# PogMC Developments

Welcome to PogMC Developments!

We create custom minecraft plugins and websites for you!

***

{% content-ref url="/pages/qRUh1gY5SS8YLPk8T5Cy" %}
[Plugins](/plugins/ultracollections)
{% endcontent-ref %}

{% content-ref url="/pages/orhG37LeSTzkzXl4rP99" %}
[Websites](/blockbase/blockbase)
{% endcontent-ref %}


# UltraCollections

https\://builtbybit.com/resources/ultracollections-hypixel-style.51098/

Welcome to the UltraCollections wiki, below you can find several links to help you!

* [Commands & Permissions](/plugins/ultracollections/commands-and-permissions)
* [Features](/plugins/ultracollections/features)
* [Understanding the config](/plugins/ultracollections/understanding-the-config)
* [How to create a collection](/plugins/ultracollections/how-to-create-a-collection)
* [How to create a category](/plugins/ultracollections/how-to-create-a-category)
* [How the GUI system works](/plugins/ultracollections/how-the-gui-system-works)
* [How to create a reward GUI](/plugins/ultracollections/how-to-create-a-reward-gui)

## Discord

Join our discord - <https://discord.gg/6CARCghy3m>


# Features

**UltraCollections 1.0**

* Create unlimited collections & categories for collections (Each is a different file ofc)
* Features 2 collection modes, breaking blocks and picking up items
* Set collection to any item using a ingame command, items with any lore, custom model data... are supported.
* SQLite & MySQL support, MySQL can sync collection data between multiple servers
* You can configure the level items (for example green glass pane when completing a collection level) to run commands or open guis within the collections plugin.
* You can easily create rewards GUIs by creating a new file, then from ingame you can add items to the gui with a command. You could add a helmet, chestplate, leggings and boots, then add commands to those items to open their crafting recipes.
* There's commands such as addxp, setxp, resetcollection & reset to reset player
* Features a wiki explaining everything
* Has anti exploits, blocks thrown by players or placed by players will not count towards collections.
* Set commands to run when people level up (Player or Console commands)
* Leaderboards per collection


# Understanding the config

The config is pretty straightforward, there's not much to understand.

***

This is the database configuration. You can have either SQLite or MySQL, use mysql if you want to sync the collections data across servers.

```database:
  type: sqlite # Options: mysql, sqlite
  mysql:
    host: localhost
    port: 3306
    database: your_database_name
    username: your_mysql_username
    password: your_mysql_password
  sqlite:
    path: plugins/UltraCollections/database.db
```

***

This saves the playerdata periodically. If a player leaves the server or if the server stops, the data is saved instantly to make sure its synced on other servers when using mysql.

```
save-data-every: 1200 #time in ticks, 1200 = 60 seconds
```

***

This is pretty self explanatory, if you don't want the plugin to work on a certain world, add them to the `disabled-worlds` list and if you don't want it to work in certain worldguard regions, add those worldguard regions to `disabled-worldguard-regions`

```
disabled-worlds:
  - world_2

disabled-worldguard-regions:
  - village
```


# Commands & Permissions

The current commands in the plugin are:

`/collections`

* Opens the main collections gui
* **Permission:** collection.maingui

`/collections reload`

* Reloads the plugin
* **Permission**: collections.admin.reload

`/collections addxp <player> <collection> <xp>`

* Adds xp to a player's collection
* **Permission:** collections.admin.addxp

`/collections setxp <player> <collection> <xp>`

* Sets the xp of a player's collection to a certain amount
* **Permission:** collections.admin.setxp

`/collections opengui <player> <gui>`

* Opens any gui within the collections plugin for the specified player
* **Permission:** collections.admin.opengui

`/collections resetcollection <player> <collection>`

* Resets a certain collection completely for the specified player
* **Permission:** collections.admin.resetcollection

`/collections reset <player>`

* Resets ALL collections for a specified player
* **Permission:** collections.admin.reset

`/collections setitem <collection>`

* Sets the item used for triggering a certain collection to the item the command executor is holding.
* **Permission:** collections.admin.setitem

`/collections setreward <reward_file> <reward_name> <item_icon>`

* Adds the handheld item to the specified rewards file with the specified icon (Icon must be a single character, check GUI wiki for more info)
* **Permission:** collections.admin.setreward


# How the GUI system works

### Structure

This is the structure of your GUI. The `.` are the empty spaces, they're also the spaces where collections get added to automatically for category guis.

```
  structure:
    - "# # # # ? # # # #"
    - "# . . . . . . . #"
    - "# . . . . . . . #"
    - "# . . . . . . . #"
    - "# . . . . . . . #"
    - "# # # B C N # # #"
```

***

### Ingredients

These are the ingredients, each ingredient has an item icon which is one character, you can add this character to the structure to make the item show in that slot in the GUI.

```
  ingredients:
    filler:
      gui_item: BLACK_STAINED_GLASS_PANE
      item_icon: "#"
      item_name: "&f"
      item-lore: []
      custom_model_data: 1069
    collections_main:
      gui_item: PAINTING
      item_name: "&aCombat Collections"
      item_icon: "?"
      custom_model_data: 1069
      item-lore:
        - "&7View your combat Collections!"
    combat:
      gui_item: GOLDEN_HOE
      item_name: "&bCombat Collections"
      item_icon: "F"
      custom_model_data: 1069
      item-lore:
        - "&7View your combat collections"

    back:
      gui_item: ARROW
      item_name: "&aGo Back"
      item_icon: "B"
      custom_model_data: 1069
      item-lore:
        - "&7to the"
        - "&7previous page"
    next:
      gui_item: ARROW
      item_name: "&aNext"
      item_icon: "N"
      custom_model_data: 1069
      item-lore:
        - "&7Go to the"
        - "&7next page"

    close:
      gui_item: BARRIER
      item_name: "&cClose"
      item_icon: "C"
      item-lore: []
      actions:
        opengui: main
        play_sound:
          sound: "ENTITY_ITEM_PICKUP"
          volume: 1.0
          pitch: 1.0
```

### Actions

There is a actions system with which you can make certain items do certain things when left clicked, here are all the available actions (opengui, play\_sound, run\_command & send\_message):

