🧩 CustomiZer — Complete Plugin Documentation

🌐 Built-in HTTP Server

On startup the plugin spins up a lightweight HTTP server on a configurable port (default 7270). The resource pack is served at http://<your-ip>:<port>/<hash>.zip. Players receive it automatically on join via the setResourcePack API.

🔄 Hot Reload Without Restart

Running /zpack zip or /z reload rebuilds the pack in memory and updates the live HTTP handler — the server never needs a restart. The new pack hash triggers a fresh download on the next player join.

📐 Dual Format Output

The pack is written in both formats simultaneously:

• Old format — assets/minecraft/models/item/<material>.json with overrides[] — works on all versions including 1.21.8.
• New format — assets/minecraft/items/<material>.json with range_dispatch — required for 1.21.4+ priority rendering.

🗂️ Includes Folder

Place any extra resource pack inside plugins/CustomiZer/includes/ and it will be merged into the generated pack automatically on every build. Perfect for adding custom sounds, textures, or fonts from other tools.

📂 Complete Pack Folder Layout

This is the exact structure the plugin expects. Drop your pack folder into plugins/CustomiZer/packs/ and run /zpack reloadpacks then /zpack zip.

packs/
└── my_pack/
    ├── configs/
    │   ├── my_items.yml          ← items / blocks / font_images definitions
    │   ├── category.yml          ← optional: GUI category for this pack
    │   └── subfolder/            ← configs can be nested in subdirectories
    │       └── more_items.yml
    │
    └── resourcepack/
        ├── pack.mcmeta           ← required Minecraft pack metadata
        └── assets/
            └── <namespace>/     ← must match info.namespace in your YMLs
                ├── models/
                │   ├── item/     ← .json model files for items
                │   └── block/    ← .json model files for blocks
                └── textures/
                    ├── item/     ← .png textures for items
                    ├── block/    ← .png textures for blocks
                    └── custom/   ← textures for font images (any subpath)

📄 pack.mcmeta (required)

Place this file at resourcepack/pack.mcmeta. Use pack_format: 34 for Minecraft 1.21+.

{
  "pack": {
    "pack_format": 34,
    "description": "My Pack"
  }
}

🔑 Registry — Auto-assigned IDs

The plugin automatically assigns Custom Model Data integers (starting at 30100) to every item and block and Unicode PUA codepoints (starting at U+EC00) to every font image. These assignments are persisted in packs/.registry.yml — they never change between restarts, so existing items in player inventories remain valid.

📂 Step 1 — Where to put the texture

Font textures are .png files placed inside the pack's resourcepack at:

resourcepack/assets/<namespace>/textures/<your-path>.png

The <your-path> value is whatever you write in the config's path: field (the .png extension is added automatically). Examples:

📄 Step 2 — Declare it in configs/

Create a YAML file anywhere inside configs/ (e.g. configs/my_fonts.yml). You can mix font images with items in the same file, or keep them separate.

info:
  namespace: gem_ranks          # must match assets/<namespace>/ folder

font_images:
  ba_i:                         # unique ID for this font image
    path: "bronze_amethyst_i"   # path under textures/ (no .png)
    scale_ratio: 12             # rendered height in pixels
    y_position: 9.5             # ascent — distance from text baseline
    permission: bronze_amethyst_i   # optional: permission to display in GUI
    show_in_gui: true               # optional: show in font browser GUI

Full field reference:

🔤 Step 3 — Apply the pack

After saving the files, run these two commands as admin:

1. /zpack reloadpacks — scans the pack and assigns a Unicode codepoint to each font image
2. /zpack zip — rebuilds the resource pack and sends it to online players

You can verify registration with /zpack fonts (lists all font IDs + their Unicode codepoints) and preview any single image with /zpack font <pack> <id> (shows it in your action bar).

✏️ Global Overrides — customfonts.yml

Override any font image's scale, position, and horizontal shift from plugins/CustomiZer/customfonts.yml without touching the pack itself. Useful for fine-tuning third-party packs.

fonts:
  gem_ranks:          # pack folder name
    ba_i:             # font image ID
      scale_ratio: 14
      y_position: 10
      x_position: -4  # horizontal pixel shift (not available in pack config)

📁 Step 1 — Put your PNG in the right folder

