> For the complete documentation index, see [llms.txt](https://docs.pogmc.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pogmc.net/kafal/oraxen-mappings.md).

# Oraxen Mappings

## Overview

Oraxen 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.

## Supported Format

Oraxen Mappings uses the Oraxen Plugin YAML configuration files only.

## YAML Format

### File Location

Place YAML files in the `Oraxen/items/` folder within your resource pack:

{% code title="Example pack structure" %}

```
your-pack.zip
├── Oraxen/
│   └── items/
│       ├── weapons.yml
│       ├── armor.yml
│       └── tools.yml
└── assets/
    └── ...
```

{% endcode %}

### YAML Structure

```yaml
item_key:
  material: BUKKIT_MATERIAL
  Pack:
    model: model_path (optional)
    item_model: item_definition_id (optional)
  Components:
    equippable:
      slot: SLOT_NAME
      model: equipment_model_id
    max_stack_size: number (optional)
    durability: number (optional)
```

### YAML Field Reference

| Field                         | Type   | Required | Description                                                            |
| ----------------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `material`                    | string | ✅        | Bukkit Material name (e.g., `NETHERITE_SWORD`)                         |
| `Pack.model`                  | string | ❌        | Model file path hint for item definition lookup                        |
| `Pack.item_model`             | string | ❌        | Explicit item definition ID override                                   |
| `Components.equippable.slot`  | string | ❌        | Equipment slot: `HEAD`, `CHEST`, `LEGS`, `FEET`, `MAINHAND`, `OFFHAND` |
| `Components.equippable.model` | string | ❌        | Equipment model ID (e.g., `oraxen:emerald`)                            |
| `Components.max_stack_size`   | number | ❌        | Maximum stack size (auto-set to 1 for equippable items)                |
| `Components.durability`       | number | ❌        | Maximum durability for the item                                        |

### YAML Examples

Basic weapons and tools:

{% code title="weapons.yml" %}

```yaml
excalibur:
  material: NETHERITE_SWORD
  Pack:
    model: weapons/excalibur

drill:
  material: DIAMOND_PICKAXE
  Pack:
    model: tools/drill
  Components:
    durability: 2000

crossbow_heavy:
  material: BOW
  Pack:
    model: weapons/crossbow_heavy
```

{% endcode %}

Items with durability:

{% code title="durable\_items.yml" %}

```yaml
flame_blade:
  material: GOLDEN_SWORD
  Pack:
    model: weapons/flame_blade
  Components:
    durability: 500
    max_stack_size: 1

magic_wand:
  material: STICK
  Pack:
    model: magic/wands/fire
  Components:
    durability: 100
    max_stack_size: 1
```

{% endcode %}

Equippable armor:

{% code title="armor.yml" %}

```yaml
emerald_helmet:
  material: DIAMOND_HELMET
  Pack:
    model: armor/emerald/helmet
  Components:
    equippable:
      slot: HEAD
      model: oraxen:emerald
    durability: 500

emerald_chestplate:
  material: DIAMOND_CHESTPLATE
  Pack:
    model: armor/emerald/chestplate
  Components:
    equippable:
      slot: CHEST
      model: oraxen:emerald
    durability: 800

knight_helmet:
  material: LEATHER_HELMET
  Components:
    equippable:
      slot: HEAD
      model: minecraft:knight
    durability: 300
```

{% endcode %}

Complex example with mixed types:

{% code title="mixed\_examples.yml" %}

```yaml
legendary_sword:
  material: NETHERITE_SWORD
  Pack:
    model: legendary/excalibur
  Components:
    durability: 3000

ruby_chestplate:
  material: DIAMOND_CHESTPLATE
  Components:
    equippable:
      slot: CHEST
      model: oraxen:ruby
    durability: 1000

enchanted_bow:
  material: BOW
  Pack:
    model: weapons/enchanted_bow
  Components:
    durability: 800
    max_stack_size: 1
```

{% endcode %}

## Equipment Slots

When using `Components.equippable.slot` for armor:

| Slot       | Usage                 |
| ---------- | --------------------- |
| `HEAD`     | Helmets, hats, crowns |
| `CHEST`    | Chestplates, tunics   |
| `LEGS`     | Leggings, pants       |
| `FEET`     | Boots, shoes          |
| `MAINHAND` | Main hand equipment   |
| `OFFHAND`  | Off-hand equipment    |

## Troubleshooting

<details>

<summary>YAML not being read</summary>

* Ensure files are in `Oraxen/items/` folder
* Check that files have `.yml` or `.yaml` extension
* Verify YAML syntax is valid (use a YAML validator)

</details>

<details>

<summary>Items not mapping</summary>

* Verify `material` uses correct Bukkit Material names
* Check that item definition files exist in `assets/<namespace>/items/`
* Ensure model files are properly referenced

</details>

<details>

<summary>Model file warnings</summary>

* These are informational — mappings are still created
* Models will work if added later
* Verify your model file paths if this is unexpected

</details>

<details>

<summary>Armor not working</summary>

* Ensure `Components.equippable.slot` is set correctly
* Verify equipment model ID exists
* Check that item definition file matches the item key

</details>

## Example Project Structure

{% code title="oraxen-pack.zip layout" %}

```
oraxen-pack.zip
├── Oraxen/
│   └── items/
│       ├── weapons.yml
│       ├── armor.yml
│       └── tools.yml
├── assets/
│   ├── oraxen/
│   │   ├── models/
│   │   │   ├── item/
│   │   │   │   ├── excalibur.json
│   │   │   │   └── drill.json
│   │   │   └── armor/
│   │   │       └── emerald/
│   │   │           ├── helmet.json
│   │   │           └── chestplate.json
│   │   ├── items/
│   │   │   ├── excalibur.json
│   │   │   ├── emerald_helmet.json
│   │   │   └── emerald_chestplate.json
│   │   └── textures/
│   │       └── item/
│   │           ├── excalibur.png
│   │           └── drill.png
│   └── minecraft/
│       └── ...
└── pack.mcmeta
```

{% endcode %}

## Important Notes

{% hint style="info" %}
For armor items, the item key (e.g., `emerald_chestplate`) determines the item definition ID, not the `Components.equippable.model` field. The equippable model is used as a component in the mapping, but the actual item definition comes from the item key.

Example:

```yaml
emerald_chestplate:
  Components:
    equippable:
      model: oraxen:emerald  # This is the equipment model, not the item def
```

* Item definition: `assets/oraxen/items/emerald_chestplate.json`
* Equipment model: referenced in the equippable component
  {% endhint %}

{% hint style="info" %}
Durability vs Max Stack Size:

* Items with `Components.equippable` automatically have `max_stack_size: 1`
* Non-equippable items can have custom `max_stack_size`
* Durability is converted to the `minecraft:max_damage` component
  {% endhint %}