```
      actions:
        opengui: main
        play_sound:
          sound: "ENTITY_ITEM_PICKUP"
          volume: 1.0
          pitch: 1.0
        send_message:
          message: You have not unlocked this yet!
        run_command:
          command: crafting open dirt_minion # example command
          as_op: true
```


# How to create a category

Its pretty easy to create a category. Navigate to `UltraCollections/gui` and in the gui folder, simply create a new yml, for example, `combat.yml`. Then, paste the code below in it, you can modify this as to your needs.

* The `category_name` is important as that is what you define in collections for them to show up in this category.

### Actions

There is a actions system with which you can make certain items do certain things when left clicked, here are all the available actions (opengui, play\_sound, run\_command & send\_message):

```
      actions:
        opengui: main
        play_sound:
          sound: "ENTITY_ITEM_PICKUP"
          volume: 1.0
          pitch: 1.0
        send_message:
          message: You have not unlocked this yet!
        run_command:
          command: crafting open dirt_minion # example command
          as_op: true
```

### combat.yml

````GUI:
  title: Combat
  category_name: combat
  structure:
    - "# # # # ? # # # #"
    - "# . . . . . . . #"
    - "# . . . . . . . #"
    - "# . . . . . . . #"
    - "# . . . . . . . #"
    - "# # # B C N # # #"

  locked_collection_gui_item:
    gui_item: gray_dye
    item_name: "&c???"
    custom_model_data: 1069
    item-lore:
      - "&7Unknown Collection"

  collection_unlocked_gui_lore:
    - '  &eProgress: {progress_percentage}'
    - '  &e{progress_bar}{currentxp}/{max_xp}'
    - '  &eRewards:'
    - '  {rewards}'
    - ''
    - '&eClick to view'

  ingredients:
    filler:
      gui_item: BLACK_STAINED_GLASS_PANE
      item_icon: "#"
      item_name: "&f"
      item-lore: []
      custom_model_data: 1069
    collections_main:
      gui_item: PAINTING
      item_name: "&aCombat Collections"
      item_icon: "?"
      custom_model_data: 1069
      item-lore:
        - "&7View your combat Collections!"
    combat:
      gui_item: GOLDEN_HOE
      item_name: "&bCombat Collections"
      item_icon: "F"
      custom_model_data: 1069
      item-lore:
        - "&7View your combat collections"

    back:
      gui_item: ARROW
      item_name: "&aGo Back"
      item_icon: "B"
      custom_model_data: 1069
      item-lore:
        - "&7to the"
        - "&7previous page"
    next:
      gui_item: ARROW
      item_name: "&aNext"
      item_icon: "N"
      custom_model_data: 1069
      item-lore:
        - "&7Go to the"
        - "&7next page"

    close:
      gui_item: BARRIER
      item_name: "&cClose"
      item_icon: "C"
      item-lore: []
      actions:
        opengui: main
        play_sound:
          sound: "ENTITY_ITEM_PICKUP"
          volume: 1.0
          pitch: 1.0```
````


# How to create a collection

Its pretty easy to create a collection. Navigate to `UltraCollections/collections` and in the collections folder, simply create a new yml, for example, dirt.yml. Then, paste the code below in it, you can modify this as to your needs.

***

#### category

The category is important as that is where this collection will show up.

***

#### maxLevel

* You need to set the `maxLevel` to the max level of the collection, this must match the xpRequirements section aswell!

***

#### giveXP

* This is the amount of xp that will be given when the block is broken or picked up

***

#### collectionExecutor

**executorType**

* There are 2 executor types, `BY_BLOCK_BREAK` and `BY_PICKUP_ITEM`. If the executor is `BY_BLOCK_BREAK`, the player will gain collection xp when breaking the block, and if its `BY_PICKUP_ITEM`, the player will gain collection xp by picking up the item defined.

**itemstack**

* This itemstack can be modified in the config, or just go ingame and run the `/collections setitem <collection>` command when holding the item, and this will automatically update.

***

#### leaderboard

* This is where you change the style/design of how the leaderboard looks.

***

#### commandRewards

* You can configure command rewards here for each level, these will be executed when people level up to that level. You can make console or player execute them by adding either `PLAYER` or `CONSOLE` before the command.

***

#### xpRequirements

* This is the XP required to level up to each level.

***

#### Structure and ingredients

Structure and ingredients are explained in [How the GUI system works](https://github.com/abyssxd/UltraCollections-Wiki/wiki/How-the-GUI-system-works)

***

#### levels

* Here you can configure different levels
* The rewards section is what is shown for level up message and in the GUI
* Locked, unlocked and current item are the items for the level, there are these 3 so that you can fully customize them.
* Actions are explained in [How the GUI system works](https://github.com/abyssxd/UltraCollections-Wiki/wiki/How-the-GUI-system-works)

***

Once you know all this, you can make the process faster by using our collections creator: <https://pogmc.net/ultracollections/collection_creator.php>

***

### dirt.yml

```
maxLevel: 7
category: farming
displayName: '&aDirt'

giveXP: 3

collectionExecutor:
  executorType: BY_BLOCK_BREAK
  itemstack:
    ==: org.bukkit.inventory.ItemStack
    v: 3700
    type: DIRT

leaderboard:
  - '&a{playername} &f-> &6{level} &e({xp})'


commandRewards:
  '2':
    rewards:
      - PLAYER give %player% diamond 1
      - CONSOLE say %player% has leveled up!
  '3':
    rewards:
      - PLAYER give %player% gold_ingot 5
  '4':
    rewards:
      - PLAYER give %player% iron_ingot 5
  '5':
    rewards:
      - CONSOLE give %player% diamond 5
      - PLAYER give %player% diamond_shovel
# Add rewards for other levels as needed


xpRequirements:
  '1': 10.0
  '2': 20.0
  '3': 30.0
  '4': 100.0
  '5': 105.0
  '6': 110.0
  '7': 130.0
# Add XP requirements for other levels as needed

structure:
  - '# # # # ? # # # #'
  - '# # # # # # # # #'
  - '# L L L L L L L #'
  - '# # # # # # # # #'
  - '# # # # # # # # #'
  - '# # # B C N T # #'

