# 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//` 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 ```yaml 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` ```yaml namespace:item_key: custom_model_data_value custom:flame_sword: 1001 custom:ruby_helmet: 2000 ``` ### YAML Examples **Basic weapons and tools:** ```yaml 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:** ```yaml 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):** ```yaml 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):** ```yaml 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:** ```yaml 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//` 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//...`
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) ```yaml Components: equippable: slot: CHEST model: namespace:armor_id ``` Method 2: specific\_properties.armor (legacy) ```yaml 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: ```yaml 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pogmc.net/kafal/itemsadder-mappings.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.