# 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.
---
# 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/kafal-items-mappings.md?ask=
```
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.