> 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/kafal-items-mappings.md).
# Kafal Items Mappings
## Overview
Kafal-Items is a mapping system for converting Java 1.21+ item model systems to Bedrock Edition. It reads item definitions from either CSV files or a JSON configuration and generates the appropriate Geyser mappings.
## Supported Formats
Kafal-Items supports two input formats:
* CSV files — Simple, spreadsheet-friendly format
* JSON configuration — Advanced format with additional options
## CSV Format
### File Location
Place CSV files in a `csv/` folder within your resource pack:
```
your-pack.zip
├── csv/
│ ├── weapons.csv
│ ├── armor.csv
│ └── tools.csv
└── assets/
└── ...
```
### CSV Structure
Columns (in order):
```csv
namespace,base_item,item_id,custom_model_data
```
| Column | Description | Example |
| ------------------- | ------------------------------ | ------------------------------------------ |
| `namespace` | Resource pack namespace | `netherite`, `custom`, `mypack` |
| `base_item` | Bukkit Material name | `NETHERITE_SWORD`, `BOW`, `DIAMOND_HELMET` |
| `item_id` | Model or item definition path | `netherite:skins/knight/bow` |
| `custom_model_data` | CMD value (for reference only) | `1001`, `2050` |
### CSV Examples
Basic weapons and tools:
```csv
namespace,base_item,item_id,custom_model_data
netherite,NETHERITE_SWORD,netherite:weapons/excalibur,1001
netherite,DIAMOND_PICKAXE,netherite:tools/drill,1002
custom,BOW,custom:weapons/crossbow_heavy,2000
mypack,GOLDEN_SWORD,mypack:swords/flame_blade,3000
```
Multiple files approach:
`csv/weapons.csv`:
```csv
namespace,base_item,item_id,custom_model_data
combat,NETHERITE_SWORD,combat:swords/katana,100
combat,BOW,combat:bows/longbow,101
combat,CROSSBOW,combat:crossbows/repeater,102
```
`csv/armor.csv`:
```csv
namespace,base_item,item_id,custom_model_data
armor,DIAMOND_HELMET,armor:sets/knight/helmet,200
armor,DIAMOND_CHESTPLATE,armor:sets/knight/chestplate,201
armor,DIAMOND_LEGGINGS,armor:sets/knight/leggings,202
```
### Important CSV Notes
{% hint style="info" %}
* Header row required: The first row must contain the column names
* Custom Model Data: This value is for documentation/reference only. The actual CMD is stored in your Java item model definition files
* Order matters: Columns must be in the exact order shown above
{% endhint %}
## JSON Format
### File Location
Place a single `kafal-items.json` file in the root of your resource pack:
```
your-pack.zip
├── kafal-items.json
└── assets/
└── ...
```
### JSON Structure
```json
{
"items": [
{
"baseItem": "string",
"itemId": "string",
"equipmentId": "string (optional)",
"equipmentSlot": "string (optional)",
"equipmentNamespace": "string (optional)",
"maxDamage": number (optional),
"maxStackSize": number (optional)
}
]
}
```
### JSON Field Reference
| Field | Type | Required | Description |
| -------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `baseItem` | string | ✅ | Bukkit Material name (e.g., `NETHERITE_SWORD`) |
| `itemId` | string | ✅ | Model path or item definition path |
| `equipmentId` | string | ❌ | Equipment model ID for equippable items |
| `equipmentSlot` | string | ❌ | Equipment slot: `head`, `chest`, `legs`, `feet`, `mainhand`, `offhand` |
| `equipmentNamespace` | string | ❌ | Namespace for equipment (defaults to `minecraft`) |
| `maxDamage` | number | ❌ | Maximum durability for the item |
| `maxStackSize` | number | ❌ | Maximum stack size (auto-set to 1 for equippable items) |
### JSON Examples
Basic items:
```json
{
"items": [
{
"baseItem": "NETHERITE_SWORD",
"itemId": "netherite:weapons/excalibur"
},
{
"baseItem": "BOW",
"itemId": "custom:weapons/crossbow_heavy"
}
]
}
```
Items with durability:
```json
{
"items": [
{
"baseItem": "DIAMOND_PICKAXE",
"itemId": "tools:mining/drill",
"maxDamage": 2000
},
{
"baseItem": "GOLDEN_SWORD",
"itemId": "weapons:flame_blade",
"maxDamage": 500
}
]
}
```
Equippable armor:
```json
{
"items": [
{
"baseItem": "DIAMOND_HELMET",
"itemId": "armor:knight/helmet",
"equipmentId": "knight_helmet",
"equipmentSlot": "head",
"equipmentNamespace": "armor",
"maxDamage": 500,
"maxStackSize": 1
},
{
"baseItem": "DIAMOND_CHESTPLATE",
"itemId": "armor:knight/chestplate",
"equipmentId": "knight_chestplate",
"equipmentSlot": "chest",
"equipmentNamespace": "armor",
"maxDamage": 800
}
]
}
```
Complex example with mixed types:
```json
{
"items": [
{
"baseItem": "NETHERITE_SWORD",
"itemId": "legendary:excalibur",
"maxDamage": 3000
},
{
"baseItem": "DIAMOND_HELMET",
"itemId": "armor:sets/knight/helmet",
"equipmentId": "knight_helmet",
"equipmentSlot": "head",
"equipmentNamespace": "armor",
"maxDamage": 500
},
{
"baseItem": "STICK",
"itemId": "magic:wands/fire",
"maxStackSize": 1,
"maxDamage": 100
}
]
}
```
## Item ID Resolution
The `itemId` field supports two strategies:
Direct Model Path (Most Common)\
Points directly to a model file location:
```
itemId: "netherite:skins/knight/bow"
→ Looks for: assets/netherite/models/skins/knight/bow.json
```
Item Definition Path\
References an item definition file that contains the model reference:
```
itemId: "netherite:knight_bow"
→ Looks for: assets/netherite/items/knight_bow.json
→ Reads the "model" field from that file
```
## Material Names
Use standard Bukkit Material enum names for `baseItem`:
Common materials:
* Swords: `WOODEN_SWORD`, `STONE_SWORD`, `IRON_SWORD`, `GOLDEN_SWORD`, `DIAMOND_SWORD`, `NETHERITE_SWORD`
* Tools: `WOODEN_PICKAXE`, `STONE_AXE`, `IRON_SHOVEL`, `DIAMOND_HOE`, etc.
* Armor: `LEATHER_HELMET`, `CHAINMAIL_CHESTPLATE`, `IRON_LEGGINGS`, `DIAMOND_BOOTS`, etc.
* Ranged: `BOW`, `CROSSBOW`, `TRIDENT`
* Other: `STICK`, `FISHING_ROD`, `SHIELD`, `ELYTRA`, `CARROT_ON_A_STICK`
Note: Legacy material names (e.g., `LEGACY_IRON_SWORD`) are automatically cleaned.
## Equipment Slots
When using `equipmentSlot` for equippable items:
| Slot | Usage |
| ---------- | ----------------------------- |
| `head` | Helmets, hats, crowns |
| `chest` | Chestplates, tunics |
| `legs` | Leggings, pants |
| `feet` | Boots, shoes |
| `mainhand` | Main hand equipment (default) |
| `offhand` | Off-hand equipment |
## Troubleshooting
CSV not being read
* Ensure files are in `csv/` folder
* Check that files have `.csv` extension
* Verify header row matches exactly: `namespace,base_item,item_id,custom_model_data`
Items not mapping
* Verify `baseItem` uses correct Bukkit Material names
* Check that `itemId` points to valid model or item definition
* Ensure namespace in `itemId` matches your pack structure
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
## Example Project Structure
```
custom-items-pack.zip
├── kafal-items.json (OR csv/ folder)
├── csv/
│ ├── weapons.csv
│ ├── armor.csv
│ └── tools.csv
├── assets/
│ ├── custom/
│ │ ├── models/
│ │ │ ├── item/
│ │ │ │ └── flame_blade.json
│ │ │ └── weapons/
│ │ │ └── excalibur.json
│ │ ├── items/
│ │ │ └── knight_bow.json
│ │ └── textures/
│ │ └── item/
│ │ ├── flame_blade.png
│ │ └── excalibur.png
│ └── minecraft/
│ └── ...
└── pack.mcmeta
```
If you want, I can also:
* Convert any CSV examples into separate step-by-step import instructions, or
* Add a ready-to-copy sample `kafal-items.json` file for a specific use case.