Create this folder if it doesn't exist, then drop your PNG inside:

plugins/CustomiZer/gui_input/<packName>/
  └── my_gui.png       ← your background image

• Replace <packName> with any name you want, e.g. my_casino_gui.
• You can put multiple PNGs in the folder — each becomes its own GUI image.
• The PNG should be the same width as a Minecraft inventory (176px wide at 1× scale, or any multiple of that).

⌨️ Step 2 — Run the command

/zpack gui <packName>
/zpack gui <packName> <namespace>   ← optional: custom namespace, defaults to packName

The plugin reads your PNG dimensions, auto-calculates the scale_ratio so the image fills the full 176px inventory width, and generates:

• plugins/CustomiZer/packs/<packName>/ — drop-in pack folder (ready for reloadpacks)
• plugins/CustomiZer/gui_output/<packName>.zip — portable ZIP to share or archive

✅ Step 3 — Apply and use

/zpack reloadpacks
/zpack zip

To use the image as a GUI title background in gui.yml:

title: "<shift:-8><font_image:my_casino_gui:my_gui>"

Preview it instantly in-game: /zpack font <packName> <id>

📁 Step 1 — Put your PNGs in the right folder

plugins/CustomiZer/rank_input/<packName>/
  ├── gold_rank.png
  ├── silver_rank.png
  └── bronze_rank.png

• Each PNG = one rank badge. The filename (without .png) becomes the badge ID.
• Make your images small — 12–20px tall works best for chat alignment.

⌨️ Step 2 — Run the command

/zpack rank <packName>
/zpack rank <packName> <namespace>   ← optional namespace

The generator uses the image's natural height as the scale_ratio (so a 12px-tall PNG renders at 12px), sets y_position: 9.5 to align with the chat baseline, and adds a permission field per badge.

✅ Step 3 — Apply and use

/zpack reloadpacks
/zpack zip

Insert a badge anywhere that accepts MiniMessage tags (chat prefix, lore, title):

<font_image:my_ranks:gold_rank> PlayerName

Each badge also gets a permission node equal to its filename (e.g. gold_rank). Gate display in your chat plugin using that node.

📁 Step 1 — Put your PNGs in the right folder

plugins/CustomiZer/item_input/<packName>/
  ├── blood_ingot.png
  ├── raw_blood.png
  └── solar_ingot.png

• Filename (without .png) = item ID. Underscores become spaces in the display name (blood_ingot → Blood Ingot).
• Use standard Minecraft item texture sizes: 16×16 or 32×32.

⌨️ Step 2 — Run the command

/zpack item <packName>
/zpack item <packName> <namespace> <material>
  ↑ material defaults to PAPER — change to e.g. DIAMOND for a different base glow

✅ Step 3 — Apply and use

/zpack reloadpacks
/zpack zip

Give items to players or yourself:

/z give <player> item blood_ingot
/z get item solar_ingot

Open the generated config at packs/<packName>/configs/<packName>.yml to add lore, actions, crafting recipes, etc.

📁 Step 1 — Name your PNGs correctly

The generator auto-detects texture splits based on filename suffixes. You have two options per block:

plugins/CustomiZer/block_input/<packName>/
  ├── oak_beam.png          ← sides (or all-faces if no _top exists)
  ├── oak_beam_top.png      ← top & bottom
  ├── stone_tile.png        ← all 6 faces identical (no _top provided)
  └── spruce_beam_top.png   ← top/bottom for spruce_beam (sides use spruce_beam.png or spruce_beam_side.png)

⌨️ Step 2 — Run the command

/zpack block <packName>
/zpack block <packName> <namespace> <material> <sound>

✅ Step 3 — Apply and use

/zpack reloadpacks
/zpack zip

/z give <player> block oak_beam     ← gives the item; right-click to place

Open packs/<packName>/configs/<packName>.yml to adjust hardness, sounds, and drops. To set what drops when mined, add an entry in blocks.yml:

blocks:
  oak_beam:
    pack_id: "<packName>:oak_beam"
    display_name: "Oak Beam"
    drops:
      - item: OAK_LOG
        amount: 1
        chance: 100

📁 Step 1 — Create one subfolder per armor set