locked_item:
  itemstack:
    ==: org.bukkit.inventory.ItemStack
    v: 3700
    type: RED_STAINED_GLASS_PANE
  displayName: "{collection_name} Level {collection_level}"
  lore:
    - '  &eProgress: {progress_percentage}'
    - '  &e{progress_bar}{currentxp}/{max_xp}'
    - '  &eRewards:'
    - '  {rewards}'


current_item:
  itemstack:
    ==: org.bukkit.inventory.ItemStack
    v: 3700
    type: YELLOW_STAINED_GLASS_PANE
  displayName: "{collection_name} Level {collection_level}"
  lore:
    - '  &eProgress: {progress_percentage}'
    - '  &e{progress_bar}{currentxp}/{max_xp}'
    - '  &eRewards:'
    - '  {rewards}'

unlocked_item:
  itemstack:
    ==: org.bukkit.inventory.ItemStack
    v: 2586
    type: GREEN_STAINED_GLASS_PANE
  displayName: "{collection_name} Level {collection_level}"
  lore:
    - '  &eProgress: {progress_percentage}'
    - '  &e{progress_bar}{currentxp}/{max_xp}'
    - '  &eRewards:'
    - '  {rewards}'

ingredients:
  filler:
    item_icon: '#'
    item_name: '&f'
    item-lore: []
    gui_item: BLACK_STAINED_GLASS_PANE
    custom_model_data: 1069

  collection_item:
    gui_item: Dirt
    item_name: '&aDirt Collection'
    item_icon: '?'
    custom_model_data: 1069
    item-lore:
      - '&7Viewing Dirt collection'

  back:
    gui_item: ARROW
    item_name: '&aGo Back'
    item_icon: B
    custom_model_data: 1069
    item-lore:
      - '&7to the'
      - '&7previous page'

  leaderboard:
    gui_item: DIAMOND
    item_name: '&aLeaderboard'
    item_icon: T
    custom_model_data: 1069
    item-lore:
      - '&7Top 10 players'
      - '{leaderboard}'


  next:
    gui_item: ARROW
    item_name: '&aNext'
    item_icon: N
    custom_model_data: 1069
    item-lore:
      - '&7Go to the'
      - '&7next page'

  close:
    gui_item: BARRIER
    item_name: '&cClose'
    item_icon: C
    item-lore: []
    actions:
      opengui: main
      play_sound:
        sound: ENTITY_ITEM_PICKUP
        volume: 1.0
        pitch: 1.0

levels:
  '1':
    rewards:
      - '  &eDirt Minion &7Recipe'
    locked_item:
      actions:
        send_message:
          message: You have not unlocked this yet!
    current_item:
      actions:
        send_message:
          message: You have not unlocked this yet!
    unlocked_item:
      actions:
        run_command:
          command: crafting open dirt_minion # example command
          as_op: true

```


# How to create a reward GUI

Creating a rewards gui is simple, just create a new yml file in the `UltraCollections/rewards` folder and use the template provided in this page. With what you've learned from [How the GUI system works](https://github.com/abyssxd/UltraCollections-Wiki/wiki/How-the-GUI-system-works), you know that you need to define a item icon in the stucture for the item to show up. So follow these steps:

***

## Instructions

1. Create yml
2. Fill it with the template
3. We've defined a "I" in the structure, now go in-game and hold your rewards item and run this command: `/collections setreward <reward_file> <reward_name> <item_icon>`

* The `reward_file` is the file you just made WITHOUT THE .YML, so a dirt\_reward.yml would be `dirt_reward`
* The `reward_name` is just a key lets set it to `helmet` for now.
* Now the `item_icon`, as we already have an `I` in the stucture, lets use `I`.
* Here is your final command: `/collections setreward dirt_reward helmet I`

4. Now the item is added to the config file and in the GUI in-game.

***

### Template

```
GUI:
  title: Dirt Level 2 Rewards
  category_name: dirt_level_2
  structure:
    - '# # # # # # # # #'
    - '# # # # # # # # #'
    - '# # # # I # # # #'
    - '# # # # # # # # #'
    - '# # # # # # # # #'
    - '# # # # C # # # #'
  ingredients:
    filler:
      gui_item: BLACK_STAINED_GLASS_PANE
      item_icon: '#'
      item_name: '&f'
      item-lore: []
      custom_model_data: 1069

    close:
      gui_item: BARRIER
      item_name: '&cClose'
      item_icon: C
      item-lore: []
      actions:
        opengui: farming
        play_sound:
          sound: ENTITY_ITEM_PICKUP
          volume: 1.0
          pitch: 1.0

```

***

### Example

```
GUI:
  title: Dirt Level 2 Rewards
  category_name: dirt_level_2
  structure:
    - '# # # # # # # # #'
    - '# # # # # # # # #'
    - '# # H I L B # # #'
    - '# # # # # # # # #'
    - '# # # # # # # # #'
    - '# # # # C # # # #'
  ingredients:
    filler:
      gui_item: BLACK_STAINED_GLASS_PANE
      item_icon: '#'
      item_name: '&f'
      item-lore: []
      custom_model_data: 1069

    close:
      gui_item: BARRIER
      item_name: '&cClose'
      item_icon: C
      item-lore: []
      actions:
        opengui: farming
        play_sound:
          sound: ENTITY_ITEM_PICKUP
          volume: 1.0
          pitch: 1.0

    helmet:
      item_name: Helmet
      item_icon: H
      itemstack:
        ==: org.bukkit.inventory.ItemStack
        v: 2586
        type: LEATHER_HELMET
        meta:
          ==: ItemMeta
          meta-type: COLORABLE_ARMOR
          display-name: '"Dirt Helmet"'

    chestplate:
      item_name: Chestplate
      item_icon: I
      itemstack:
        ==: org.bukkit.inventory.ItemStack
        v: 2586
        type: LEATHER_CHESTPLATE
        meta:
          ==: ItemMeta
          meta-type: COLORABLE_ARMOR
          display-name: '"Dirt Chestplate"'

    leggings:
      item_name: Leggings
      item_icon: L
      itemstack:
        ==: org.bukkit.inventory.ItemStack
        v: 2586
        type: LEATHER_LEGGINGS
        meta:
          ==: ItemMeta
          meta-type: COLORABLE_ARMOR
          display-name: '"Dirt Pants"'
    boots:
      item_name: Boots
      item_icon: B
      itemstack:
        ==: org.bukkit.inventory.ItemStack
        v: 2586
        type: LEATHER_BOOTS
        meta:
          ==: ItemMeta
          meta-type: COLORABLE_ARMOR
          display-name: '"Dirt Boots"'
