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:

Example pack structure

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

YAML Structure

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:

weapons.yml

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

Items with durability:

durable_items.yml

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

Equippable armor:

armor.yml

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

Complex example with mixed types:

mixed_examples.yml

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

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

YAML not being read

• Ensure files are in Oraxen/items/ folder

• Check that files have .yml or .yaml extension

• Verify YAML syntax is valid (use a YAML validator)

Items not mapping

• Verify material uses correct Bukkit Material names

• Check that item definition files exist in assets/<namespace>/items/

• Ensure model files are properly referenced

Model file warnings

• These are informational — mappings are still created

• Models will work if added later

• Verify your model file paths if this is unexpected

Armor not working

• Ensure Components.equippable.slot is set correctly

• Verify equipment model ID exists

• Check that item definition file matches the item key

Example Project Structure

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

Important Notes

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:

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

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