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

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:

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:

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:

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:

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:

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.

1

model.path

Extracts basename from model path.

• Example:

default:knight_helmet:
  material: DIAMOND_HELMET
  model:
    path: armor/knight/helmet

→ Extracts basename: helmet → Looks for: assets/default/items/helmet.json

2

texture

Uses texture path basename.

• Example:

custom:ruby:
  material: PAPER
  texture: items/ruby_gem

→ Extracts basename: ruby_gem → Looks for: assets/custom/items/ruby_gem.json

3

textures[0]

Uses first texture path basename.

4

item_key

Uses the item key directly as a last resort.

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:

templates:
  durable:
    data:
      max-damage: 2000

items:
  default:strong_sword:
    template: durable
    material: IRON_SWORD

Multiple templates:

items:
  default:item:
    template: [template1, template2]

Templates are applied in order, with later values overriding earlier ones.

Variable substitution:

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