```


# Developer API

Coming soon.


# BlockBase

A customizable ReactJS based Minecraft server website

BuiltByBit: <https://builtbybit.com/resources/blockbase-fully-customizable-website.52448/>

{% content-ref url="/pages/iP4n9zSWZR0C3vXjfgYo" %}
[Getting Started](/blockbase/blockbase/getting-started)
{% endcontent-ref %}

{% content-ref url="/pages/RoPbvFGCcUXRajiu2hn1" %}
[Changing Branding](/blockbase/blockbase/changing-branding)
{% endcontent-ref %}

{% content-ref url="/pages/OFdNBISu72F2QnJOWL75" %}
[Editing Pages](/blockbase/blockbase/editing-pages)
{% endcontent-ref %}

{% content-ref url="/pages/OBn7nUfvzE668hjSlYMF" %}
[Theming](/blockbase/blockbase/theming)
{% endcontent-ref %}


# Getting Started

Let's get started!

So you've finally purchased BlockBase, you're excited to get it up and running for your server, but how??

***

## Running Locally

You must run this locally first to edit it before you can publish it to your web host (we provide free web hosts through discord btw).&#x20;

You'll need to install NodeJS in your system to start, download it from [here](https://nodejs.org/en/download/prebuilt-installer).

### Commands

After you've installed NodeJS, extract blockbase.zip, go inside the extracted folder, open a new command prompt and run these commands:

1. `npm install` - This will install the necessary dependencies to run and compile the website.
2. `npm run` - This will run the website locally for you, when you edit the files, this locally hosted website will automatically update as you edit blockbase. We recommend using [VsCode ](https://code.visualstudio.com/)to edit the files.
3. `npm build` - Open a new command prompt in the same folder, then run this command. This'll generate a new folder called `build`, everything INSIDE of that `build` folder is what you need to upload to your webhost's `public_html` folder.


# Changing Branding

Changing the branding of BlockBase is fairly easy, here's a few steps.

1. `public/images/blockbase.png` - This is the logo, you can either replace this with your own logo or move your own new logo to the `public/images` folder.
2. `src/config/mainPageConfig.js` - This is where you can change the url of the logo you just modified, and this is where you can edit the main page. You can change all texts that say `BlockBase` to your server name here.
3. `src/config/mainConfig.js` - This is where you can edit all the SEO related tags. Just open it and you'll see what you need to change.


# Editing Pages

Editing pages is made really easy with the configuration files. You can find all the configs to edit under `src/configs` folder.<br>

Currently, each option in config isn't explained in details because I am sure people purchasing this will already know what all the options mean. If not, you can always open a ticket on our [Discord](https://discord.gg/mGwymZWGUf) for premium support.


# Theming

Changing the theme of BlockBase is really easy. You'd only need to change the background image and change the color configuration.

1. `src/assets/underwater.png` - Replace this with your new image.
2. `src/configs/colorConfig.js` - This is the config that controls all the colors on the website, it says which colors belongs to which pages. The main landing page's colors are the ones outside the sections like rules, staff..etc
3. You can also ask an AI like ChatGPT or ClaudeAI to change the colors to a Dark, Light, Purple...theme to match your server.


# 404 Error

If you get a 404 Error when clicking on buttons that lead to /vote, /staff...etc, here's what to do:

1. Open your web host's public\_html directory
2. Create or edit the existing .htaccess file
3. Paste this in:

```
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>
```


# About

A Java to Bedrock 3D Animated Converter for Nexo, ItemsAdder and Oraxen Packs

#### [Take me to Kafal](https://kafal.pogmc.net/)

## Features

* Supports 1.21.4+ Item Models & Legacy Custom Model Data
* 2D Items
* 3D Items & Furniture using Display Entities
* Custom Armors
* Inventory Icon Generation
* 3D Bows & Crossbows
* Custom Blocks (Supports custom geometry too)
* Font Conversion
* Custom GUIs with Custom Rows with a web-based offset editor
* Uses **Geyser V2 Mappings** to support Item Models
* Offset config generator for GeyserDisplayEntity (Although GeyserDisplayEntity needs to be updated to support item models for offsets, will talk to them soon)


# How to convert

Converting your pack is fairly easy. Here's some basic steps to follow:

**Step 1**

* Turn off protection in config.yml or settings.yml of Nexo/ItemsAdder/Oraxen

**Step 2**

* Copy your output zip somewhere, open it, and add the Nexo/ItemsAdder/Oraxen folders like stated in [Pack Structure](/kafal/pack-structure)

**Step 3**

* Head over to [Kafal](https://kafal.pogmc.net/) & upload your pack

**Step 4**

* You will be prompted to select GUI rows, you can select any rows for now, but you must mark anything that isn't a GUI as not a gui, that'll make it treat that image as a font. Later in the GUI Offset Editor, you can edit your GUIs.

**Step 5**

* Once the pack is done converting, download it. Place the `xxx_xxx_mappings` files in `Geyser-XXX/custom_mappings` & the `Kafal-Java2Bedrock.zip` file in `Geyser-XXX/packs`

**Step 6**

* Restart your server, join & enjoy!


# Pack Structure

It is now **CRUCIAL** that you have this structure — it’s needed to support item models as Java packs do not specify what material item models are mapped to. This also means for vanilla packs that don't use plugins, item models are NOT supported by Kafal.

```
pack/
├─ assets/
│  └─ ... (vanilla/other assets)
├─ nexo/
│  └─ items/
│     └─ ... (your Nexo items)
└─ ... (other pack files)


