# 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`