Installation

From zero to a running server with CustomiZer in five minutes.

Requirements

Step-by-Step Setup

resourcepack:
  enabled: true
  url: "http://123.456.789.0"   # Your public IP
  port: 7270                     # Port for the pack HTTP server (open this in your firewall!)

Folder Structure After First Start

config.yml

The main configuration file — resource pack server, language, messages, economy boosts.

Resource Pack Settings

This is the most important section. It controls how the pack is built and served to players.

resourcepack:
  enabled: true

  # The public URL players will download the pack from.
  # Must be reachable from the internet. Use your server's public IP or domain.
  url: "http://YOUR.PUBLIC.IP"

  # The HTTP port the plugin listens on. Open this port in your firewall.
  port: 7270

  # Resource pack format version. 46 = Minecraft 1.21.x
  format: 46

  # Optional: merge external resource pack ZIPs into the generated pack.
  # Paths are relative to your plugins/ folder.
  merge-packs:
    - "ModelEngine/resource pack.zip"

Language & Messages

language: en   # "en" or "fr"

# Whether to show a hotbar message when players earn rewards
hotbar_message_enabled: true
hotbar_message_format: "&a{job} XP: &b{jobsxp}  &aMoney: &b{money}"

# Whether to show a bossbar message
bossbar_message_enabled: true
bossbar_message_format: "{job} | XP: {jobsxp} | Money: {money}"
bossbar_color: BLUE     # BLUE, PURPLE, YELLOW, GREEN, WHITE
bossbar_style: SOLID    # SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20

WorldGuard Region Boosts

If WorldGuard is installed and enabled in settings.yml, you can multiply or divide rewards in specific regions:

# Players in "vip_mine" earn 2x XP and money
Multiplier:
  vip_mine: 2.0
  elite_zone: 3.0

# Players in "noob_area" earn half rewards
Diviser:
  noob_area: 2.0

# Time-based global boost (all players)
GlobalBoost:
  start: "18:00"
  end: "20:00"
  multiplier: 1.5

settings.yml

Debug mode, optional integration toggles, and client-specific pack settings.

# Set to true for detailed debug logs in console. Leave false on production.
debug: false

dependencies:
  # Enable if you have ItemsAdder AND want its custom blocks to give
  # CustomiZer rewards (Jobs XP, money, etc.)
  itemsadder_support: false

  # Enable if you have WorldGuard AND want region-based multipliers.
  worldguard_integration_support: false

  # Enable if you have Jobs Reborn AND want custom blocks to give Jobs XP.
  jobs_support: false

esc_menu:
  # When true: Feather Client players get the pack WITHOUT ESC menu art.
  # Feather Client is auto-detected. No setup needed.
  ignore_feather_client: false

  # When true: Lunar Client players get the pack WITHOUT ESC menu art.
  # Requires Apollo-Bukkit plugin.
  ignore_lunar_client: false

How the Resource Pack Works

Understanding what happens automatically so you know what you DON'T have to do.

The Automatic Process

When the server starts (or when you run /z reload), CustomiZer does all of this automatically:

Content Priority

When two sources try to define the same file, this order determines which wins:

Creating a Pack

A beginner-friendly walkthrough for adding your first custom pack.

What Is a "Pack"?

A pack is a folder inside plugins/CustomiZer/packs/ that contains two things:

• An assets/ folder with your texture and model files (just like a standard Minecraft resource pack)
• A configs/ folder with YAML files that tell CustomiZer what items and blocks exist in this pack

Step-by-Step: Your First Pack

info:
  namespace: my_first_pack   # Must match your assets folder name

items:
  ruby:
    display_name: "Ruby"
    resource:
      generate: true          # Auto-generate the model from the texture
      material: PAPER         # Vanilla item used as the base
      model_id: 200350        # Unique number — must not clash with other packs
      textures:
        - items/ruby.png      # Relative to assets/my_first_pack/textures/

# items/my_first_pack/gui.yml  ← shown in /zitems (admin give tool)
name: "My First Pack"
slot: 20   # Position in the /zitems main menu

icon:
  pack: my_first_pack
  id: ruby
  lore:
    - "My custom items"

gui:
  title: "My First Pack"
  size: 6

items:
  - type: pack_item
    pack: my_first_pack
    id: ruby

Namespace Rules

• The namespace in info.namespace must be lowercase, no spaces, no special characters
• It must match the folder name inside assets/
• You reference items from this pack as namespace:item_key — for example my_first_pack:ruby

Pack Items

Define custom items inside your pack. These are the visual layer — textures, models, and materials.

How items are split across two files

Like blocks, items live in two config files. The pack file controls appearance; the CustomiZe! file controls behaviour.

Simple Item with Auto-Generated Model

Use this when you have a flat PNG texture and want CustomiZer to automatically make a Minecraft item model:

info:
  namespace: my_pack

items:
  # The key "ruby" is how you reference this item everywhere else.
  # Format: namespace:key → "my_pack:ruby"
  ruby:
    display_name: "Ruby"   # Shown in-game (supports color codes)
    resource:
      generate: true        # true = auto-generate model from textures
      material: PAPER       # Vanilla material (PAPER is a common choice for flat items)
      model_id: 200350      # Custom Model Data (must be globally unique)
      textures:
        - items/ruby.png    # In assets/my_pack/textures/items/ruby.png

Item with a Hand-Crafted Model

Use this when you have a pre-made 3D model JSON (e.g. from Blockbench):

  dragon_sword:
    display_name: "Dragon Sword"
    resource:
      generate: false                        # false = use the model at model_path
      material: IRON_SWORD                   # Use a sword material for handheld animation
      model_path: weapons/dragon_sword       # In assets/my_pack/models/weapons/dragon_sword.json

Item with Permission

Only players with the specified permission can see or use this item:

  vip_gem:
    display_name: "VIP Gem"
    permission: myserver.vip.gem   # Optional permission node
    resource:
      generate: true
      material: PAPER
      model_id: 200351
      textures:
        - items/vip_gem.png

Item Field Reference

Pack Blocks

Custom blocks that can be placed in the world, using note-block states under the hood for real solid placement with custom textures.

How blocks are split across two files

Custom blocks use two config files that work together — one for visuals, one for gameplay. This is the same pattern used by every other pack content type.

packs/your_pack/configs/blocks.yml

This file registers the block in the resource pack — textures, placement type, and break sounds. The material is the base item players hold to place the block (use BRICK for most blocks). The model ID is assigned automatically from the texture.

# packs/my_pack/configs/blocks.yml

info:
  namespace: my_pack

items:
  silver_ore:
    display_name: "Silver Ore"
    material: BRICK               # Base item held in hand to place the block
    resource:
      generate: true
      textures:
        - blocks/silver_ore.png   # Path inside assets/my_pack/textures/

    specific_properties:
      block:
        placed_model:
          type: REAL_NOTE         # Uses the note-block trick for real solid placement
        sound:
          break:
            name: "BLOCK_STONE_BREAK"
            volume: 1
            pitch: 1

  deepslate_silver_ore:
    display_name: "Deepslate Silver Ore"
    material: BRICK
    resource:
      generate: true
      textures:
        - blocks/deepslate_silver_ore.png
    specific_properties:
      block:
        placed_model:
          type: REAL_NOTE
        sound:
          break:
            name: "BLOCK_DEEPSLATE_BREAK"
            volume: 1
            pitch: 1

CustomiZe!/your_pack/blocks.yml

This file links the pack block to its gameplay behaviour. The pack_id uses the format namespace:item_id and matches the entry in your packs/configs file. See the Custom Blocks (CustomiZe!) page for all available options.

# CustomiZe!/my_pack/blocks.yml

blocks:

  silver_ore:
    pack_id: "my_pack:silver_ore"      # namespace:item_id from packs/configs
    display_name: "&fSilver Ore"
    lore:
      - "&7A rare silver deposit."
    drop_self: true                    # Block drops itself when broken
    break_with:
      - HAND
      - WOODEN_PICKAXE
      - STONE_PICKAXE
      - IRON_PICKAXE
      - GOLDEN_PICKAXE
      - DIAMOND_PICKAXE
      - NETHERITE_PICKAXE
    drops:
      - type: plugin_item             # Drop a plugin custom item
        item: silver_ingot
        amount: 1
        chance: 100
      - type: vanilla                 # Drop a vanilla item
        item: IRON_NUGGET
        amount_min: 1
        amount_max: 3
        chance: 50
      - type: command                 # Run a console command on break
        command: "eco give %player% 5"
        chance: 25

  deepslate_silver_ore:
    pack_id: "my_pack:deepslate_silver_ore"
    display_name: "&8Deepslate Silver Ore"
    lore:
      - "&7A rare silver deposit in deepslate."
    drop_self: false
    break_with:
      - IRON_PICKAXE
      - DIAMOND_PICKAXE
      - NETHERITE_PICKAXE
    drops:
      - type: plugin_item
        item: silver_ingot
        amount_min: 1
        amount_max: 2
        chance: 100

Pack Tools

Retextured vanilla tools and weapons — custom appearance, with optional advanced mechanics in the CustomiZe! folder.

How tools are split across two files

Simple retextured tools only need the packs/configs file. If you want rarity progression, custom durability, level-up systems, or special effects — add the mechanics side in CustomiZe!.

Tools in packs/configs follow the same format as pack items — same material, generate, and textures fields:

info:
  namespace: my_pack

items:
  silver_sword:
    display_name: "Silver Sword"
    resource:
      generate: true
      material: IRON_SWORD    # Stats of an iron sword, custom texture
      model_id: 200500
      textures:
        - tools/silver_sword.png

  silver_pickaxe:
    display_name: "Silver Pickaxe"
    resource:
      generate: true
      material: IRON_PICKAXE  # Stats of an iron pickaxe, custom texture
      model_id: 200501
      textures:
        - tools/silver_pickaxe.png

  mythril_axe:
    display_name: "Mythril Axe"
    resource:
      generate: true
      material: DIAMOND_AXE   # Diamond stats
      model_id: 200502
      textures:
        - tools/mythril_axe.png

Good material choices by tool type

Font Images (Glyphs)

PNG images rendered as text characters — used for GUI backgrounds, rank badges, icons in lore, and ESC menu art.

What Is a Font Image?

Minecraft supports custom fonts where each character can be replaced with a PNG image. CustomiZer uses this to render images anywhere text is shown — including inventory titles, item lore, chat, scoreboards, and the ESC menu.