pack/
├─ assets/
│  └─ ... (vanilla/other assets)
├─ oraxen/
│  └─ items/
│     └─ ... (your Oraxen items)
└─ ... (other pack files)


pack/
├─ assets/
│  └─ ... (vanilla/other assets)
├─ itemsadder/
│  ├─ contents/
│  │  └─ ... (ItemsAdder namespaces + assets)
│  └─ storage/
│     └─ ... (item_ids_cache.yml)
└─ ... (other pack files)

```


# 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


# ItemsAdder Mappings

## Overview

ItemsAdder 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. It also supports custom model data caching for proper CMD value tracking.

## Supported Format

ItemsAdder Mappings uses the ItemsAdder YAML configuration files only.

## YAML Format

### File Location

Place YAML files anywhere under `ItemsAdder/contents/<namespace>/` within your resource pack:

```
your-pack.zip
├── ItemsAdder/
│   ├── contents/
│   │   ├── mynamespace/
│   │   │   ├── weapons.yml
│   │   │   ├── armor.yml
│   │   │   └── tools.yml
│   │   └── custom/
│   │       └── items.yml
│   └── storage/
│       └── item_ids_cache.yml
└── assets/
    └── ...
```

### YAML Structure

```yaml
info:
  namespace: your_namespace

items:
  item_key:
    resource:
      material: BUKKIT_MATERIAL
      model_path: model_path
    Components:
      max_stack_size: number (optional)
      durability: number (optional)
      equippable:
        slot: SLOT_NAME
        model: equipment_model_id
        allowed_entity_types: [entity_list] (optional)
    specific_properties:
      armor:
        slot: SLOT_NAME
        custom_armor: armor_model_id
    behaviours:
      armor: true/false
```

### YAML Field Reference

| Field                                        | Type    | Required | Description                                                                    |
| -------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `info.namespace`                             | string  | ❌        | Namespace for items (auto-detected from directory if missing)                  |
| `resource.material`                          | string  | ✅        | Bukkit Material name (e.g., `NETHERITE_SWORD`)                                 |
| `resource.model_path`                        | string  | ✅        | Model path (can be nested like `santa_decoration/big_gift_box`)                |
| `Components.equippable.slot`                 | string  | ❌        | Equipment slot: `HEAD`, `CHEST`, `LEGS`, `FEET`, `MAINHAND`, `OFFHAND`, `BODY` |
| `Components.equippable.model`                | string  | ❌        | Equipment model ID (with namespace)                                            |
| `Components.equippable.allowed_entity_types` | array   | ❌        | List of entities that can equip                                                |
| `Components.max_stack_size`                  | number  | ❌        | Maximum stack size (auto-set to 1 for equippable items)                        |
| `Components.durability`                      | number  | ❌        | Maximum durability for the item                                                |
| `specific_properties.armor.slot`             | string  | ❌        | Armor slot (alternative to Components.equippable)                              |
| `specific_properties.armor.custom_armor`     | string  | ❌        | Custom armor model ID                                                          |
| `behaviours.armor`                           | boolean | ❌        | Indicates if item is armor                                                     |

### Custom Model Data Cache

ItemsAdder uses a cache file for custom model data values:

**File:** `ItemsAdder/storage/item_ids_cache.yml`

```yaml
namespace:item_key: custom_model_data_value
custom:flame_sword: 1001
custom:ruby_helmet: 2000
```

### YAML Examples

**Basic weapons and tools:**

```yaml
info:
  namespace: custom

items:
  excalibur:
    resource:
      material: NETHERITE_SWORD
      model_path: weapons/excalibur
  
  drill:
    resource:
      material: DIAMOND_PICKAXE
      model_path: tools/drill
    Components:
      durability: 2000
  
  crossbow_heavy:
    resource:
      material: BOW
      model_path: weapons/crossbow_heavy
```

**Items with nested model paths:**

```yaml
info:
  namespace: christmas

items:
  big_gift_box:
    resource:
      material: PAPER
      model_path: santa_decoration/big_gift_box
  
  small_gift:
    resource:
      material: PAPER
      model_path: santa_decoration/gifts/small
```

**Equippable armor (using Components):**

```yaml
info:
  namespace: armor

items:
  ruby_helmet:
    resource:
      material: DIAMOND_HELMET
      model_path: ruby_helmet
    Components:
      equippable:
        slot: HEAD
        model: armor:ruby
      durability: 500
  
  ruby_chestplate:
    resource:
      material: DIAMOND_CHESTPLATE
      model_path: ruby_chestplate
    Components:
      equippable:
        slot: CHEST
        model: armor:ruby
        allowed_entity_types: [player, zombie]
      durability: 800
```

**Equippable armor (using specific\_properties):**

```yaml
info:
  namespace: custom

items:
  emerald_helmet:
    resource:
      material: DIAMOND_HELMET
      model_path: armor/emerald/helmet
    specific_properties:
      armor:
        slot: HEAD
        custom_armor: emerald
    behaviours:
      armor: true
  
  emerald_chestplate:
    resource:
      material: DIAMOND_CHESTPLATE
      model_path: armor/emerald/chestplate
    specific_properties:
      armor:
        slot: CHEST
        custom_armor: emerald
    behaviours:
      armor: true
```

**Complex example with mixed types:**

```yaml
info:
  namespace: legendary

items:
  legendary_sword:
    resource:
      material: NETHERITE_SWORD
      model_path: weapons/legendary/excalibur
    Components:
      durability: 3000
  
  sapphire_chestplate:
    resource:
      material: DIAMOND_CHESTPLATE
      model_path: armor/sapphire/chestplate
    Components:
      equippable:
        slot: CHEST
        model: legendary:sapphire
      durability: 1000
  
  magic_wand:
    resource:
      material: STICK
      model_path: magic/wands/fire
    Components:
      durability: 100
      max_stack_size: 1
