> 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/nexo-mappings.md).
# 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
```yaml
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:
```yaml
excalibur:
material: NETHERITE_SWORD
drill:
material: DIAMOND_PICKAXE
Components:
durability: 2000
crossbow_heavy:
material: BOW
Pack:
custom_model_data: 1001
```
Items with durability:
```yaml
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:
```yaml
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:
```yaml
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//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:
```yaml
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