Kafal Items Mappings

Support for Item Models without Nexo, Oraxen or ItemsAdder

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

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:

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:

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:

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

• 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

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

{
  "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:

{
  "items": [
    {
      "baseItem": "NETHERITE_SWORD",
      "itemId": "netherite:weapons/excalibur"
    },
    {
      "baseItem": "BOW",
      "itemId": "custom:weapons/crossbow_heavy"
    }
  ]
}

Items with durability:

{
  "items": [
    {
      "baseItem": "DIAMOND_PICKAXE",
      "itemId": "tools:mining/drill",
      "maxDamage": 2000
    },
    {
      "baseItem": "GOLDEN_SWORD",
      "itemId": "weapons:flame_blade",
      "maxDamage": 500
    }
  ]
}

Equippable armor:

{
  "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:

{
  "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.