```

## Equipment Slots

| 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 under `ItemsAdder/contents/<namespace>/` directory
* Check that files have `.yml` or `.yaml` extension
* Verify YAML syntax is valid (use a YAML validator)
* Ensure files are not in `categories/` folder (automatically skipped)

</details>

<details>

<summary>Namespace not detected</summary>

* Add `info.namespace` to YAML file
* Ensure directory structure follows `ItemsAdder/contents/<namespace>/...`

</details>

<details>

<summary>Items not mapping</summary>

* Verify `resource.material` uses correct Bukkit Material names
* Check that `resource.model_path` is specified
* Ensure item definition files exist
* Try both simple and nested model path formats

</details>

<details>

<summary>Nested model paths not working</summary>

* Verify basename exists: `santa_decoration/big_gift_box` → `big_gift_box.json`
* Try underscore format: `santa_decoration_big_gift_box.json`
* Check if full path exists: `santa_decoration/big_gift_box.json`

</details>

<details>

<summary>Custom model data missing</summary>

* Check if `item_ids_cache.yml` exists
* Verify cache format: `namespace:item_key: cmd_value`
* Ensure namespace matches item configuration

</details>

<details>

<summary>Armor not working</summary>

* Set either `Components.equippable` OR `specific_properties.armor`
* Verify slot is set correctly
* Check that equipment model ID exists
* Confirm armor model path exists

</details>

## Example Project Structure

```
itemsadder-pack.zip
├── ItemsAdder/
│   ├── contents/
│   │   ├── custom/
│   │   │   ├── weapons.yml
│   │   │   └── armor.yml
│   │   └── christmas/
│   │       └── decorations.yml
│   └── storage/
│       └── item_ids_cache.yml
├── assets/
│   ├── itemsadder/
│   │   ├── models/
│   │   │   └── item/
│   │   │       ├── excalibur.json
│   │   │       └── big_gift_box.json
│   │   ├── items/
│   │   │   ├── excalibur.json
│   │   │   └── big_gift_box.json
│   │   └── textures/
│   │       └── item/
│   │           ├── excalibur.png
│   │           └── big_gift_box.png
│   └── minecraft/
│       └── ...
└── pack.mcmeta
```

## Important Notes

### Armor Configuration Methods

ItemsAdder supports two methods for armor configuration:

Method 1: Components.equippable (modern)

```yaml
Components:
  equippable:
    slot: CHEST
    model: namespace:armor_id
```

Method 2: specific\_properties.armor (legacy)

```yaml
specific_properties:
  armor:
    slot: CHEST
    custom_armor: armor_id
```

Both methods work, but `Components.equippable` is preferred for new configurations.

### Entity Restrictions

Use `allowed_entity_types` to restrict which entities can equip armor:

```yaml
Components:
  equippable:
    allowed_entity_types: [player, zombie, skeleton]
```

Entity types are automatically prefixed with `minecraft:`.

### Durability vs Max Stack Size

* Items with armor configuration automatically have `max_stack_size: 1`
* Non-armor items can have custom `max_stack_size`
* Durability can be specified as a number or in nested format


# Oraxen Mappings

## Overview

Oraxen 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

Oraxen Mappings uses the Oraxen Plugin YAML configuration files only.

## YAML Format

### File Location

Place YAML files in the `Oraxen/items/` folder within your resource pack:

{% code title="Example pack structure" %}

```
your-pack.zip
├── Oraxen/
│   └── items/
│       ├── weapons.yml
│       ├── armor.yml
│       └── tools.yml
└── assets/
    └── ...
```

{% endcode %}

### YAML Structure

```yaml
item_key:
  material: BUKKIT_MATERIAL
  Pack:
    model: model_path (optional)
    item_model: item_definition_id (optional)
  Components:
    equippable:
      slot: SLOT_NAME
      model: equipment_model_id
    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.model`                  | string | ❌        | Model file path hint for item definition lookup                        |
| `Pack.item_model`             | string | ❌        | Explicit item definition ID override                                   |
| `Components.equippable.slot`  | string | ❌        | Equipment slot: `HEAD`, `CHEST`, `LEGS`, `FEET`, `MAINHAND`, `OFFHAND` |
| `Components.equippable.model` | string | ❌        | Equipment model ID (e.g., `oraxen:emerald`)                            |
| `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:

{% code title="weapons.yml" %}

```yaml
excalibur:
  material: NETHERITE_SWORD
  Pack:
    model: weapons/excalibur

drill:
  material: DIAMOND_PICKAXE
  Pack:
    model: tools/drill
  Components:
    durability: 2000

crossbow_heavy:
  material: BOW
  Pack:
    model: weapons/crossbow_heavy
```

{% endcode %}

Items with durability:

{% code title="durable\_items.yml" %}

```yaml
flame_blade:
  material: GOLDEN_SWORD
  Pack:
    model: weapons/flame_blade
  Components:
    durability: 500
    max_stack_size: 1

magic_wand:
  material: STICK
  Pack:
    model: magic/wands/fire
  Components:
    durability: 100
    max_stack_size: 1
```

{% endcode %}

Equippable armor:

{% code title="armor.yml" %}

```yaml
emerald_helmet:
  material: DIAMOND_HELMET
  Pack:
    model: armor/emerald/helmet
  Components:
    equippable:
      slot: HEAD
      model: oraxen:emerald
    durability: 500

emerald_chestplate:
  material: DIAMOND_CHESTPLATE
  Pack:
    model: armor/emerald/chestplate
  Components:
    equippable:
      slot: CHEST
      model: oraxen:emerald
    durability: 800

knight_helmet:
  material: LEATHER_HELMET
  Components:
    equippable:
      slot: HEAD
      model: minecraft:knight
    durability: 300
```

{% endcode %}

Complex example with mixed types:

{% code title="mixed\_examples.yml" %}

```yaml
legendary_sword:
  material: NETHERITE_SWORD
  Pack:
    model: legendary/excalibur
  Components:
    durability: 3000

ruby_chestplate:
  material: DIAMOND_CHESTPLATE
  Components:
    equippable:
      slot: CHEST
      model: oraxen:ruby
    durability: 1000

enchanted_bow:
  material: BOW
  Pack:
    model: weapons/enchanted_bow
  Components:
    durability: 800
    max_stack_size: 1
```

{% endcode %}

## Equipment Slots

When using `Components.equippable.slot` for armor:

