# CraftEngine Mappings ## Overview CraftEngine Mappings is a mapping system for converting Java 1.21+ item model systems to Bedrock Edition. It reads item definitions from YAML configuration files with template support and generates the appropriate Geyser mappings. ## Supported Format CraftEngine Mappings uses the CraftEngine YAML configuration files with template system support. ## YAML Format ### File Location Place YAML files under `CraftEngine/resources/` within your resource pack: ``` your-pack.zip ├── CraftEngine/ │ └── resources/ │ ├── weapons.yml │ ├── armor.yml │ └── tools.yml └── assets/ └── ... ``` ### YAML Structure ```yaml templates: template_name: # Reusable template configuration settings: equipment: slot: SLOT_NAME asset-id: equipment_model_id items: namespace:item_key: material: BUKKIT_MATERIAL model: path: model_path texture: texture_path (alternative) textures: [texture_list] (alternative) template: template_name (optional) arguments: key: value (for template variables) data: custom-model-data: number (optional) max-damage: number (optional) max-stack-size: number (optional) settings: equipment: slot: SLOT_NAME asset-id: equipment_model_id ``` ### YAML Field Reference | Field | Type | Required | Description | | ----------------------------- | ------------ | -------- | ------------------------------------------------------------------------------ | | `material` | string | ✅ | Bukkit Material name (e.g., `NETHERITE_SWORD`) | | `model.path` / `model` | string | ❌ | Model file path for item definition lookup | | `texture` | string | ❌ | Single texture path (alternative to model) | | `textures` | array | ❌ | Array of texture paths (uses first for lookup) | | `template` | string/array | ❌ | Template name(s) to inherit from | | `arguments` | object | ❌ | Variables for template substitution | | `data.custom-model-data` | number | ❌ | Custom model data value | | `data.max-damage` | number | ❌ | Maximum durability for the item | | `data.max-stack-size` | number | ❌ | Maximum stack size | | `settings.equipment.slot` | string | ❌ | Equipment slot: `HEAD`, `CHEST`, `LEGS`, `FEET`, `BODY`, `MAINHAND`, `OFFHAND` | | `settings.equipment.asset-id` | string | ❌ | Equipment model ID | ### YAML Examples **Basic weapons and tools:** ```yaml items: default:excalibur: material: NETHERITE_SWORD model: path: weapons/excalibur default:drill: material: DIAMOND_PICKAXE model: path: tools/drill data: max-damage: 2000 custom:crossbow_heavy: material: BOW texture: weapons/crossbow_heavy ``` **Using templates:** ```yaml templates: basic_armor: data: max-damage: 500 settings: equipment: slot: ${slot} asset-id: ${armor_set} items: armor:knight_helmet: material: DIAMOND_HELMET template: basic_armor arguments: slot: HEAD armor_set: knight model: path: armor/knight/helmet armor:knight_chestplate: material: DIAMOND_CHESTPLATE template: basic_armor arguments: slot: CHEST armor_set: knight model: path: armor/knight/chestplate ``` **Multiple templates:** ```yaml templates: durable: data: max-damage: 2000 equippable_chest: settings: equipment: slot: CHEST items: custom:reinforced_chestplate: material: DIAMOND_CHESTPLATE template: [durable, equippable_chest] settings: equipment: asset-id: reinforced model: path: armor/reinforced/chestplate ``` **Using textures instead of models:** ```yaml items: default:ruby_gem: material: PAPER texture: items/ruby_gem data: custom-model-data: 1000 default:sapphire_gem: material: PAPER textures: - items/sapphire_gem - items/sapphire_gem_glowing data: custom-model-data: 1001 ``` **Complex example with mixed types:** ```yaml templates: legendary_weapon: data: max-damage: 3000 max-stack-size: 1 items: legendary:excalibur: material: NETHERITE_SWORD template: legendary_weapon model: path: legendary/weapons/excalibur data: custom-model-data: 5000 armor:sapphire_chestplate: material: DIAMOND_CHESTPLATE model: path: armor/sapphire/chestplate data: max-damage: 1000 custom-model-data: 2000 settings: equipment: slot: CHEST asset-id: sapphire magic:wand: material: STICK texture: magic/wands/fire data: max-damage: 100 max-stack-size: 1 ``` ## Item Key Format Item keys in CraftEngine use the format `namespace:item_key`: Examples: * `default:bench` → namespace: `default`, item: `bench` * `custom:ruby_sword` → namespace: `custom`, item: `ruby_sword` * `armor:knight_helmet` → namespace: `armor`, item: `knight_helmet` The namespace is extracted from the item key and used for item definition resolution. ## Item Definition Resolution CraftEngine resolves item definitions in the following priority. {% stepper %} {% step %} ### model.path Extracts basename from model path. * Example: ```yaml default:knight_helmet: material: DIAMOND_HELMET model: path: armor/knight/helmet ``` → Extracts basename: `helmet` → Looks for: `assets/default/items/helmet.json` {% endstep %} {% step %} ### texture Uses texture path basename. * Example: ```yaml custom:ruby: material: PAPER texture: items/ruby_gem ``` → Extracts basename: `ruby_gem` → Looks for: `assets/custom/items/ruby_gem.json` {% endstep %} {% step %} ### textures\[0] Uses first texture path basename. {% endstep %} {% step %} ### item\_key Uses the item key directly as a last resort. {% endstep %} {% endstepper %} Namespace handling: * Namespace from item key (e.g., `default:bench` → `default`) * Falls back to `minecraft` if not found in preferred namespace * Searches all namespaces as last resort ## Template System CraftEngine supports a powerful template system with variable substitution. ### Template Features Basic inheritance: ```yaml templates: durable: data: max-damage: 2000 items: default:strong_sword: template: durable material: IRON_SWORD ``` Multiple templates: ```yaml items: default:item: template: [template1, template2] ``` Templates are applied in order, with later values overriding earlier ones. Variable substitution: ```yaml templates: armor_piece: settings: equipment: slot: ${slot} asset-id: ${set_name} items: armor:helmet: template: armor_piece arguments: slot: HEAD set_name: knight ``` Variables use `${variable_name}` syntax and are replaced with values from `arguments`. Nested templates: * Templates can reference other templates, with circular reference protection. ## Material Names Use standard Bukkit Material enum names for `material`. Common materials: * Swords: `WOODEN_SWORD`, `STONE_SWORD`, `IRON_SWORD`, `GOLDEN_SWORD`, `DIAMOND_SWORD`, `NETHERITE_SWORD` * Tools: `WOODEN_PICKAXE`, `STONE_AXE`, `IRON_SHOVEL`, `DIAMOND_HOE`, etc. * Armor: `LEATHER_HELMET`, `CHAINMAIL_CHESTPLATE`, `IRON_LEGGINGS`, `DIAMOND_BOOTS`, etc. * Ranged: `BOW`, `CROSSBOW`, `TRIDENT` * Other: `STICK`, `FISHING_ROD`, `SHIELD`, `ELYTRA`, `PAPER`, `CARROT_ON_A_STICK` Note: Legacy material names (e.g., `LEGACY_IRON_SWORD`) are automatically cleaned. ## Equipment Slots When using `settings.equipment.slot`: | 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 ### Common Issues **YAML not being read:** * Ensure files are under `CraftEngine/resources/` directory * Check that files have `.yml` or `.yaml` extension * Verify YAML syntax is valid (use a YAML validator) **Template variables not working:** * Check variable syntax: `${variable_name}` * Ensure `arguments` field is defined with matching keys * Verify template is referenced correctly **Template not found:** * Confirm template name matches exactly (case-sensitive) * Ensure template is defined in `templates:` section * Check for typos in template references **Items not mapping:** * Verify `material` uses correct Bukkit Material names * Check that model/texture paths are specified * Ensure namespace is included in item key * Verify item definition files exist **Namespace not detected:** * Include namespace in item key: `namespace:item_key` * Check for colon separator in key **Armor not working:** * Ensure `settings.equipment.slot` is set * Verify `asset-id` is specified * Check that equipment model exists * Confirm item definition matches configuration ## Example Project Structure ``` craftengine-pack.zip ├── CraftEngine/ │ └── resources/ │ ├── weapons.yml │ ├── armor.yml │ └── tools.yml ├── assets/ │ ├── default/ │ │ ├── models/ │ │ │ └── item/ │ │ │ ├── excalibur.json │ │ │ └── drill.json │ │ ├── items/ │ │ │ ├── excalibur.json │ │ │ └── drill.json │ │ └── textures/ │ │ └── item/ │ │ ├── excalibur.png │ │ └── drill.png │ └── minecraft/ │ └── ... └── pack.mcmeta ``` ## Important Notes ### Item Key Namespace The namespace in the item key (e.g., `default:bench`) determines the preferred namespace for item definition lookup. This allows organizing items by namespace while using centralized YAML files. ### Template Inheritance Templates provide powerful reusability: * Define common properties once * Apply to multiple items * Override specific fields per item * Use variable substitution for flexibility ### Model vs Texture CraftEngine supports multiple ways to specify models: * `model.path` or `model` - Direct model path * `texture` - Single texture path * `textures` - Array of textures (uses first) All three methods extract a basename for item definition lookup. ### Equipment Configuration Use `settings.equipment` for armor items: * `slot` - Where the item is equipped * `asset-id` - The equipment model ID The asset-id can include namespace: `namespace:model_id` ### Durability vs Max Stack Size * Items with equipment automatically have `max_stack_size: 1` * Non-equipment items can have custom `max_stack_size` * Durability is specified in `data.max-damage` --- # 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/craftengine-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.