Nexo Mappings

Overview

Nexo Mappings 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

Nexo mappings uses the Nexo plugin YAML configuration files only.

YAML Format

File Location

Place YAML files in the Nexo/items/ folder (or any subfolder) within your resource pack:

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

YAML Structure

item_key:
  material: BUKKIT_MATERIAL
  Pack:
    custom_model_data: number (optional)
  item_model: item_definition_id (optional)
  Components:
    item_model: item_definition_id (optional)
    equippable:
      slot: SLOT_NAME
      model: equipment_model_id
      allowed_entity_types: [entity_list] (optional)
    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.custom_model_data	number	❌	Custom model data value
item_model	string	❌	Explicit item definition ID override
Components.item_model	string	❌	Item definition ID (highest priority for armor)
Components.equippable.slot	string	❌	Equipment slot: HEAD, CHEST, LEGS, FEET, MAINHAND, OFFHAND, BODY
Components.equippable.model	string	❌	Equipment model ID (e.g., nexo:ruby)
Components.equippable.allowed_entity_types	array	❌	List of entities that can equip (e.g., [player, zombie])
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:

excalibur:
  material: NETHERITE_SWORD

drill:
  material: DIAMOND_PICKAXE
  Components:
    durability: 2000

crossbow_heavy:
  material: BOW
  Pack:
    custom_model_data: 1001

Items with durability:

flame_blade:
  material: GOLDEN_SWORD
  Pack:
    custom_model_data: 500
  Components:
    durability: 500
    max_stack_size: 1

magic_wand:
  material: STICK
  Components:
    durability: 100
    max_stack_size: 1

Equippable armor:

ruby_helmet:
  material: DIAMOND_HELMET
  Components:
    item_model: nexo:ruby_helmet
    equippable:
      slot: HEAD
      model: nexo:ruby
    durability: 500

ruby_chestplate:
  material: DIAMOND_CHESTPLATE
  Pack:
    custom_model_data: 200
  Components:
    item_model: nexo:ruby_chestplate
    equippable:
      slot: CHEST
      model: nexo:ruby
    durability: 800

knight_helmet:
  material: LEATHER_HELMET
  Components:
    equippable:
      slot: HEAD
      model: minecraft:knight
      allowed_entity_types: [player, zombie]
    durability: 300

Complex example with mixed types:

legendary_sword:
  material: NETHERITE_SWORD
  Pack:
    custom_model_data: 1000
  Components:
    durability: 3000

sapphire_chestplate:
  material: DIAMOND_CHESTPLATE
  Components:
    item_model: nexo:sapphire_chestplate
    equippable:
      slot: CHEST
      model: nexo:sapphire
      allowed_entity_types: [player]
    durability: 1000

enchanted_bow:
  material: BOW
  Pack:
    custom_model_data: 2000
  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
BODY	Body equipment (horse armor, wolf armor)
MAINHAND	Main hand equipment
OFFHAND	Off-hand equipment

Troubleshooting

YAML not being read

• Ensure files are in Nexo/items/ folder or subfolders

• 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.item_model is set for armor items

• Verify Components.equippable.slot is set correctly

• Check that equipment model ID exists

• Confirm item definition file matches the specified model

Example Project Structure

nexo-pack.zip
├── Nexo/
│   └── items/
│       ├── weapons.yml
│       ├── armor.yml
│       └── tools.yml
├── assets/
│   ├── nexo/
│   │   ├── models/
│   │   │   ├── item/
│   │   │   │   ├── excalibur.json
│   │   │   │   └── drill.json
│   │   │   └── armor/
│   │   │       └── ruby/
│   │   │           ├── helmet.json
│   │   │           └── chestplate.json
│   │   ├── items/
│   │   │   ├── excalibur.json
│   │   │   ├── ruby_helmet.json
│   │   │   └── ruby_chestplate.json
│   │   └── textures/
│   │       └── item/
│   │           ├── excalibur.png
│   │           └── drill.png
│   └── minecraft/
│       └── ...
└── pack.mcmeta

Important Notes

Armor Configuration

For armor items, use Components.item_model to specify the item definition ID. This has the highest priority and is specifically designed for armor and special items.

Example:

ruby_chestplate:
  material: DIAMOND_CHESTPLATE
  Components:
    item_model: nexo:ruby_chestplate  # Item definition ID
    equippable:
      slot: CHEST
      model: nexo:ruby  # Equipment model (separate from item def)

→ Item definition: assets/nexo/items/ruby_chestplate.json → Equipment model: Referenced in the equippable component

Entity types are automatically prefixed with minecraft:.

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 can be specified as a number or in durability.value format