This is how the fancy GUI backgrounds, the rank icons in chat, and the ESC menu logos work. They're all just carefully positioned PNG images rendered as "characters".

Defining Font Images in a Pack

Create a font.yml (or any .yml file) in your pack's configs/ folder:

info:
  namespace: my_pack

font_images:
  my_icon:                           # Key used to display this image
    path: "font/my_icon.png"         # In assets/my_pack/textures/font/my_icon.png
    scale_ratio: 11                  # Size of the image in pixels (height)
    y_position: 9                    # Vertical offset from the text baseline

Using a Font Image in Text

Once defined, you display the image using the MiniMessage <font_image> tag:

title: "<font_image:my_pack:my_icon>"
# or in item lore:
lore:
  - "<font_image:my_pack:my_coin> 500 coins"

The image appears inline wherever text appears — in inventory titles, item names, lore lines, chat messages, etc.

Rank Badge Glyphs (gem_ranks example)

Font images can be permission-gated. When show_in_gui: true is set, players with the required permission see their rank badge displayed in the GUI:

info:
  namespace: gem_ranks

font_images:
  bronze_amethyst_i:
    permission: bronze_amethyst_i     # Player needs this permission to see this glyph
    show_in_gui: true                 # Show in the rank GUI
    path: "bronze_amethyst_i"         # assets/gem_ranks/textures/bronze_amethyst_i.png
    scale_ratio: 12
    y_position: 9.5

  gold_diamond_iii:
    permission: gold_diamond_iii
    show_in_gui: true
    path: "gold_diamond_iii"
    scale_ratio: 12
    y_position: 9.5

Give a player the permission gem_ranks.bronze_amethyst_i and they'll see that badge appear next to their name or in the rank GUI.

GUI Background Font Images

The GUI background (the image behind the inventory grid) is also a font image. It's rendered in the inventory title with special pixel-offset characters:

info:
  namespace: CustomiZerInternal

font_images:
  "1":
    path: custom/30main_gui/1    # The GUI background image
    scale_ratio: 255             # Large scale = full inventory background
    y_position: 46
    x_position: -6.5

Then in the GUI title:

title: "<white><shift:-8><font_image:CustomiZerInternal:1>"

The <shift:-8> is a pixel offset that positions the background image correctly.

Tips for Font Images

• scale_ratio: The height of the image in game pixels. 11–12 is good for small icons. 255 is used for full-screen GUI backgrounds.
• y_position: Move the image up or down relative to the text line. Positive = up, negative = down.
• Always use PNG with transparency for icons and badges.
• Test your glyphs by giving yourself a paper item with the font tag in its name.

In-Game Glyph Commands

CustomiZer includes a full set of admin commands to browse, search, preview, and manage glyphs directly in-game. All of these require the cxp.admin permission.

/zpack fonts

Lists every registered font image across all packs. Shows the pack name, font ID, Unicode codepoint, and the exact tag you need to paste into gui.yml:

# Example output in chat:
# [CustomiZer] Registered font images (12):
#   gem_ranks:bronze_amethyst_i  U+E000  → gui.yml: <font_image:gem_ranks:bronze_amethyst_i>
#   my_pack:my_icon              U+E001  → gui.yml: <font_image:my_pack:my_icon>

/zpack font <packName> <fontId>

Previews a single glyph. Sends it to your action bar so you can see exactly how it looks in-game. Run this whenever you add a new font image and want to check its size and position.

/zpack glyph list [packName]

Lists all registered glyphs (with the Glyph API metadata). Add a pack name to filter to just that pack's glyphs:

# All glyphs:
/zpack glyph list

# Only glyphs from "gem_ranks":
/zpack glyph list gem_ranks

Each entry shows the pack name, font ID, Unicode codepoint, and two clickable links — [copy tag] copies the full <font_image:pack:id> tag ready to paste into any YAML, and [copy char] copies the rendered Unicode character itself. No need to open any YAML file — find the glyph you want in chat, click copy, paste it wherever you need it.

/zpack glyph <packName> <fontId>

Shows detailed info about one specific glyph — its codepoint, the Unicode character, and the YAML tag to use it.

/zpack glyph search <query>

Searches all registered glyphs by name. Useful when you have many font images and can't remember the exact ID:

/zpack glyph search bronze

/zpack glyph export

Prints YAML snippets for every registered glyph. Useful if you want to lock codepoints so they don't change after a reload (copy the output into your pack configs).

/zpack glyph regenerate

Clears the entire glyph codepoint registry and reassigns all codepoints from scratch. Use this if codepoints have gotten misaligned after adding or removing glyphs. Warning: players must re-download the resource pack after running this.

PlaceholderAPI Integration

If PlaceholderAPI is installed, you can use glyphs as placeholders anywhere that supports PAPI:

Example in a LuckPerms prefix: [%customizer_glyph_gem_ranks_gold_i%] — this renders the gold rank icon next to the player's name in chat.

ESC Menu Customization

Replace the vanilla pause menu text (like "Game Menu" and "Disconnect") with custom PNG images.

How It Works

Minecraft's ESC menu buttons show text from language files — for example, the title reads whatever the translation of menu.game says. CustomiZer injects custom font characters into those translation strings, replacing the text with your PNG image characters.

The result: players open their ESC menu and instead of "Game Menu" they see your server's logo image.

Setting It Up

Create a YAML config file in your pack's configs/ folder:

info:
  namespace: my_esc_pack

minecraft_lang_overwrite:
  esc_menu_texts:
    entries:
      # Replace the "Game Menu" title with your logo image
      "menu.game": ":top_logo_1::offset_-1:"

      # Replace the "Disconnect" button text with a custom banner image
      "menu.disconnect": ":offset_-10::offset_-256::bottom_banner::offset_-256:"

    # Apply to all language files (ALL), or specific ones: [en_us, fr_fr]
    languages:
      - ALL

    # For Lunar Client players (requires Apollo-Bukkit):
    # Set this to the resource location of the same logo image
    apollo_icon: "my_esc_pack:textures/top_logo_1.png"

The Token Syntax

Inside the string value, you use colon-wrapped tokens:

• :my_image_key: — renders the font image defined as my_image_key in your font.yml
• :offset_-256: — moves the cursor left by 256 pixels (used to position images)
• :offset_10: — moves the cursor right by 10 pixels

Client Compatibility

The CustomiZe! Folder

Where you configure gameplay mechanics — completely separate from the visual pack system.

Why Is It Separate?

The packs/ folder handles appearance — textures, models, sounds. The CustomiZe!/ folder handles behavior — how items work in the game.

This separation exists because many servers want to use third-party resource packs (bought or downloaded) exactly as-is, without modifying them. By keeping behavior config separate, you can use any pack's textures while fully controlling how those items work on your server.

Folder Structure

How Merging Works