| Slot       | Usage                 |
| ---------- | --------------------- |
| `HEAD`     | Helmets, hats, crowns |
| `CHEST`    | Chestplates, tunics   |
| `LEGS`     | Leggings, pants       |
| `FEET`     | Boots, shoes          |
| `MAINHAND` | Main hand equipment   |
| `OFFHAND`  | Off-hand equipment    |

## Troubleshooting

<details>

<summary>YAML not being read</summary>

* Ensure files are in `Oraxen/items/` folder
* 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.equippable.slot` is set correctly
* Verify equipment model ID exists
* Check that item definition file matches the item key

</details>

## Example Project Structure

{% code title="oraxen-pack.zip layout" %}

```
oraxen-pack.zip
├── Oraxen/
│   └── items/
│       ├── weapons.yml
│       ├── armor.yml
│       └── tools.yml
├── assets/
│   ├── oraxen/
│   │   ├── models/
│   │   │   ├── item/
│   │   │   │   ├── excalibur.json
│   │   │   │   └── drill.json
│   │   │   └── armor/
│   │   │       └── emerald/
│   │   │           ├── helmet.json
│   │   │           └── chestplate.json
│   │   ├── items/
│   │   │   ├── excalibur.json
│   │   │   ├── emerald_helmet.json
│   │   │   └── emerald_chestplate.json
│   │   └── textures/
│   │       └── item/
│   │           ├── excalibur.png
│   │           └── drill.png
│   └── minecraft/
│       └── ...
└── pack.mcmeta
```

{% endcode %}

## Important Notes

{% hint style="info" %}
For armor items, the item key (e.g., `emerald_chestplate`) determines the item definition ID, not the `Components.equippable.model` field. The equippable model is used as a component in the mapping, but the actual item definition comes from the item key.

Example:

```yaml
emerald_chestplate:
  Components:
    equippable:
      model: oraxen:emerald  # This is the equipment model, not the item def
```

* Item definition: `assets/oraxen/items/emerald_chestplate.json`
* Equipment model: referenced in the equippable component
  {% endhint %}

{% hint style="info" %}
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 is converted to the `minecraft:max_damage` component
  {% endhint %}


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

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

<details>

<summary>CSV not being read</summary>

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

</details>

<details>

<summary>Items not mapping</summary>

* 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

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

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


# CraftEngine Mappings

## Overview

CraftEngine Mappings is a mapping system for converting Java 1.21+ item model systems to Bedrock Edition. It reads item definitions from YAML configuration files with template support and generates the appropriate Geyser mappings.

## Supported Format

CraftEngine Mappings uses the CraftEngine YAML configuration files with template system support.

## YAML Format

### File Location

Place YAML files under `CraftEngine/resources/` within your resource pack:

```
your-pack.zip
├── CraftEngine/
│   └── resources/
│       ├── weapons.yml
│       ├── armor.yml
│       └── tools.yml
└── assets/
    └── ...
```

### YAML Structure

```yaml
templates:
  template_name:
    # Reusable template configuration
    settings:
      equipment:
        slot: SLOT_NAME
        asset-id: equipment_model_id

items:
  namespace:item_key:
    material: BUKKIT_MATERIAL
    model:
      path: model_path
    texture: texture_path (alternative)
    textures: [texture_list] (alternative)
    template: template_name (optional)
    arguments:
      key: value (for template variables)
    data:
      custom-model-data: number (optional)
      max-damage: number (optional)
      max-stack-size: number (optional)
    settings:
      equipment:
        slot: SLOT_NAME
        asset-id: equipment_model_id
```

### YAML Field Reference

| Field                         | Type         | Required | Description                                                                    |
| ----------------------------- | ------------ | -------- | ------------------------------------------------------------------------------ |
| `material`                    | string       | ✅        | Bukkit Material name (e.g., `NETHERITE_SWORD`)                                 |
| `model.path` / `model`        | string       | ❌        | Model file path for item definition lookup                                     |
| `texture`                     | string       | ❌        | Single texture path (alternative to model)                                     |
| `textures`                    | array        | ❌        | Array of texture paths (uses first for lookup)                                 |
| `template`                    | string/array | ❌        | Template name(s) to inherit from                                               |
| `arguments`                   | object       | ❌        | Variables for template substitution                                            |
| `data.custom-model-data`      | number       | ❌        | Custom model data value                                                        |
| `data.max-damage`             | number       | ❌        | Maximum durability for the item                                                |
| `data.max-stack-size`         | number       | ❌        | Maximum stack size                                                             |
| `settings.equipment.slot`     | string       | ❌        | Equipment slot: `HEAD`, `CHEST`, `LEGS`, `FEET`, `BODY`, `MAINHAND`, `OFFHAND` |
| `settings.equipment.asset-id` | string       | ❌        | Equipment model ID                                                             |

### YAML Examples

**Basic weapons and tools:**

```yaml
items:
  default:excalibur:
    material: NETHERITE_SWORD
    model:
      path: weapons/excalibur
  
  default:drill:
    material: DIAMOND_PICKAXE
    model:
      path: tools/drill
    data:
      max-damage: 2000
  
  custom:crossbow_heavy:
    material: BOW
    texture: weapons/crossbow_heavy
```

**Using templates:**

```yaml
templates:
  basic_armor:
    data:
      max-damage: 500
    settings:
      equipment:
        slot: ${slot}
        asset-id: ${armor_set}

items:
  armor:knight_helmet:
    material: DIAMOND_HELMET
    template: basic_armor
    arguments:
      slot: HEAD
      armor_set: knight
    model:
      path: armor/knight/helmet
  
  armor:knight_chestplate:
    material: DIAMOND_CHESTPLATE
    template: basic_armor
    arguments:
      slot: CHEST
      armor_set: knight
    model:
      path: armor/knight/chestplate
```

**Multiple templates:**

```yaml
templates:
  durable:
    data:
      max-damage: 2000
  
  equippable_chest:
    settings:
      equipment:
        slot: CHEST

items:
  custom:reinforced_chestplate:
    material: DIAMOND_CHESTPLATE
    template: [durable, equippable_chest]
    settings:
      equipment:
        asset-id: reinforced
    model:
      path: armor/reinforced/chestplate