plugins/CustomiZer/armor_input/<packName>/
  └── my_armor_set/           ← one folder per set; folder name = set ID
      ├── layer_1.png         ← REQUIRED — worn overlay: body, arms, feet
      ├── layer_2.png         ← REQUIRED — worn overlay: leggings only
      ├── helmet.png          ← optional inventory icon
      ├── chestplate.png      ← optional inventory icon
      ├── leggings.png        ← optional inventory icon
      └── boots.png           ← optional inventory icon

• layer_1.png and layer_2.png are the worn textures players see when the armor is equipped. Make them in Blockbench or any armor texture editor.
• The icon PNGs are what shows in the inventory slot. Standard 16×16 or 32×32.
• You can have multiple set subfolders under one <packName> — all sets get merged into a single pack file.

⌨️ Step 2 — Run the command

/zpack armor <packName>
/zpack armor <packName> <namespace>   ← optional namespace, defaults to packName

The generator produces a config with:

• An armors_rendering block linking layer_1 and layer_2 to the set ID
• An item entry per piece you provided (helmet/chestplate/leggings/boots) with specific_properties.armor.slot set correctly

✅ Step 3 — Apply and use

/zpack reloadpacks
/zpack zip

/z give <player> armor my_armor_set_chestplate

Open packs/<packName>/configs/<packName>.yml to optionally enable leather color tinting:

armors_rendering:
  my_armor_set:
    color: '#8c196c'    ← hex colour shown on the leather base layer
    use_color: true     ← set to true to enable tinting