All CustomiZe!/*/swords.yml files are deep-merged together at load time. __global__ loads first, then each pack folder alphabetically. This means:

• You can add pack-specific swords in CustomiZe!/my_pack/swords.yml without touching the global file
• All packs' items/blocks/swords/etc. are combined into one big list
• If two files define the same key, the later-loading file wins (alphabetical order)

Quick Reference — Which file for what?

Custom Items

Usable items with click actions, cooldowns, limited uses, and food effects.

What Is a Custom Item?

A custom item is any item that does something special when right-clicked (or eaten). Examples: a scroll that runs a command, a health potion that restores hearts, a money bag that gives currency, a food item that applies potion effects.

Custom items are defined here. The texture comes from a pack item in packs/. You connect them by matching the MODELDATA number to the model_id in your pack.

Full Example

items:
  teleport_scroll:
    TYPE: PAPER                     # Vanilla material (must match the pack item's material)
    NAME: "&d✦ Teleport Scroll"
    LORE:
      - "&7Right-click to teleport to spawn."
      - "&8Cooldown: 30 seconds"
      - "&8Uses: &f%uses% &8remaining"
    MODELDATA: 12000               # Must match the model_id in your pack item definition
    COOLDOWN: 30                   # Seconds between uses
    USE: 5                         # Item breaks after 5 uses (-1 = unlimited)
    INTERACTS:
      - RIGHT_CLICK_AIR
      - RIGHT_CLICK_BLOCK
    ACTION:
      TYPE: COMMAND
      COMMAND: "spawn %player%"    # %player% is replaced with the player's name

All ACTION Types

INTERACTS Options

Controls which clicks trigger the action:

Food Items

Any item can be made edible — even PAPER. Add a FOOD block and set ACTION TYPE: EAT:

items:
  magic_herb:
    TYPE: PAPER
    NAME: "&aMagic Herb"
    LORE:
      - "&7Eat to gain Regeneration and Speed."
    MODELDATA: 12010
    COOLDOWN: 0
    USE: -1
    INTERACTS: []       # Empty — eating triggers the action, not clicking
    ACTION:
      TYPE: EAT
    FOOD:
      NUTRITION: 4              # Hunger bars restored (2 = one drumstick)
      SATURATION: 0.6           # Saturation added (0.0–1.0)
      CAN_ALWAYS_EAT: true      # Player can eat this even when not hungry
      EFFECTS:
        - effect: REGENERATION
          duration: 200          # ticks (20 ticks = 1 second, so 200 = 10 seconds)
          amplifier: 1           # 0 = Level I, 1 = Level II, 2 = Level III
          chance: 1.0            # 100% chance
        - effect: SPEED
          duration: 100          # 5 seconds
          amplifier: 0           # Speed I
          chance: 0.5            # 50% chance — might not apply!

Lore Placeholders

In item lore you can use %uses% to show remaining uses dynamically. Color codes (&a, &6, etc.) and MiniMessage tags work in both NAME and LORE.

Custom Swords & Axes

Custom weapons with attributes, enchants, hit effects, elemental damage, and lifesteal. Every feature listed below is optional — a sword needs zero special config to work as a plain custom item.

All Config Keys

Attributes

Written as a flat map under attributes:. Values are added on top of the base material's default stats. All are optional — include only what you need.

Enchantments

Written as enchantments: section with enchantment name (Bukkit Registry key) → level:

enchantments:
  sharpness: 5
  unbreaking: 3
  looting: 2
  fire_aspect: 2
  knockback: 2
  sweeping_edge: 3

Hit Effects (effects-enemy / effects-self)

Each entry under effects-enemy or effects-self is a potion effect key with two sub-keys:

The effect name is the Bukkit PotionEffectType registry key. Common ones:

Elemental Damage

Set elemental_damage to one of these values. Each triggers a different effect on hit:

Lifesteal

Lifesteal is automatic when the rarity block is present — you do not configure it manually. The amount scales with the current rarity tier:

Lore Placeholders

Minimal Example (No Levelling)

swords:
  fire_sword:
    type: IRON_SWORD
    display_name: "&c&l🔥 Fire Sword"
    durability: 3000
    HIDE-ENCHANTS: true
    lore:
      - "&7A sword kissed by flame."
      - "&8Durability: %custom_durability% / %max_custom_durability%"
    attributes:
      GENERIC_ATTACK_DAMAGE: 8.0
      GENERIC_ATTACK_SPEED: 1.8
    enchantments:
      unbreaking: 3
      looting: 2
    effects-enemy:
      slowness:
        chance: 0.5        # 50% chance per hit
        duration: 60       # 3 seconds
    elemental_damage: Fire

Full Example (With Rarity Levelling)

swords:
  dragon_blade:
    type: IRON_SWORD
    display_name: "&4Dragon Blade"
    durability: 5000
    HIDE-ENCHANTS: true
    lore:
      - "&8Rarity: %rarity%"
      - "&8Progress: %progress% / %required% kills"
      - "&8Durability: %custom_durability% / %max_custom_durability%"
    attributes:
      GENERIC_ATTACK_DAMAGE: 10.0
      GENERIC_ATTACK_SPEED: 1.6
    enchantments:
      sharpness: 3
      looting: 2
    effects-enemy:
      slowness:
        chance: 0.40
        duration: 60
      weakness:
        chance: 0.25
        duration: 100
    effects-self:
      strength:
        chance: 0.15
        duration: 120
    elemental_damage: Fire

    # Remove this entire rarity block if you don't want levelling
    rarity:
      common:
        custom_model_data: 32001
        name: "&7Common Dragon Blade"
      rare:
        custom_model_data: 32002
        name: "&9Rare Dragon Blade"
      epic:
        custom_model_data: 32003
        name: "&5Epic Dragon Blade"
      legendary:
        custom_model_data: 32004
        name: "&6Legendary Dragon Blade"
      mythical:
        custom_model_data: 32005
        name: "&dMythical Dragon Blade"

Custom Armors

Armor pieces with stat bonuses, potion effects while worn, armor trim cosmetics, and 3D equippable models.

All Config Keys

Attributes

Attributes are a list. Each entry is a map with three keys: attribute, amount, and operation. All are bound to the armor's equipment slot automatically.

Attribute Operations

Potion Effects (While Worn)

Each entry in potion_effects is a map with three keys:

Armor Trim

Adds a purely cosmetic pattern overlay on the armor texture. Both keys are required if you include the trim section.

trim:
  material: GOLD         # Trim color material (GOLD, IRON, DIAMOND, NETHERITE, etc.)
  pattern: WAVY          # Trim pattern (SENTRY, DUNE, COAST, WILD, WARD, EYE, VEX, TIDE,
                         # SNOUT, RIB, SPIRE, SILENCE, FLOW, BOLT, WAVY, SHAPER, RAISER, HOST)

Equippable (3D Worn Model)

The equippable section sets a 3D model that appears on the player's body when they wear the armor. Requires Minecraft 1.21.4+ clients.

equippable:
  model: "my_pack:dragon_armor"               # Resource location of the equippable model
  equip_sound: "minecraft:item.armor.equip_diamond"  # Sound when equipping

Full Example

custom_armors:
  dragon_helmet:
    pack_id: "my_pack:dragon_helmet"   # Pulls material + CMD from PackManager

    display_name: "&4&lDragon Helmet"
    lore:
      - "&7Forged from dragonscale."
      - "&8+4 Max Health | +3 Armor"

    attributes:
      - attribute: GENERIC_MAX_HEALTH
        amount: 4.0
        operation: ADD_NUMBER        # +2 extra hearts
      - attribute: GENERIC_ARMOR
        amount: 3.0
        operation: ADD_NUMBER

    potion_effects:
      - effect: fire_resistance
        duration: 999999             # Permanent while worn
        amplifier: 0                 # Level I
      - effect: night_vision
        duration: 999999
        amplifier: 0

    trim:
      material: GOLD
      pattern: WAVY

    equippable:
      model: "my_pack:dragon_armor"
      equip_sound: "minecraft:item.armor.equip_diamond"

Custom Blocks — Gameplay Side

This file controls everything that happens when a custom block is placed or mined — hardness, blast resistance, drops, required tools, light emission, display name, lore, sounds, particles, and Jobs XP. It is the companion to packs/blocks.yml which only handles textures.

The Two-File Rule (Quick Reminder)

Full Block Configuration

Here is a complete example showing every available option for one block. Use only the fields you need — most are optional.

# CustomiZe!/my_pack/blocks.yml

blocks:
  silver_ore:
    # Links this entry to packs/my_pack/configs/blocks.yml → silver_ore
    # Format: "namespace:item_key"  (namespace = pack's info.namespace value)
    pack_id: "my_pack:silver_ore"

    # Rich display name shown in lore and break messages.
    # Supports MiniMessage tags (gradients, colours, bold, etc.)
    display_name: "Silver Ore"

    # Lore lines shown when the block item is in the player's hand.
    lore:
      - "A pale metallic ore."
      - "▸ Drops Raw Silver when mined."

    # Mining time — mirrors vanilla hardness values.
    # Higher = slower to mine. Omit to use vanilla NOTE_BLOCK timing (very fast).
    # Reference: stone=1.5, iron_ore=3.0, deepslate_ore=4.5, obsidian=50.0
    hardness: 3.0

    # Explosion resistance. Blocks with this set are fully protected from
    # TNT, creeper, and other explosion damage. Omit to allow destruction.
    blast_resistance: 3.0

    # Light emission level (0 = no light, 15 = full torch-level light).
    # When set above 0, the server places a hidden LIGHT block so real
    # light propagates. Players still see the ore texture, not the light block.
    light_level: 8

    # Whether the block drops its own block item when broken.
    # false = use the drops list below instead (recommended for ores)
    # true  = the block item itself drops (good for decorative blocks)
    drop_self: false

    # ── Which tools can break this block ──────────────────────────────────
    # List vanilla material names and/or custom pickaxe IDs from pickaxes.yml.
    # Omit this key entirely → any tool works (including bare hand).
    # Set to an empty list [] → completely indestructible in survival.
    break_with:
      - IRON_PICKAXE
      - GOLDEN_PICKAXE
      - DIAMOND_PICKAXE
      - NETHERITE_PICKAXE
      - silver_lithium_pickaxe    # A custom pickaxe key from CustomiZe!/pickaxes.yml

    # ── What the block drops when broken ──────────────────────────────────
    # Multiple drops are all rolled independently (each has its own chance).
    drops:
      # type: plugin_item — a custom item defined in CustomiZe!/items.yml
      - type: plugin_item
        item: "my_pack:raw_silver"   # format: "pack_namespace:item_key"
        amount: 1                     # exact amount
        chance: 100                   # 100 = always drops

      # Use amount_min / amount_max for a random range:
      - type: plugin_item
        item: "my_pack:silver_shard"
        amount_min: 0
        amount_max: 2
        chance: 40                    # 40% chance to drop 0–2 shards

      # type: vanilla — any standard Bukkit material name
      - type: vanilla
        item: EXPERIENCE_BOTTLE
        amount_min: 1
        amount_max: 1
        chance: 20                    # 20% chance

      # type: command — runs a console command when this block is broken
      # %player% is replaced with the breaker's name
      - type: command
        command: "eco give %player% 5"
        chance: 50                    # 50% chance to give 5 coins

    # Optional sound played to the breaker when the block is mined.
    # Use any Minecraft sound key (tab-complete with /playsound).
    soundeffectonmined: "block.amethyst_block.break"

    # Optional particle effect shown when the block is mined.
    # Use any Bukkit Particle enum name.
    visualeffectonmined: "VILLAGER_HAPPY"


  # ── Decorative block example (drop_self: true) ──────────────────────────
  oak_beam:
    pack_id: "my_pack:oak_beam"
    display_name: "&fOak Beam"
    lore:
      - "&7A decorative oak wood beam."
    hardness: 2.0            # Mines at log speed
    blast_resistance: 2.0
    drop_self: true          # Drops the block item itself (no drops list needed)
    break_with:
      - HAND                 # Can be broken by bare hand
      - WOODEN_AXE
      - STONE_AXE
      - IRON_AXE
      - GOLDEN_AXE
      - DIAMOND_AXE
      - NETHERITE_AXE


# ── XP and money rewards ─────────────────────────────────────────────────────
# Works for BOTH your custom pack blocks AND vanilla Minecraft blocks.
# Add this section anywhere in the file (or in __global__/blocks.yml).
xp_values:

  # Custom block: use "namespace:item_key" (same as pack_id above)
  my_pack:silver_ore:
    name: "Silver Ore"
    jobsxp: 8.0              # XP given to the Jobs plugin job
    job: "Miner"             # The Jobs job name (must match your jobs config)
    money: 5.0               # Vault economy money given to the player
    points: 2.0              # Server points / custom currency
    cancel-vanilla-drops: false   # true = stop vanilla drops (useful for custom ores)

  # Vanilla block: use the Bukkit material name
  COAL_ORE:
    name: "Coal Ore"
    jobsxp: 2.0
    job: "Miner"
    money: 1.0
    points: 0.5
    cancel-vanilla-drops: false

All Fields at a Glance

Drop Types

Custom Pickaxes

Pickaxes that level up as players mine — each level unlocks new textures, area mining, and Haste effects.

How Pickaxe Levelling Works

Each pickaxe tracks how many blocks the player has mined with it. When the count reaches blocks_required for the current level, the pickaxe automatically upgrades to the next level. The upgrade:

• Changes the Custom Model Data → new texture appears
• Increases durability, mining radius, and effect level
• Updates the lore to show the new stats
• Notifies the player

Full Configuration Example

pickaxes:
  tier_pickaxe:
    type: DIAMOND_PICKAXE
    display_name: "⛏ Tier Pickaxe"
    lore:
      - "⛏ Level: %level% / %max_level%"
      - "Blocks mined: %blocks_mined% / %blocks_required%"
      - "Durability: %current_durability% / %max_durability%"
      - "Mining area: %radius%×%radius%"
      - "%bonuses%"

    levels:
      # Level 1 — Starting tier
      1:
        name: "⛏ Tier Pickaxe [Lvl. 1]"
        custom_model_data: 30041        # Texture for level 1 (wooden-looking)
        durability: 2000
        radius: 1                       # Mines 1×1 (just the block you click)
        height_radius: 0                # 0 = only the exact height level mined
        effect_on_hold: haste
        effect_amplifier: 0             # 0 = Haste I
        blocks_required: 200            # Mine 200 blocks to reach level 2
        bonus:
          - "• Haste I while held"

      # Level 2
      2:
        name: "⛏ Tier Pickaxe [Lvl. 2]"
        custom_model_data: 30042        # New texture (stone-looking)
        durability: 4000
        radius: 1
        height_radius: 1               # Mines 1 block above and below too (3 tall)
        effect_on_hold: haste
        effect_amplifier: 0
        blocks_required: 500
        bonus:
          - "• Haste I while held"
          - "• 1×3 column mining"

      # Level 3
      3:
        name: "⛏ Tier Pickaxe [Lvl. 3]"
        custom_model_data: 30043        # New texture (iron-looking)
        durability: 7000
        radius: 3                       # Mines 3×3 area
        height_radius: 1
        effect_on_hold: haste
        effect_amplifier: 1             # Haste II
        blocks_required: 1000
        bonus:
          - "• Haste II while held"
          - "• 3×3 area mining"

      # Level 4 — Final tier
      4:
        name: "⛏ Tier Pickaxe [Lvl. 4]"
        custom_model_data: 30044        # New texture (diamond/netherite-looking)
        durability: 12000
        radius: 3
        height_radius: 3               # Mines 3×7 tall area
        effect_on_hold: haste
        effect_amplifier: 1
        blocks_required: 0             # 0 = MAX LEVEL, no further upgrade
        bonus:
          - "• Haste II while held"
          - "• 3×7 area mining"
          - "• MAX LEVEL"

All Per-Level Config Keys

Lore Placeholders

Harvester Hoes

Auto-harvesting, auto-replanting hoes with an XP-based levelling system, custom drop tables, and Vault economy auto-sell. The levelling system is built-in.

How Harvester Hoes Work

When a player right-clicks a crop with a configured harvester hoe, the plugin:

1. Checks if the crop type is in supported-crops for this hoe
2. Harvests the crop and optionally drops custom items (from the drops table)
3. If auto-replant is enabled, replants the crop at replant-growth-stage
4. If auto-sell is enabled, deposits money for the harvest directly to the player's balance
5. Grants XP from xp-values and checks experience.level-up-requirements for a level-up
6. Decrements uses by 1. When uses hit 0, the hoe breaks.

Top-Level Hoe Keys

Supported Crops (supported-crops)

Use vanilla Minecraft block material names:

Abilities (Levelling System)

The abilities section is where the levelling system lives. Each sub-key is a level name (e.g. level-0, level-1). level-0 is the starting state when the hoe is first created. The plugin upgrades to the next level name when XP thresholds are hit.

Per-Level Ability Keys

XP Levelling (experience)

The experience.level-up-requirements section maps level names to cumulative XP totals. When the player's accumulated XP reaches the threshold, the hoe upgrades to that level automatically:

experience:
  level-up-requirements:
    level-1: 100     # Reach 100 XP → upgrade to level-1
    level-2: 300     # Reach 300 total XP → upgrade to level-2
    level-3: 600     # Reach 600 total XP → upgrade to level-3

XP is gained per harvest. The amount comes from xp-values:

xp-values:
  WHEAT: 5           # +5 XP per wheat harvested
  CARROTS: 7         # +7 XP per carrot
  POTATOES: 6        # +6 XP per potato
  CUSTOM_CROP: 3     # XP for any custom crop (from CustomiZer's crop system)

Custom Drop Table (drops)

Defines what items drop when a crop is harvested. Organized by crop material → named drop entries:

drops:
  WHEAT:                          # Crop type
    wheat_item:                   # Any unique key for this drop entry
      item: WHEAT                 # Vanilla material name OR vanilla mapping
      chance: 1.0                 # 0.0–1.0 probability (1.0 = 100%)
      quantity: 1                 # How many to drop
    seeds:
      item: WHEAT_SEEDS           # Wheat seeds as a bonus drop
      chance: 0.5                 # 50% chance
      quantity: 2

  CARROTS:
    carrot_drop:
      item: CARROT                # Note: plugin auto-maps CARROTS block → CARROT item
      chance: 1.0
      quantity: 1
    bonus_carrot:
      item: CARROT
      chance: 0.3
      quantity: 3

Auto-Sell Prices (economy)

Required if any ability level has auto-sell: true. Price is per unit, multiplied by the current level's drop-multiplier:

economy:
  sell-prices:
    WHEAT: 50.0        # 50 coins per wheat
    CARROTS: 75.0
    POTATOES: 60.0
    BEETROOTS: 45.0

Messages

All message keys are optional. If not defined, no message is sent for that event.

Lore Placeholders

Only one special placeholder exists for hoe lore:

Full Example

hoes:
  harvest_hoe:
    base-item: GOLDEN_HOE
    custom-model-data: 10000        # Starting CMD (level-0 CMD overrides this)
    name: "🌾 Harvest Hoe"
    uses: 100                       # Base uses at level-0

    supported-crops:
      - WHEAT
      - CARROTS
      - POTATOES
      - BEETROOTS

    xp-values:
      WHEAT: 5
      CARROTS: 7
      POTATOES: 6
      BEETROOTS: 4

    experience:
      level-up-requirements:
        level-1: 100
        level-2: 300
        level-3: 700

    drops:
      WHEAT:
        wheat:
          item: WHEAT
          chance: 1.0
          quantity: 1
        seeds:
          item: WHEAT_SEEDS
          chance: 0.4
          quantity: 1

    abilities:
      level-0:
        name: "&7🌾 Harvest Hoe [Lv.0]"
        lore:
          - "&8Uses: &f<uses>"
          - "&7Harvest crops automatically."
        model-data: 10000
        use-multiplier: 1
        drop-multiplier: 1
        auto-sell: false
        auto-replant: true
        replant-growth-stage: 0

      level-1:
        name: "&a🌾 Harvest Hoe [Lv.1]"
        lore:
          - "&8Uses: &f<uses>"
          - "&7+50% drops | Auto-replant"
        model-data: 10001           # New texture
        use-multiplier: 2           # 100 × 2 = 200 uses at this level
        drop-multiplier: 2          # 50% more drops (int, so effectively doubles)
        auto-sell: false
        auto-replant: true

      level-2:
        name: "&6🌾 Harvest Hoe [Lv.2]"
        lore:
          - "&8Uses: &f<uses>"
          - "&7Auto-sell enabled | Double drops"
        model-data: 10002
        use-multiplier: 3           # 100 × 3 = 300 uses
        drop-multiplier: 2
        auto-sell: true             # Crops sold directly to wallet
        auto-replant: true

economy:
  sell-prices:
    WHEAT: 50.0
    CARROTS: 75.0
    POTATOES: 60.0
    BEETROOTS: 45.0

messages:
  exp-gain: "&aGained &f{amount} &aXP! &8Total: &f{total}"
  level-up: "&6🎉 Your {hoe} levelled up to &e{level}&6!"
  auto-sell: "&aAuto-sold crops for &6{amount} coins."

Cosmetics

Wearable display items — hats, back items, wings — that players can equip without replacing armor.

cosmetics:
  cool_hat:
    pack_id: "my_pack:cool_hat"      # References the pack item for texture
    display_name: "✦ Cool Hat"
    slot: hat                         # Where to equip: hat | back | wings | offhand
    lore:
      - "A very stylish hat."
      - "Right-click to equip or swap!"
    permission: "myserver.hats.cool"  # Optional — only players with this perm can use it

  angel_wings:
    pack_id: "my_pack:angel_wings"
    display_name: "🪶 Angel Wings"
    slot: back

Backpacks

Physical backpack items that open a persistent inventory. The inventory is bound to the item, not the player — trade the backpack to transfer all its contents.

How it works

• Every backpack item gets a unique UUID stamped in its PDC (customizer:backpack_instance_uuid) when given.
• The inventory is stored by that UUID (SQLite or MongoDB) — so two backpacks of the same type have separate inventories.
• Players run /backpack while holding the backpack in their offhand (or wearing it on their chestplate) to open it.
• Hoppers and plugins cannot move items into or out of an open backpack inventory.

storage:
  type: sqlite          # "sqlite" or "mongodb"
  sqlite:
    file: db/backpacks.db  # stored in plugins/CustomiZer/db/

backpacks:
  adventure_backpack_1:
    pack_id: "elitecreatures:adventure_backpack_cosmetic_backpack_1"
    display_name: "<gold><bold>🎒 Adventure Backpack I"
    slots: 18           # 9, 18, 27, 36, 45, or 54  (or use rows: 1-6)
    permission: "myserver.backpack.tier1"   # optional
    lore:
      - "<dark_gray>18 slots"
      - "<gray>Wear on chest or hold in offhand, run <yellow>/backpack"

  large_backpack:
    pack_id: "elitecreatures:large_backpack"
    display_name: "<green>🎒 Large Backpack"
    rows: 4             # equivalent to slots: 36

Giving backpacks

Add the backpack as a type: backpack entry in your gui.yml — it will appear in /zitems and clicking gives the physical item (with UUID stamped and lore applied):

items:
  - type: backpack
    pack: elitecreatures
    id: adventure_backpack_cosmetic_backpack_1
    name: "<gold><bold>🎒 Adventure Backpack I"
    lore:
      - "<dark_gray>18 slots"
      - "<gray>Hold in offhand → /backpack"

Storage backends

Gem Sockets

A socketing system where players insert gems into weapons and armor for stat bonuses that wear down over time.

Example — Steve sockets a 🔥 Fire Rune into his sword

A full walkthrough of how a player uses /zsocket from start to finish. The Fire Rune adds +2.5 Attack Damage, so it goes into a weapon.

Config Reference

socket_char: "◈"
empty_socket_lore: "◈ Empty Socket"
max_sockets: 4

# Default uses for gems that don't set their own. -1 = unlimited.
default_max_uses: -1

gem_decay:
  enabled: true
  interval_seconds: 60   # 1 use consumed per minute of equip time

gems:
  water_rune:
    display_name: "💧 Water Rune"
    type: PAPER
    model_data: 200377
    tier: 2
    stat: armor
    value: 1.5
    max_uses: 100          # -1 for unlimited
    lore:
      - "Tier: Awakened"
      - "+1.5 Armor when socketed."

Armor Sets

Equip N matching armor pieces to unlock bonuses — potion effects, console commands, and messages. Bonuses activate and deactivate automatically as pieces are equipped or removed.

How Sets Work

Each armor piece registered in armors.yml has a unique key (e.g. dragon_helmet). The sets.yml file groups those keys into sets and defines what happens at each threshold (2 pieces equipped, 3 pieces, 4 pieces, etc.).

Every time a player equips or unequips armor, the plugin:

1. Counts how many pieces of each set the player has equipped
2. Compares the new count to the previous count
3. If the count crossed a threshold upward → applies effects, runs commands, sends activation message
4. If the count crossed a threshold downward → removes effects, sends deactivation message

Config Keys

Potion Effect Map Keys

Full Example

sets:
  dragon:
    pieces:
      - dragon_helmet
      - dragon_chestplate
      - dragon_leggings
      - dragon_boots

    bonuses:
      "2":                                         # Wearing 2 out of 4 pieces
        message: "&c&l★ 2-Piece Dragon: &fStrength I active!"
        potion_effects:
          - effect: strength
            duration: 999999                       # Permanent while worn
            amplifier: 0                           # Strength I

      "4":                                         # Full set bonus
        message: "&4&l★ Full Dragon Set! &cFire Resistance + Strength II!"
        potion_effects:
          - effect: fire_resistance
            duration: 999999
            amplifier: 0
          - effect: strength
            duration: 999999
            amplifier: 1                           # Strength II (overrides 2-piece Strength I)
        commands:
          - "broadcast &4{player} &chas assembled the full Dragon Set!"

Custom Crops

Persistent, multi-stage crops with generated or custom models, configurable growth conditions, dynamic hitboxes, stage effects, age-aware loot tables, edible harvest items, and plugin events.

What the Crop System Does

1. Scans every folder inside plugins/CustomiZer/packs/ for a Models/ or Textures/ crop layout.
2. Detects each crop's stages from correctly named model or texture files.
3. Assigns stable CustomModelData values for the seed and every stage. The assignments are saved and reused after restarts.
4. Creates a plantable seed item tagged with the crop ID.
5. Displays the planted crop with a packet-based ItemDisplay and uses an invisible Interaction entity as its clickable hitbox.
6. Checks growth every 30 seconds, changes the model and hitbox as the age increases, and saves placed crops across restarts.
7. Rolls an age-aware loot table when the crop is right-clicked or broken.

Crop Lifecycle In Game

The following screenshots show the complete visible lifecycle: planting a seed, growing through the configured models, reaching the final stage, and breaking a mature tomato crop to receive its configured tomato drop.

1. Planting the Seed (Age 0)

Right-click the configured placement.bottom_block with the crop's tagged seed. The seed is consumed in Survival mode and the first crop model appears in the empty block above.

2. Growing Through the Stages

As growth checks succeed, each crop advances one age at a time. Its model and clickable hitbox update to match the new stage. This example field shows several custom crops at different growth stages.

3. Final Stage (Ready to Harvest)

When a crop reaches its highest detected age, it uses the final stage model. If ready_effect is configured, particles mark the crop as mature and continue appearing every growth check while it remains ready.

Tomato Drop Example

In this example, the highlighted mature tomato plant matches a loot entry configured with item: "pack:my_farm_pack:tomato" and a final-stage age condition.

Before Breaking

The mature tomato crop is still planted and displaying its final model.

After Breaking

The crop is removed and the configured custom tomato item drops naturally at its location.

Creating a Crop Pack

Create one pack folder and choose one of the two supported visual layouts. If a pack contains a Models/ directory, the scanner prefers it and does not scan that pack's Textures/ directory for crops.

Option A: PNG Textures (Automatic Models)

plugins/CustomiZer/packs/my_farm_pack/
├── Textures/
│   └── tomato/
│       ├── tomato_crop_stage0.png
│       ├── tomato_crop_stage1.png
│       └── tomato_crop_stage2.png
└── configs/
    └── tomato.yml

The exact texture pattern is <crop-id>_crop_stage<age>.png. CustomiZer generates:

• A flat seed item model using the stage 0 texture.
• A crossed-plane crop model for every detected stage.
• Resource-pack textures under assets/customizer/textures/crop/<crop-id>_<age>.png.

Option B: Pre-Built JSON Models

plugins/CustomiZer/packs/my_farm_pack/
├── Models/
│   └── tomato/
│       ├── tomato_seed.json
│       ├── tomato_crop_stage_0.json
│       ├── tomato_crop_stage_1.json
│       └── tomato_crop_stage_2.json
├── configs/
│   └── tomato.yml
└── resourcepack/
    └── assets/
        └── my_farm_pack/
            ├── models/
            └── textures/

The exact stage model pattern is <crop-id>_crop_stage_<age>.json. The seed model is <crop-id>_seed.json. Missing seed or stage models fall back to generated models. Model JSON may reference namespaced textures and parent models; place those assets in the pack's normal resourcepack/assets/ structure.

Pack Items for Harvests and Seeds

If loot should drop a textured pack item, define that item in a normal pack item config. The item ID used by the crop must match the ID under items:.

# plugins/CustomiZer/packs/my_farm_pack/configs/farm_items.yml
info:
  namespace: my_farm_pack

items:
  tomato:
    display_name: "Tomato"
    resource:
      generate: false
      material: APPLE
      model_path: custom/items/tomato

  tomato_seed:
    display_name: "Tomato Seed"
    resource:
      generate: false
      material: WHEAT_SEEDS
      model_path: custom/items/tomato_seed

Complete Crop Configuration

# plugins/CustomiZer/packs/my_farm_pack/configs/tomato.yml
seed:
  id: tomato_seed                    # Logical seed ID; default: tomato_seed
  material: WHEAT_SEEDS              # Vanilla base material of the generated seed

growth:
  max_age: 2                         # Informational in the current loader; files determine max age
  avg_seconds_per_stage: 120         # Average target time for each stage
  min_light: 7                       # Growth pauses below this block light level

placement:
  bottom_block: FARMLAND             # Exact Bukkit material that must be clicked

hitbox:
  auto_height_step: 0.1              # Default height = max(0.2, step * (age + 1))

# Optional exact hitboxes override the automatic size for listed ages
hitboxes:
  "0":
    width: 0.75
    height: 0.25
  "2":
    width: 0.9
    height: 0.8

sounds:
  place: minecraft:item.crop.plant   # Successful planting
  break: minecraft:block.crop.break  # Left-click or environmental break
  interact: minecraft:block.crop.hit # Right-click harvest
  grow: minecraft:block.grass.place  # Optional; every successful age increase

loot:
  drop_seed_if_immature: true        # Currently stored but not used by loot rolling
  decrease_age_on_harvest: -1        # -1 removes crop; 0 keeps same age; N subtracts N ages

multipliers:
  bonemeal: 0.3                      # Present in config, but currently not used by interaction code
  max_moisture: 0.2                  # +20% in swamp, jungle, or forest biome names
  rain: 0.1                          # +10% while storming without thunder
  thunderstorm: -0.3                 # -30% while thundering
  snow: -0.5                         # -50% in snow, frozen, or ice biome names

ready_effect:
  particle: HAPPY_VILLAGER           # Bukkit Particle enum name; omit for no ready particles
  count: 6                           # Ambient count; maturity burst uses count * 3

stage_effects:
  "1":
    particle: COMPOSTER               # Bukkit Particle enum name
    particle_count: 4                 # Default: 5
    sound: minecraft:block.grass.place
  "2":
    particle: CRIMSON_SPORE
    particle_count: 10
    sound: minecraft:entity.experience_orb.pickup

item_drops:
  ripe_tomato:
    item: "pack:my_farm_pack:tomato"
    min_amount: 1
    max_amount: 3
    chance: 1.0
    trigger_min_age: 2
    trigger_max_age: -1
    food:
      nutrition: 3
      saturation: 0.5
      can_always_eat: true
      effects:
        - effect: HASTE
          duration: 120
          amplifier: 0
          chance: 0.3

  immature_seed_return:
    item: "crop_seed"
    min_amount: 1
    max_amount: 1
    chance: 1.0
    trigger_min_age: 0
    trigger_max_age: 1

Configuration Reference

Exact Growth Calculation

Growth is checked once every 600 ticks (30 seconds). A crop can advance by at most one age per check. Crops already at maximum age are skipped.

base chance = 30 / avg_seconds_per_stage
final chance = base chance + (base chance × each active multiplier)
final chance is clamped between 0.0 and 1.0

Example: with avg_seconds_per_stage: 120, the base roll is 30 / 120 = 0.25, or 25% every 30 seconds. During ordinary rain with rain: 0.1, it becomes 0.25 + 0.025 = 0.275, or 27.5%.

• rain applies when the world has a storm and is not thundering.
• thunderstorm applies instead of rain while the world is thundering.
• max_moisture currently checks whether the biome name contains swamp, jungle, or forest; it does not inspect farmland moisture.
• snow applies when the biome name contains snow, frozen, or ice.
• bonemeal is not currently read by planting or interaction code, so bone meal does not force or accelerate a crop.

Planting, Harvesting, and Breaking

When WorldGuard integration is available, planting is denied where the player cannot build. Crop place, grow, harvest, break, and remove lifecycle events are also exposed to other plugins; cancellable events can stop the corresponding action, and the grow event can change the target age.

Drop Table Reference

Every child under item_drops: is an independent roll. Multiple entries can match and drop together.

Supported Item References

Recommended Mature and Immature Drops

item_drops:
  mature_produce:
    item: "pack:my_farm_pack:tomato"
    min_amount: 1
    max_amount: 3
    chance: 1.0
    trigger_min_age: 2
    trigger_max_age: -1

  mature_seed:
    item: "crop_seed"
    min_amount: 1
    max_amount: 2
    chance: 0.7
    trigger_min_age: 2
    trigger_max_age: -1

  immature_seed:
    item: "crop_seed"
    min_amount: 1
    max_amount: 1
    chance: 1.0
    trigger_min_age: 0
    trigger_max_age: 1

Edible Crop Drops

Add food: to any loot entry to apply a Paper food component to that generated drop.

# plugins/CustomiZer/config.yml
crops:
  can_always_eat: false

Persistence and Reloading

• Placed crop type, location, current age, timestamps, and planter UUID are persisted.
• Crop visuals and hitboxes are recreated after restart and when their chunk loads.
• CustomModelData allocations are stored in a registry so adding crops does not renumber existing crops.
• /zcrop reload rescans crop definitions and refreshes displays. Rebuild or resend the resource pack when adding or changing textures/models.

Crop Commands

Creation Checklist

1. Choose a lowercase crop ID such as tomato.
2. Create either continuous PNG stages in Textures/tomato/ or JSON stages in Models/tomato/.
3. Create configs/tomato.yml. If omitted, CustomiZer generates a basic config after detecting the visual files.
4. Define harvest and seed pack items if you want custom inventory textures.
5. Use explicit age ranges for every mature and immature drop.
6. Run /zcrop reload, then /zcrop list to confirm registration.
7. Use /zcrop give <player> tomato, plant it, and test stages with /zcrop setage <age>.
8. Rebuild/distribute the resource pack whenever visual assets change.

GUI System

CustomiZer has two in-game menus. They look similar but show completely different things. Read this page first — it will save you hours of confusion.

The One-Sentence Explanation

The Most Important Thing to Understand

/z gui and /zitems now read from two separate files per pack:

packs/<packId>/gui.yml    ← raw visual items shown in /z gui (type: pack_item, raw)
items/<packId>/gui.yml   ← functional items shown in /zitems (type: sword, pickaxe, armor, etc.)

The slot: at the top of each pack's yml controls where the category icon appears in the menu. There is no longer a pack_overrides section for slot assignments.

The item's type: field determines what kind of item it is:

Side-by-Side Comparison

Inventory Slot Reference

Both GUIs use standard Minecraft slot numbering — left to right, top to bottom, starting at 0. A 6-row inventory has 54 slots (0–53):

Row 1:  [ 0][ 1][ 2][ 3][ 4][ 5][ 6][ 7][ 8]
Row 2:  [ 9][10][11][12][13][14][15][16][17]
Row 3:  [18][19][20][21][22][23][24][25][26]
Row 4:  [27][28][29][30][31][32][33][34][35]
Row 5:  [36][37][38][39][40][41][42][43][44]
Row 6:  [45][46][47][48][49][50][51][52][53]  ← nav buttons row

/z gui — Pack Browser

The player-facing menu. Shows raw resource pack items (custom textures and models) so players can see what's available on the server. Browse only — no items are given.

How It Works

When a player runs /z gui, they see one icon per registered pack. Clicking a pack icon opens a second page listing all items of type pack_item or raw from that pack's packs/<packId>/gui.yml. A "Browse All Items" button also lets players see all raw items from all packs on one paginated page.

Config 1 — Shell layout: plugins/CustomiZer/gui/main_menu.yml

Controls the outer frame of the /z gui category browser: title, size, background filler, border, and the "Browse All Items" button. The Prev/Back/Next navigation buttons when browsing items inside a pack are also configured here.

# plugins/CustomiZer/gui/main_menu.yml

categories:
  title: "<white><shift:-8><font_image:CustomiZerInternal:1>"
  size: 6
  background:
    enabled: true
    material: PAPER
    model_data: 29999
    name: " "
  border:
    enabled: true
    material: PAPER
    model_data: 29999
    name: " "

pack_gui:
  prev_button:
    slot: 47
    material: PAPER
    model_data: 29999
    name: "&c◀ Previous"
  back_button:
    slot: 49
    material: PAPER
    model_data: 29999
    name: "&c✖ Back"
  next_button:
    slot: 51
    material: PAPER
    model_data: 29999
    name: "&aNext ▶"
  page_info:
    enabled: true
    slot: 48
    material: PAPER
    model_data: 29999
    name: "&7Page &f%page% &7/ &f%total%"

The "Browse All Items" button (new) opens a paginated browser showing ALL raw items from ALL packs. It is configured in plugins/CustomiZer/gui/all_items.yml.

Config 2 — Pack display items: packs/<packId>/gui.yml

This is the file you create to make a pack appear in /z gui. It contains the raw visual items (type: pack_item or type: raw) displayed in the browser. The plugin automatically scans for these files. No other registration needed.

For /zitems, create a separate file at items/<packId>/gui.yml with functional item types (sword, pickaxe, armor, etc.).

Changing a pack's slot in /z gui

Edit the slot: at the top of the pack's packs/<packId>/gui.yml. That number controls where the pack's icon sits in the /z gui category grid. If no packs/ file exists for a pack, the slot is read from items/<packId>/gui.yml instead.

# packs/my_gem_pack/gui.yml  ← display browser for /z gui

name: "<gradient:#ffd700:#ff9a3c><bold>Gem Pack</bold></gradient>"
slot: 11    # ← Change this to move the icon in /z gui

icon:
  pack: my_gem_pack   # pack namespace
  id: ruby            # item id used as the icon

gui:
  size: 6

# Only pack_item / raw types appear in /z gui
items:
  - type: pack_item
    pack: my_gem_pack
    id: ruby
    name: "&cRuby"
    lore:
      - "&7A precious red gem"

  - type: pack_item
    pack: my_gem_pack
    id: emerald_gem
    name: "&aEmerald Gem"
    lore:
      - "&7A brilliant green gem"

Adding a Pack to /z gui (summary)

1. Create packs/my_pack/gui.yml with a free slot: and pack_item entries
2. Run /zpack reloadpacks in-game

That's it. No other file needs to be touched for the pack to appear in /z gui.

/zitems — Functional Items Browser

The admin tool for browsing and giving functional items — swords with levelling, pickaxes, cosmetics, harvesters, and more. Left-click any item to receive it instantly.

The /zitems main menu — each icon is a registered pack. Click a pack to browse its functional items.

Config 1 — Nav buttons: plugins/CustomiZer/gui/items_shop.yml

This file controls the Prev / Back / Next navigation buttons and page info shown when browsing items inside a category. It does not control which packs appear as categories — that comes from each pack's items/<packId>/gui.yml.

# plugins/CustomiZer/gui/items_shop.yml

pack_gui:
  prev_button:
    slot: 47
    material: PAPER
    model_data: 29999
    name: "&c◀ Previous"
  back_button:
    slot: 49
    material: PAPER
    model_data: 29999
    name: "&c✖ Back"
  next_button:
    slot: 51
    material: PAPER
    model_data: 29999
    name: "&aNext ▶"
  page_info:
    enabled: true
    slot: 48
    material: PAPER
    model_data: 29999
    name: "&7Page &f%page% &7/ &f%total%"

Config 2 — Pack functional items: items/<packId>/gui.yml

This is the file that registers functional items in /zitems. It is a separate file from the packs/<packId>/gui.yml used by /z gui. You need both files if you want a pack to appear in both menus.

Changing a category's slot in /zitems

Edit slot: at the top of items/<packId>/gui.yml. This controls the pack icon position in /zitems. The equivalent packs/<packId>/gui.yml controls the slot in /z gui independently.

Controlling item placement inside a category

Each item entry in items/<packId>/gui.yml supports an optional slot: field that pins it to a specific position:

# items/my_pack/gui.yml  ← functional items for /zitems

name: "<gradient:#5cc8ff:#7ee787><bold>My Pack</bold></gradient>"
slot: 11
icon:
  pack: my_pack
  id: silver_sword
gui:
  size: 6

items:
  # Functional items → appear in /zitems (clicking gives the fully configured item)
  - type: sword
    id: silver_sword
    slot: 11          # ← pin to exact slot inside the /zitems category page
    name: "&7⚔ Silver Sword"
    lore:
      - "&7A levelling sword"
      - "&aLeft-click to receive"

  - type: pickaxe
    id: silver_pickaxe
    slot: 12          # ← pin to slot 12
    name: "&7⛏ Silver Pickaxe"
    lore:
      - "&7Radius mining pickaxe"

  - type: harvester
    id: silver_hoe
    # no slot: → placed automatically after the pinned items

For the display browser (/z gui), create a separate packs/my_pack/gui.yml with type: pack_item entries for the same items.

Item Types Reference

Converting ItemsAdder Packs Automatically

If you have ItemsAdder content packs you want to move to CustomiZer, the built-in converter handles it automatically — it creates the gui.yml, copies assets, and classifies items.

1. Drop the ItemsAdder content folder (must contain configs/ and resourcepack/) into:
   plugins/CustomiZer/converters/itemsadder/input/<packName>/
2. Run in-game: /zpack convert itemsadder <packName>
3. Run /zpack zip to rebuild the resource pack

Pack GUI — gui.yml Reference

Two separate files per pack: one for the /z gui display browser, one for the /zitems admin give tool. Each file controls which slot the pack occupies, what icon it shows, and which items appear inside it.

Where the files live

packs/<packId>/gui.yml    ← display browser for /z gui (type: pack_item, raw)
items/<packId>/gui.yml   ← admin give tool for /zitems (type: sword, pickaxe, armor, etc.)

The plugin automatically detects these files. No other registration is needed — just create the file and reload. The slot: at the top of each file controls where the category icon appears. If only one file exists for a pack, its slot: is used for both menus.

packs/<packId>/gui.yml — display browser (/z gui)

# packs/my_pack/gui.yml  ← raw visual items shown in /z gui

# Display name shown as the pack's label in /z gui.
name: "<gradient:#5cc8ff:#7ee787><bold>My Pack</bold></gradient>"

# Slot in the /z gui category grid.
# Use slots 11–15, 20–24, 29–33, or 38–42 for best results.
slot: 11

# The icon shown for this pack in the /z gui category grid.
icon:
  pack: my_pack     # pack namespace
  id: silver_ore    # item id within that pack

# The title and size of the pack's browsing page.
gui:
  title: "<white><shift:-8><font_image:CustomiZerInternal:1>"
  size: 6   # rows (1–6); last row = nav buttons if size > 1

# Only pack_item / raw types belong here
items:

  # Raw visual item — shows in /z gui (clicking gives the raw item)
  - type: pack_item
    pack: my_pack
    id: silver_ore
    name: "&7Silver Ore"
    lore:
      - "&7A raw ore texture"
    # slot: 0    ← optional: pin to exact position

items/<packId>/gui.yml — admin give tool (/zitems)

# items/my_pack/gui.yml  ← functional items shown in /zitems

name: "<gradient:#5cc8ff:#7ee787><bold>My Pack</bold></gradient>"
slot: 11

icon:
  pack: my_pack
  id: silver_ore

gui:
  size: 6

# Functional item types belong here
items:

  # Functional sword — shows in /zitems
  - type: sword
    id: silver_sword
    slot: 11      # optional: pin to slot 11 in the /zitems category page
    name: "&7⚔ Silver Sword"
    lore:
      - "&7A levelling sword"
      - "&aLeft-click to receive"

  # Functional pickaxe — shows in /zitems
  - type: pickaxe
    id: silver_pickaxe
    slot: 12
    name: "&7⛏ Silver Pickaxe"

  # Functional harvester hoe — shows in /zitems
  - type: harvester
    id: silver_hoe
    name: "&7🌾 Silver Hoe"

  # Functional cosmetic hat — shows in /zitems
  - type: cosmetic
    id: silver_crown
    name: "&7👑 Silver Crown"

Common Mistakes & Fixes

Mastery System

Persistent XP tracks that reward players for mining, combat, farming, and exploration with milestone rewards.

What Is Mastery?

Mastery tracks give players a long-term progression goal separate from levelling. Breaking ore gives Mining Mastery XP. Killing mobs gives Combat Mastery XP. Reaching milestones (level 10, 25, 50, 100) triggers reward commands and messages.

max_level: 100     # Maximum mastery level for all tracks

tracks:
  mining:
    display: "⛏ Mining Mastery"

    # XP earned per block broken
    xp_per_block:
      COAL_ORE: 3
      IRON_ORE: 5
      GOLD_ORE: 7
      DIAMOND_ORE: 15
      ANCIENT_DEBRIS: 40
      DEEPSLATE_COAL_ORE: 4
      my_pack:ruby_ore: 12       # Custom pack blocks use namespace:key

    xp_per_level: 1000           # XP needed per level (same for all levels)

    milestones:
      10:
        message: "⛏ Mining Mastery 10 reached!"
        commands:
          - "give {player} diamond 5"
      25:
        message: "⛏ Mining Mastery 25! You're a real miner."
      50:
        message: "⛏ Mining Mastery 50!"
        commands:
          - "cxp give {player} item prestige_token 1"
      100:
        message: "⛏ MINING MASTER! Maximum level achieved!"
        commands:
          - "cxp give {player} item elite_pickaxe 1"

  combat:
    display: "⚔ Combat Mastery"
    xp_per_kill:
      ZOMBIE: 3
      SKELETON: 4
      SPIDER: 3
      CREEPER: 6
      ENDER_DRAGON: 200
      WITHER: 100
    xp_per_level: 1500

  farming:
    display: "🌿 Farming Mastery"
    xp_per_harvest:
      WHEAT: 2
      CARROTS: 2
      POTATOES: 2
      PUMPKIN: 5
    xp_per_level: 800

Commands

Missions

Daily and weekly objectives that reset on a schedule and reward players with money and items.

daily_reset_hour: 0       # Hour of day to reset daily missions (0 = midnight)
weekly_reset_day: MONDAY  # Day of week to reset weekly missions

daily:
  mine_iron:
    display: "⛏ Iron Miner"
    description: "Mine 30 Iron Ore"
    objective: MINE_BLOCK   # Objective type (see table below)
    target: IRON_ORE        # What to mine/kill/harvest
    amount: 30              # How many needed to complete
    rewards:
      money: 200
      commands:
        - "cxp give {player} item mission_token 2"
      message: "Daily Complete: Iron Miner! +$200"

  kill_zombies:
    display: "⚔ Zombie Slayer"
    description: "Kill 25 Zombies"
    objective: KILL_MOB
    target: ZOMBIE
    amount: 25
    rewards:
      money: 150

weekly:
  nether_run:
    display: "🔥 Nether Runner"
    description: "Mine 5 Ancient Debris this week"
    objective: MINE_BLOCK
    target: ANCIENT_DEBRIS
    amount: 5
    rewards:
      money: 2000
      commands:
        - "cxp give {player} item mission_token 10"

Objective Types

Prestige

Max out your mastery tracks to prestige — earning permanent reward multiplier bonuses that stack.

max_prestige: 10

# Which mastery tracks must be at max level to prestige
mastery_tracks_required:
  - mining
  - combat

mastery_level_required: 100    # All listed tracks must reach this level

levels:
  1:
    display: "✦ Prestige I"
    permanent_bonus_percent: 2    # +2% to all XP and rewards, permanently
    rewards:
      money: 5000
      commands:
        - "cxp give {player} item prestige_token 2"
      message: "★ Prestige I achieved! +2% permanent bonus!"

  2:
    display: "✦ Prestige II"
    permanent_bonus_percent: 4
    rewards:
      money: 8000

  10:
    display: "✦ ASCENDANT"
    permanent_bonus_percent: 20
    rewards:
      money: 100000
      commands:
        - "cxp give {player} sword celestial_blade"

Reforge

Re-roll stat modifiers on weapons and armor using reforge stones.

reforge_cost_item: "reforge_stone"    # CustomiZer item key consumed each reforge
reforge_cost_amount: 3               # How many stones consumed
reforge_cost_money: 250.0            # Money cost (in addition to items)
use_money_cost: true

modifiers:
  savage:
    display: "Savage"
    stats:
      GENERIC_ATTACK_DAMAGE: 2.0
      GENERIC_ATTACK_SPEED: 0.1
    lore_line: "✦ Savage: +2 ATK, +0.1 SPD"
    weight: 20       # Higher weight = more commonly rolled

  ancient:
    display: "Ancient"
    stats:
      GENERIC_MAX_HEALTH: 4.0
      GENERIC_ARMOR: 1.0
    lore_line: "✦ Ancient: +4 HP, +1 Armor"
    weight: 15

  celestial:
    display: "Celestial"
    stats:
      GENERIC_ATTACK_DAMAGE: 4.0
      GENERIC_MAX_HEALTH: 6.0
      GENERIC_ARMOR: 2.0
    weight: 2         # Rare modifier

  void:
    display: "Void"
    stats:
      GENERIC_ATTACK_DAMAGE: 6.0
      GENERIC_ATTACK_SPEED: 0.3
    weight: 1         # Very rare modifier

Repair

Restore custom durability on swords and tools with rank-based discounts and cooldowns.

repair-rate-per-10%: 1000          # Base cost (money) to restore 10% durability

# Cost per 10% durability for swords, per rarity tier
swords-repair-rate-per-10%:
  common: 1000
  rare:   2000
  epic:   3000
  legendary: 4000
  mythic: 5000

# Different cooldowns and discounts per player rank
# Rank is determined by LuckPerms group name
general-cooldown-per-rank:
  Default:
    Cooldown: 10000    # Milliseconds between repairs (10000 = 10 seconds)
    Discount: 0        # Percent discount on cost
  VIP:
    Cooldown: 5000
    Discount: 10
  MVP:
    Cooldown: 3000
    Discount: 15
  ELITE:
    Cooldown: 2000
    Discount: 20

messages:
  no-money: "&cNot enough money."
  repaired-successfully: "&aRepaired {count} items for &6${cost}&a."
  no-items-to-repair: "&eNo items need repairs."
  cooldown-message: "&cWait {time} seconds before repairing again."

This page has moved. Click here for the Levelling System page.

The Levelling System

CustomiZer supports kill-based levelling for swords and axes, and block-based levelling for pickaxes. Both are optional add-ons to normal weapons and tools.

Overview — Two Types of Levelling

Sword & Axe Rarity (Kill-Based)

Swords and axes can have a rarity: block in their config. The plugin tracks kills in item NBT data. When the kill count hits the configured threshold, the weapon upgrades to the next tier automatically — no commands needed.

Common → Rare → Epic → Legendary → Mythical

What happens when a sword/axe upgrades:

• The Custom Model Data changes to the next tier's value → Minecraft loads a different texture from the resource pack
• The item's display name changes to the tier's name
• A Buff% multiplier is applied to all attributes (so a Legendary sword is stronger than a Common one)
• The player receives an upgrade notification

Step 1 — Define a texture per tier in your pack

Each rarity tier needs its own pack item entry with a unique model_id pointing to a different texture file:

# packs/my_pack/configs/items.yml
items:
  dragon_blade_common:
    resource:
      generate: true
      material: IRON_SWORD
      model_id: 32001           # CMD for Common tier
      textures: [weapons/dragon_blade_common.png]

  dragon_blade_rare:
    resource:
      generate: true
      material: IRON_SWORD
      model_id: 32002           # CMD for Rare tier — different PNG!
      textures: [weapons/dragon_blade_rare.png]

  dragon_blade_epic:
    resource:
      generate: true
      material: IRON_SWORD
      model_id: 32003
      textures: [weapons/dragon_blade_epic.png]

  dragon_blade_legendary:
    resource:
      generate: true
      material: IRON_SWORD
      model_id: 32004
      textures: [weapons/dragon_blade_legendary.png]

  dragon_blade_mythical:
    resource:
      generate: true
      material: IRON_SWORD
      model_id: 32005
      textures: [weapons/dragon_blade_mythical.png]

Step 2 — Add the rarity block to your sword

Point each rarity tier to the correct CMD:

# CustomiZe!/__global__/swords.yml
swords:
  dragon_blade:
    type: IRON_SWORD
    display_name: "&4Dragon Blade"
    durability: 5000
    attributes:
      GENERIC_ATTACK_DAMAGE: 10.0

    lore:
      - "&8Rarity: %rarity%"
      - "&8Kills: %progress% / %required%"

    # The rarity block — remove this entirely if you don't want levelling
    rarity:
      common:
        custom_model_data: 32001    # Matches dragon_blade_common model_id
        name: "&7Common Dragon Blade"
      rare:
        custom_model_data: 32002
        name: "&9Rare Dragon Blade"
      epic:
        custom_model_data: 32003
        name: "&5Epic Dragon Blade"
      legendary:
        custom_model_data: 32004
        name: "&6Legendary Dragon Blade"
      mythical:
        custom_model_data: 32005
        name: "&dMythical Dragon Blade"

Step 3 — Configure rarity.yml

plugins/CustomiZer/rarity.yml is the global rarity chain. Every sword and axe on the server shares this file — it defines the tier names, kill thresholds, and stat buffs. Your per-sword rarity: block in swords.yml only controls the CMD (texture) and display name per tier; the actual upgrade logic lives here.

rarity.yml — All Config Keys

How the Buff Works Exactly

When a sword upgrades to a new tier, the plugin reads all attribute values from the sword's attributes: config block and reapplies them with the tier's Buff multiplier:

# Sword config:
attributes:
  GENERIC_ATTACK_DAMAGE: 10.0
  GENERIC_ATTACK_SPEED: 1.6

# At Rare (Buff: 10):
#   attack_damage = 10.0 × (1 + 10/100) = 11.0
#   attack_speed  = 1.6  × (1 + 10/100) = 1.76

# At Epic (Buff: 20):
#   attack_damage = 10.0 × (1 + 20/100) = 12.0
#   attack_speed  = 1.6  × (1 + 20/100) = 1.92

# At Legendary (Buff: 30):
#   attack_damage = 10.0 × 1.30 = 13.0

# At Mythic (Buff: 40):
#   attack_damage = 10.0 × 1.40 = 14.0

How the Kill Counter Works

• The counter tracks kills per tier. After an upgrade it resets to 0.
• A separate total kills counter tracks all-time kills with the weapon and is never reset — this is what %total_kills% shows in lore.
• At the final tier (NextRarity: null), the evolution counter is frozen. Total kills continue to increment.
• The upgrade fires the instant a kill pushes the counter to or past EvolutionKillsRequired.

You Can Create Completely Custom Tier Chains

The rarity system is not limited to the five default tiers. You can create any number of tiers with any names. The YAML key is the tier's internal ID — it must match what you write in NextRarity and in your sword's rarity: block.

Example — 3-tier custom chain

# rarity.yml — a totally custom 3-tier chain
rarities:
  bronze:
    Name: "&6Bronze"
    Buff: 0
    EvolutionKillsRequired: 25
    NextRarity: "silver"

  silver:
    Name: "&fSilver"
    Buff: 15
    EvolutionKillsRequired: 75
    NextRarity: "gold"

  gold:
    Name: "&e&lGold"
    Buff: 35
    EvolutionKillsRequired: 0    # Irrelevant — NextRarity is null
    NextRarity: null              # Max tier

Then in your sword's config, your rarity: block uses those same IDs:

rarity:
  bronze:
    custom_model_data: 50001
    name: "&6Bronze Blade"
  silver:
    custom_model_data: 50002
    name: "&fSilver Blade"
  gold:
    custom_model_data: 50003
    name: "&e&lGolden Blade"

Example — 7-tier progression for a long-term server

rarities:
  novice:
    Name: "&7Novice"
    Buff: 0
    EvolutionKillsRequired: 50
    NextRarity: "apprentice"

  apprentice:
    Name: "&aApprentice"
    Buff: 8
    EvolutionKillsRequired: 150
    NextRarity: "adept"

  adept:
    Name: "&2Adept"
    Buff: 16
    EvolutionKillsRequired: 300
    NextRarity: "expert"

  expert:
    Name: "&bExpert"
    Buff: 25
    EvolutionKillsRequired: 500
    NextRarity: "master"

  master:
    Name: "&9Master"
    Buff: 35
    EvolutionKillsRequired: 750
    NextRarity: "grandmaster"

  grandmaster:
    Name: "&5Grandmaster"
    Buff: 45
    EvolutionKillsRequired: 1000
    NextRarity: "legend"

  legend:
    Name: "&6&lLEGEND"
    Buff: 60
    EvolutionKillsRequired: 0
    NextRarity: null

Important — rarity.yml vs swords.yml rarity block

The tier IDs (e.g. common, rare, bronze) must be identical in both files — the name in rarity.yml's rarities: map must match the name in the sword's rarity: block.

Sword Lore Placeholders (with rarity)

Pickaxe Levelling (Block-Based)

Pickaxes use a completely self-contained levelling system defined inside pickaxes.yml — there is no separate rarity.yml involved. Each pickaxe definition contains a levels: map. The plugin counts blocks mined and upgrades when the threshold is met.

What happens when a pickaxe levels up:

• Custom Model Data changes → new texture
• Mining radius expands (e.g. 1×1 → 3×3 → 3×7)
• Haste level can increase per tier
• Custom durability increases
• The player is notified

# CustomiZe!/__global__/pickaxes.yml
pickaxes:
  tier_pickaxe:
    type: DIAMOND_PICKAXE
    display_name: "⛏ Tier Pickaxe"
    lore:
      - "Level: %level% / %max_level%"
      - "Blocks mined: %blocks_mined% / %blocks_required%"
      - "Mining area: %radius%×%radius%"
      - "%bonuses%"

    levels:
      1:
        name: "⛏ Tier Pickaxe [Lvl. 1]"
        custom_model_data: 30041        # Texture for level 1
        durability: 2000
        radius: 1                       # Mines 1×1 (just the single block)
        height_radius: 0
        effect_on_hold: haste
        effect_amplifier: 0             # Haste I
        blocks_required: 200            # Mine 200 blocks → level 2
        bonus:
          - "• Haste I while held"

      2:
        name: "⛏ Tier Pickaxe [Lvl. 2]"
        custom_model_data: 30042        # Different texture
        durability: 4000
        radius: 1
        height_radius: 1               # Now mines 1×3 tall
        effect_on_hold: haste
        effect_amplifier: 0
        blocks_required: 500
        bonus:
          - "• Haste I"
          - "• 1×3 column mining"

      3:
        name: "⛏ Tier Pickaxe [Lvl. 3]"
        custom_model_data: 30043
        durability: 7000
        radius: 3                       # 3×3 area!
        height_radius: 1
        effect_on_hold: haste
        effect_amplifier: 1             # Haste II
        blocks_required: 1000
        bonus:
          - "• Haste II"
          - "• 3×3 area mining"

      4:
        name: "⛏ Tier Pickaxe [MAX]"
        custom_model_data: 30044
        durability: 12000
        radius: 3
        height_radius: 3               # 3×7 area
        effect_on_hold: haste
        effect_amplifier: 1
        blocks_required: 0             # 0 = this is the max level
        bonus:
          - "• Haste II"
          - "• 3×7 area mining"
          - "• MAX LEVEL"

Pickaxe Lore Placeholders

Ore Generators

Automatically inject custom blocks into world generation — no external world editor needed.

What This Does

When a chunk is loaded for the first time (or generated fresh), CustomiZer places your custom ores into it — just like how Minecraft naturally generates diamond ore veins. Players mine them just like vanilla ores.

Configuration

worlds_populators:
  # A unique key for this generator entry
  ruby_ore_overworld:
    block: my_pack:ruby_ore      # The block to place ("namespace:key" or "minecraft:stone")
    worlds:
      - world                     # Overworld
      - world_caves               # Cave world if you have one
    replaceable_blocks:           # Only replaces these blocks when placing
      - STONE
      - ANDESITE
      - GRANITE
      - TUFF
    biomes:                       # Empty list = spawn in ALL biomes
      - PLAINS
      - FOREST
      - JUNGLE
      - MOUNTAINS
    chance: 60.0                  # Percent chance of spawning a vein per chunk (0–100)
    amount: 5                     # Number of ore veins per chunk
    min_height: 15                # Minimum Y level to spawn at
    max_height: 55                # Maximum Y level to spawn at

  deepslate_ruby_ore:
    block: my_pack:deepslate_ruby_ore
    worlds:
      - world
    replaceable_blocks:
      - DEEPSLATE
      - COBBLED_DEEPSLATE
    biomes: []                    # Empty = any biome
    chance: 35.0
    amount: 3
    min_height: -60
    max_height: 0                 # Only in deepslate level

Tips

• Already-generated chunks are NOT retroactively populated. New ore configs only affect chunks generated after the config was applied.
• To force-populate existing chunks use /zworld generate <world> (admin command).
• Use a low chance and small amount for rare ores. A chance of 100 with amount 10 would make them very common.
• The replaceable_blocks list prevents ores from floating in air or water — always include the natural blocks for that layer.

Commands

Custom Crafting Tables

Custom workbench blocks or furniture with configurable slot layouts, permissions, and recipe storage. Create and delete tables entirely in-game — no config editing required.

custom_crafting_tables:
  enabled: true

  storage:
    type: "sqlite"             # "sqlite" (file-based) or "mongodb"
    sqlite:
      file: "custom_crafting_recipes.db"
      table: "custom_crafting_recipes"

  default_table: "basic_workbench"

  tables:
    basic_workbench:
      enabled: true
      display_name: "&aBasic Workbench"

      # Open this GUI when a player right-clicks this custom block
      assigned_block: "my_pack:workbench_block"
      # OR open when a player right-clicks this placed furniture (can use both at once)
      assigned_furniture: "my_pack:workbench_item"

      permission:
        required: false
        node: "customizer.craftingtable.basic_workbench"

      gui:
        title: "&8⚒ Basic Workbench"
        rows: 5
        # Slots where players put input items
        input_slots: [10, 11, 12, 19, 20, 21, 28, 29, 30]
        # Slots where the output appears
        output_slots: [24]

      behavior:
        return_items_on_close: true   # Return inputs if GUI is closed without crafting
        consume_inputs: true          # Remove input items when crafting
        allow_partial_outputs: false

Table management

Adding recipes to a table

Each table has its own independent recipe list. Recipes are added per-table using the table's ID — the same ID you set in the wizard or in the config.

1. Run /zcraft create <tableId> <recipeName> — e.g. /zcraft create my_forge iron_to_steel.
   This opens the recipe designer pre-loaded with that table's exact slot layout.
2. Place ingredients in the blue input slots in the arrangement you want.
3. Place the result item in the red output slot.
4. Optionally toggle Shaped / Shapeless mode or add a permission node using the control buttons in the bottom row.
5. Close the GUI — the recipe saves automatically and is live immediately. No reload needed.

To edit an existing recipe, run the same /zcraft create <tableId> <recipeName> command again — it loads the current ingredients so you can change them.

Recipe commands

→ Full documentation: Custom Crafting module page

Commands

Every command available in CustomiZer.

Player Commands

Admin Commands

/zpack Commands (Glyph & Pack Management)

The /zpack command group is the main toolkit for managing the resource pack from in-game. All subcommands require cxp.admin.

Permissions

All permission nodes and their defaults.