```

**Using textures instead of models:**

```yaml
items:
  default:ruby_gem:
    material: PAPER
    texture: items/ruby_gem
    data:
      custom-model-data: 1000
  
  default:sapphire_gem:
    material: PAPER
    textures:
      - items/sapphire_gem
      - items/sapphire_gem_glowing
    data:
      custom-model-data: 1001
```

**Complex example with mixed types:**

```yaml
templates:
  legendary_weapon:
    data:
      max-damage: 3000
      max-stack-size: 1

items:
  legendary:excalibur:
    material: NETHERITE_SWORD
    template: legendary_weapon
    model:
      path: legendary/weapons/excalibur
    data:
      custom-model-data: 5000
  
  armor:sapphire_chestplate:
    material: DIAMOND_CHESTPLATE
    model:
      path: armor/sapphire/chestplate
    data:
      max-damage: 1000
      custom-model-data: 2000
    settings:
      equipment:
        slot: CHEST
        asset-id: sapphire
  
  magic:wand:
    material: STICK
    texture: magic/wands/fire
    data:
      max-damage: 100
      max-stack-size: 1
```

## Item Key Format

Item keys in CraftEngine use the format `namespace:item_key`:

Examples:

* `default:bench` → namespace: `default`, item: `bench`
* `custom:ruby_sword` → namespace: `custom`, item: `ruby_sword`
* `armor:knight_helmet` → namespace: `armor`, item: `knight_helmet`

The namespace is extracted from the item key and used for item definition resolution.

## Item Definition Resolution

CraftEngine resolves item definitions in the following priority.

{% stepper %}
{% step %}

### model.path

Extracts basename from model path.

* Example:

```yaml
default:knight_helmet:
  material: DIAMOND_HELMET
  model:
    path: armor/knight/helmet
```

→ Extracts basename: `helmet` → Looks for: `assets/default/items/helmet.json`
{% endstep %}

{% step %}

### texture

Uses texture path basename.

* Example:

```yaml
custom:ruby:
  material: PAPER
  texture: items/ruby_gem
```

→ Extracts basename: `ruby_gem` → Looks for: `assets/custom/items/ruby_gem.json`
{% endstep %}

{% step %}

### textures\[0]

Uses first texture path basename.
{% endstep %}

{% step %}

### item\_key

Uses the item key directly as a last resort.
{% endstep %}
{% endstepper %}

Namespace handling:

* Namespace from item key (e.g., `default:bench` → `default`)
* Falls back to `minecraft` if not found in preferred namespace
* Searches all namespaces as last resort

## Template System

CraftEngine supports a powerful template system with variable substitution.

### Template Features

Basic inheritance:

```yaml
templates:
  durable:
    data:
      max-damage: 2000

items:
  default:strong_sword:
    template: durable
    material: IRON_SWORD
```

Multiple templates:

```yaml
items:
  default:item:
    template: [template1, template2]
```

Templates are applied in order, with later values overriding earlier ones.

Variable substitution:

```yaml
templates:
  armor_piece:
    settings:
      equipment:
        slot: ${slot}
        asset-id: ${set_name}

items:
  armor:helmet:
    template: armor_piece
    arguments:
      slot: HEAD
      set_name: knight
```

Variables use `${variable_name}` syntax and are replaced with values from `arguments`.

Nested templates:

* Templates can reference other templates, with circular reference protection.

## Material Names

Use standard Bukkit Material enum names for `material`.

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`, `PAPER`, `CARROT_ON_A_STICK`

Note: Legacy material names (e.g., `LEGACY_IRON_SWORD`) are automatically cleaned.

## Equipment Slots

When using `settings.equipment.slot`:

| 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

### Common Issues

**YAML not being read:**

* Ensure files are under `CraftEngine/resources/` directory
* Check that files have `.yml` or `.yaml` extension
* Verify YAML syntax is valid (use a YAML validator)

**Template variables not working:**

* Check variable syntax: `${variable_name}`
* Ensure `arguments` field is defined with matching keys
* Verify template is referenced correctly

**Template not found:**

* Confirm template name matches exactly (case-sensitive)
* Ensure template is defined in `templates:` section
* Check for typos in template references

**Items not mapping:**

* Verify `material` uses correct Bukkit Material names
* Check that model/texture paths are specified
* Ensure namespace is included in item key
* Verify item definition files exist

**Namespace not detected:**

* Include namespace in item key: `namespace:item_key`
* Check for colon separator in key

**Armor not working:**

* Ensure `settings.equipment.slot` is set
* Verify `asset-id` is specified
* Check that equipment model exists
* Confirm item definition matches configuration

## Example Project Structure

```
craftengine-pack.zip
├── CraftEngine/
│   └── resources/
│       ├── weapons.yml
│       ├── armor.yml
│       └── tools.yml
├── assets/
│   ├── default/
│   │   ├── models/
│   │   │   └── item/
│   │   │       ├── excalibur.json
│   │   │       └── drill.json
│   │   ├── items/
│   │   │   ├── excalibur.json
│   │   │   └── drill.json
│   │   └── textures/
│   │       └── item/
│   │           ├── excalibur.png
│   │           └── drill.png
│   └── minecraft/
│       └── ...
└── pack.mcmeta
```

## Important Notes

### Item Key Namespace

The namespace in the item key (e.g., `default:bench`) determines the preferred namespace for item definition lookup. This allows organizing items by namespace while using centralized YAML files.

### Template Inheritance

Templates provide powerful reusability:

* Define common properties once
* Apply to multiple items
* Override specific fields per item
* Use variable substitution for flexibility

### Model vs Texture

CraftEngine supports multiple ways to specify models:

* `model.path` or `model` - Direct model path
* `texture` - Single texture path
* `textures` - Array of textures (uses first)

All three methods extract a basename for item definition lookup.

### Equipment Configuration

Use `settings.equipment` for armor items:

* `slot` - Where the item is equipped
* `asset-id` - The equipment model ID

The asset-id can include namespace: `namespace:model_id`

### Durability vs Max Stack Size

* Items with equipment automatically have `max_stack_size: 1`
* Non-equipment items can have custom `max_stack_size`
* Durability is specified in `data.max-damage`