# 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 %}


---

# 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/oraxen-mappings.md?ask=<question>
```

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.