ItemsAdder Mappings

Overview

ItemsAdder Mappings is a mapping system for converting Java 1.21+ item model systems to Bedrock Edition. It reads item definitions from YAML configuration files and generates the appropriate Geyser mappings. It also supports custom model data caching for proper CMD value tracking.

Supported Format

ItemsAdder Mappings uses the ItemsAdder YAML configuration files only.

YAML Format

File Location

Place YAML files anywhere under ItemsAdder/contents/<namespace>/ within your resource pack:

your-pack.zip
├── ItemsAdder/
│   ├── contents/
│   │   ├── mynamespace/
│   │   │   ├── weapons.yml
│   │   │   ├── armor.yml
│   │   │   └── tools.yml
│   │   └── custom/
│   │       └── items.yml
│   └── storage/
│       └── item_ids_cache.yml
└── assets/
    └── ...

YAML Structure

info:
  namespace: your_namespace

items:
  item_key:
    resource:
      material: BUKKIT_MATERIAL
      model_path: model_path
    Components:
      max_stack_size: number (optional)
      durability: number (optional)
      equippable:
        slot: SLOT_NAME
        model: equipment_model_id
        allowed_entity_types: [entity_list] (optional)
    specific_properties:
      armor:
        slot: SLOT_NAME
        custom_armor: armor_model_id
    behaviours:
      armor: true/false

YAML Field Reference

Field	Type	Required	Description
info.namespace	string	❌	Namespace for items (auto-detected from directory if missing)
resource.material	string	✅	Bukkit Material name (e.g., NETHERITE_SWORD)
resource.model_path	string	✅	Model path (can be nested like santa_decoration/big_gift_box)
Components.equippable.slot	string	❌	Equipment slot: HEAD, CHEST, LEGS, FEET, MAINHAND, OFFHAND, BODY
Components.equippable.model	string	❌	Equipment model ID (with namespace)
Components.equippable.allowed_entity_types	array	❌	List of entities that can equip
Components.max_stack_size	number	❌	Maximum stack size (auto-set to 1 for equippable items)
Components.durability	number	❌	Maximum durability for the item
specific_properties.armor.slot	string	❌	Armor slot (alternative to Components.equippable)
specific_properties.armor.custom_armor	string	❌	Custom armor model ID
behaviours.armor	boolean	❌	Indicates if item is armor

Custom Model Data Cache

ItemsAdder uses a cache file for custom model data values:

File: ItemsAdder/storage/item_ids_cache.yml

namespace:item_key: custom_model_data_value
custom:flame_sword: 1001
custom:ruby_helmet: 2000

YAML Examples

Basic weapons and tools:

info:
  namespace: custom

items:
  excalibur:
    resource:
      material: NETHERITE_SWORD
      model_path: weapons/excalibur
  
  drill:
    resource:
      material: DIAMOND_PICKAXE
      model_path: tools/drill
    Components:
      durability: 2000
  
  crossbow_heavy:
    resource:
      material: BOW
      model_path: weapons/crossbow_heavy

Items with nested model paths:

info:
  namespace: christmas

items:
  big_gift_box:
    resource:
      material: PAPER
      model_path: santa_decoration/big_gift_box
  
  small_gift:
    resource:
      material: PAPER
      model_path: santa_decoration/gifts/small

Equippable armor (using Components):

info:
  namespace: armor

items:
  ruby_helmet:
    resource:
      material: DIAMOND_HELMET
      model_path: ruby_helmet
    Components:
      equippable:
        slot: HEAD
        model: armor:ruby
      durability: 500
  
  ruby_chestplate:
    resource:
      material: DIAMOND_CHESTPLATE
      model_path: ruby_chestplate
    Components:
      equippable:
        slot: CHEST
        model: armor:ruby
        allowed_entity_types: [player, zombie]
      durability: 800

Equippable armor (using specific_properties):

info:
  namespace: custom