📦 Pack Item Config (configs/*.yml)

This is the format for defining items inside a pack folder. The plugin reads all .yml files recursively from configs/. Every file that has an items: section is processed.

info:
  namespace: my_pack            # must match the assets/<namespace>/ folder

items:
  my_item:                      # unique item ID within this namespace
    display_name: "My Item"     # shown in-game (color codes supported)
    resource:
      material: PAPER           # base Minecraft material
      generate: false           # false = use an existing model JSON
      model_path: item/my_item  # path relative to assets/<namespace>/models/
                                # (no .json extension needed)

To auto-generate a simple flat item model from a texture (no model JSON needed):

items:
  bronze_coin:
    display_name: "Bronze Coin"
    resource:
      material: PAPER
      generate: true            # plugin generates the model automatically
      model_path: item/bronze_coin   # resolves to textures/item/bronze_coin.png

Full resource: field reference:

📂 Where to put the texture / model

Given namespace: my_pack and model_path: item/my_item:

📄 Main items.yml (action items)

Right-click action items are configured in plugins/CustomiZer/items.yml. Fields:

• NAME — Display name (color codes supported)
• MATERIAL — Vanilla Minecraft material (e.g. PAPER, DIAMOND)
• LORE — List of lore lines
• CMD — Custom model data integer (links to resource pack texture)
• COOLDOWN — Seconds before the item can be used again
• DURATION — Effect duration in seconds (for effect actions)
• AMOUNT / MAX_AMOUNT — For money/random money actions
• COMMAND — Console command to run (%player% placeholder)
• ACTION — What the item does (see table below)

📄 Sword Config Structure

• type — Minecraft material (e.g. IRON_SWORD)
• lifesteal — 0.0–1.0 fraction of damage returned as HP
• elemental_damage — Element name string
• effects-enemy — Map of effect → chance + duration applied to the hit target
• effects-self — Map of effect → chance + duration applied to the attacker
• rarity.common / rare / epic / legendary / mythical — Per-tier custom_model_data, name, and lore

📄 Armor Config Structure

• color — RGB integer for the leather dye color (e.g. 16711680 = red)
• custom_model_data — CMD for each armor piece
• display_name — Display name per piece
• lore — Lore lines per piece
• attributes — Vanilla attribute modifiers (armor, armor_toughness, attack_damage…)

📦 Pack Block Config (configs/*.yml)

Blocks are items with a specific_properties.block section. The item ID, texture, and model are registered just like a regular item, but the block placement behavior is added below:

info:
  namespace: my_pack

items:
  custom_ore:
    display_name: "Custom Ore"
    resource:
      material: PAPER             # underlying item material
      generate: true              # auto-generate cube model from 6 textures
      textures:                   # [top, bottom, north, south, east, west]
        - block/custom_ore_top
        - block/custom_ore_bottom
        - block/custom_ore_side
        - block/custom_ore_side
        - block/custom_ore_side
        - block/custom_ore_side

    specific_properties:
      block:
        placed_model:
          type: REAL_NOTE         # uses the note-block placement system
          break_particles: BLOCK  # particle type on break
          directional_mode: NONE  # NONE / LOG (4 rotations) / AXIS (2 rotations)
        cancel_drop: false        # true = don't drop the item when broken
        hardness: 3.0             # mining resistance
        sound:
          break:
            name: "BLOCK_STONE_BREAK"
            volume: 1.0
            pitch: 1.0
          place:
            name: "BLOCK_STONE_PLACE"
            volume: 1.0
            pitch: 1.0

specific_properties.block field reference:

📂 Where to put the block textures

Given namespace: my_pack and generate: true with textures listed as block/custom_ore_top:

resourcepack/assets/my_pack/textures/block/custom_ore_top.png
resourcepack/assets/my_pack/textures/block/custom_ore_bottom.png
resourcepack/assets/my_pack/textures/block/custom_ore_side.png

If using generate: false, provide a model JSON at resourcepack/assets/my_pack/models/<model_path>.json that references your textures.

📋 Block ID Formats

📄 generators.yml — Full Config Reference

worlds_populators:

  my_custom_ore:
    block: blossom_studios:oak_beam   # block ID — see formats above
    worlds:
      - world                          # exact world folder name
    replaceable_blocks:
      - STONE                          # Bukkit material names (uppercase)
      - DEEPSLATE
    biomes: []                         # empty = any biome
                                       # or list specific biomes: [PLAINS, DESERT, FOREST]
    chance: 70.0                       # 0–100 — % probability each vein attempt places a block
    amount: 8                          # vein placement attempts per newly generated chunk
    max_height: 45                     # highest Y this ore can generate
    min_height: -60                    # lowest Y (use negative for deepslate layer)

⚡ Quick Examples

Dense ore deep underground, any biome:

my_deep_ore:
  block: minecraft:ancient_debris
  worlds: [world]
  replaceable_blocks: [NETHERRACK]
  biomes: []
  chance: 40.0
  amount: 3
  min_height: -58
  max_height: 16

CustomiZer pack block, plains only:

blood_ore:
  block: ultimate_armors:blood_ore
  worlds: [world]
  replaceable_blocks: [STONE, ANDESITE, GRANITE]
  biomes: [PLAINS]
  chance: 60.0
  amount: 5
  min_height: 10
  max_height: 50

📋 Lore Placeholders

Pickaxe lore lines support dynamic placeholders that update as the pickaxe levels up:

• {level} — Current level number
• {blocks_mined} — Total blocks mined with this pickaxe
• {blocks_required} — Blocks needed to reach the next level
• {progress} — Visual progress bar

📄 Hoe Structure

• type — Vanilla hoe material
• display_name, lore — Cosmetics
• custom_model_data — Resource pack texture
• levels — Map of level keys, each with radius, money per crop, XP per crop, and specific drop overrides per crop type (WHEAT, CARROT, POTATO, etc.)
• abilities — Per-level abilities (e.g. auto-replant, fortune multiplier)

🎲 How Reforging Works

1. Open the reforge station via /zreforge or the GUI.
2. Place the item you want to reforge in the station slot.
3. Pay the reforge cost (Vault economy).
4. A random modifier is applied — modifiers can change attack damage, speed, defense, or apply special effects.
5. Re-roll as many times as desired to chase the modifier you want.

📂 Category Menu

The main category GUI shows buttons for each content type: Items, Swords, Armors, Blocks, Pickaxes, Harvesters, and Cosmetics. Clicking a category opens a subcategory menu.

📑 Subcategory Tabs

Each category has two tabs:

• Configured Items — items defined in the main plugin config files (items.yml, swords.yml, etc.)
• Pack Items — items coming from installed packs in the packs/ folder

Both tabs are independently paginated. Each category has its own subcategory configuration (title, materials, slots) in gui.yml.

🎨 Decoration & Borders

Each GUI section supports a configurable background item (fills empty slots) and a border item (fills the GUI frame). Both can be any material with a custom CMD.

📄 Pagination

When item count exceeds the available slots, pagination is enabled automatically. Previous-page, next-page, and close buttons are all individually configurable per category with custom materials, CMD, name, and slot position.