# 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

<details>

<summary>YAML not being read</summary>

* 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)

</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.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

</details>

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


---

# 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/nexo-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.