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:

Copy

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

YAML Structure

Copy

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
Pack.custom_model_data
item_model

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

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