items:
  emerald_helmet:
    resource:
      material: DIAMOND_HELMET
      model_path: armor/emerald/helmet
    specific_properties:
      armor:
        slot: HEAD
        custom_armor: emerald
    behaviours:
      armor: true
  
  emerald_chestplate:
    resource:
      material: DIAMOND_CHESTPLATE
      model_path: armor/emerald/chestplate
    specific_properties:
      armor:
        slot: CHEST
        custom_armor: emerald
    behaviours:
      armor: true

Complex example with mixed types:

info:
  namespace: legendary

items:
  legendary_sword:
    resource:
      material: NETHERITE_SWORD
      model_path: weapons/legendary/excalibur
    Components:
      durability: 3000
  
  sapphire_chestplate:
    resource:
      material: DIAMOND_CHESTPLATE
      model_path: armor/sapphire/chestplate
    Components:
      equippable:
        slot: CHEST
        model: legendary:sapphire
      durability: 1000
  
  magic_wand:
    resource:
      material: STICK
      model_path: magic/wands/fire
    Components:
      durability: 100
      max_stack_size: 1

Equipment Slots

Slot	Usage
HEAD	Helmets, hats, crowns
CHEST	Chestplates, tunics
LEGS	Leggings, pants
FEET	Boots, shoes
BODY	Body equipment (horse armor, wolf armor)
MAINHAND	Main hand equipment
OFFHAND	Off-hand equipment

Troubleshooting

YAML not being read

• Ensure files are under ItemsAdder/contents/<namespace>/ directory

• Check that files have .yml or .yaml extension

• Verify YAML syntax is valid (use a YAML validator)

• Ensure files are not in categories/ folder (automatically skipped)

Namespace not detected

• Add info.namespace to YAML file

• Ensure directory structure follows ItemsAdder/contents/<namespace>/...

Items not mapping

• Verify resource.material uses correct Bukkit Material names

• Check that resource.model_path is specified

• Ensure item definition files exist

• Try both simple and nested model path formats

Nested model paths not working

• Verify basename exists: santa_decoration/big_gift_box → big_gift_box.json

• Try underscore format: santa_decoration_big_gift_box.json

• Check if full path exists: santa_decoration/big_gift_box.json

Custom model data missing

• Check if item_ids_cache.yml exists

• Verify cache format: namespace:item_key: cmd_value

• Ensure namespace matches item configuration

Armor not working

• Set either Components.equippable OR specific_properties.armor

• Verify slot is set correctly

• Check that equipment model ID exists

• Confirm armor model path exists

Example Project Structure

itemsadder-pack.zip
├── ItemsAdder/
│   ├── contents/
│   │   ├── custom/
│   │   │   ├── weapons.yml
│   │   │   └── armor.yml
│   │   └── christmas/
│   │       └── decorations.yml
│   └── storage/
│       └── item_ids_cache.yml
├── assets/
│   ├── itemsadder/
│   │   ├── models/
│   │   │   └── item/
│   │   │       ├── excalibur.json
│   │   │       └── big_gift_box.json
│   │   ├── items/
│   │   │   ├── excalibur.json
│   │   │   └── big_gift_box.json
│   │   └── textures/
│   │       └── item/
│   │           ├── excalibur.png
│   │           └── big_gift_box.png
│   └── minecraft/
│       └── ...
└── pack.mcmeta

Important Notes

Armor Configuration Methods

ItemsAdder supports two methods for armor configuration:

Method 1: Components.equippable (modern)

Components:
  equippable:
    slot: CHEST
    model: namespace:armor_id

Method 2: specific_properties.armor (legacy)

specific_properties:
  armor:
    slot: CHEST
    custom_armor: armor_id

Both methods work, but Components.equippable is preferred for new configurations.

Entity Restrictions

Use allowed_entity_types to restrict which entities can equip armor:

Components:
  equippable:
    allowed_entity_types: [player, zombie, skeleton]

Entity types are automatically prefixed with minecraft:.

Durability vs Max Stack Size

• Items with armor configuration automatically have max_stack_size: 1

• Non-armor items can have custom max_stack_size

• Durability can be specified as a number or in nested format