CRISSTEALCORE - HOW TO CONFIGURE ITEMS
======================================

Overview
--------
All custom items are defined as individual .yml files inside the `plugins/CrisStealCore/items/` folder. Each file represents ONE item and its full behavior: visuals, activators, cooldowns, effects, sounds, particles, commands, messages, restrictions, etc.

This document explains every supported option, shows full examples, and lists common pitfalls/conflicts so your items work as intended on modern Minecraft (1.20+ / 1.21+).


Basic Structure (top-level fields)
----------------------------------
name: "&6My Item Name"
material: PAPER | DIAMOND | head-<base64_or_texture_url>
custom-model-data: 1234               # optional (resource pack models)
lore:                                 # optional lines
  - "&7Line 1"
  - "&7Line 2"
glow: true | false                    # cosmetic enchanted glow
Hiders:                               # optional item flags
  - 'HIDE_ATTRIBUTES'
  - 'HIDE_ENCHANTS'
consume-use: true | false             # remove 1 item on successful use
cooldown: 60                          # seconds (per-player, per-item)
cancel_place: false                   # prevent block placement of this item
disable_drop: true | false            # prevent dropping item with Q
disable_drop_message: "&cYou cannot drop this item!"
disable-world: [world1, world2]       # list of worlds where the item is disabled
# AuraSkill support
need-mana: 10
[/SIZE]
# All interactions are defined under `activators:` (see below)
activators:
  <key>: # example: activator1
    option: RIGHT_CLICK | LEFT_CLICK | DROP_ACTIVATE or ALL_CLICK
    sound: "ENTITY_IRON_GOLEM_ATTACK"          # plays on success
    particles-success: "CRIT"                  # shows on success
    messages:
      when-using: "&aUsing item..."           # message on success
      on-cooldown: "&cCooldown: %criscore_cooldown_<item-id>%" # supports PAPI # or own system: {cooldown}
      denied_sound: "ENTITY_VILLAGER_NO"      # when denied (cooldown/world, etc.)
      particles-denied: "VILLAGER_ANGRY"
    commands:
      - "effect give %player_name% minecraft:strength 120 1 true"
    extras-success:                         # per-activator displays when succeed
      title:
        message: "&a&lSuccess!"
        fade-in: 5
        stay: 40
        fade-out: 10
      subtitle:
        message: "&7Power flows"
      actionbar:
        message: "&eBuff applied"
    extras-denied:                          # per-activator displays when denied
      title:
        message: "&c&lDenied!"
        fade-in: 5
        stay: 40
        fade-out: 10
      subtitle:
        message: "&7Try later"
      actionbar:
        message: "&cOn cooldown"

# Global display (optional). These show in addition to activator extras.
title:
  message: "&a&lSuccess!"
  fade-in: 10
  stay: 60
  fade-out: 20
subtitle:
  message: "&7Sub info"
actionbar:
  message: "&eActionbar text"


Materials
---------
- Use any valid Bukkit material name (e.g., PAPER, DIAMOND, NETHER_STAR).
- Custom heads: `material: head-<value>`
  - <value> may be:
    - A Base64 texture string
    - A full texture URL (e.g., https://textures.minecraft.net/texture/...) possibly base64-wrapped
  - The plugin decodifies Base64 to extract the texture URL and applies it to a skull item.


Model/Stacking
--------------
- `custom-model-data` lets you bind the item to a resource pack model.

Visibility/Glow
---------------
- `glow: true` gives an enchanted appearance without adding a real enchant.
- `Hiders` accepts Bukkit ItemFlag constants like 'HIDE_ATTRIBUTES', 'HIDE_ENCHANTS'.


Use, Cooldown, Drop, World Restriction
--------------------------------------
- `consume-use: true` consumes one unit upon successful activation.
- `cooldown: <seconds>` per-player; the placeholder `%criscore_cooldown_<item-id>%` shows remaining time.
- `disable_drop: true` blocks Q-drop; `disable_drop_message` shows when blocked.
- `disable-world: [world1, world2]` — item cannot be used in listed worlds (denied effects/messages will be shown).


Activators and Messages
-----------------------
- `activators:` defines how the item is triggered.
  - `option: RIGHT_CLICK` — right click in air/block.
  - `option: LEFT_CLICK`  — left click in air/block.
  - `option: DROP_ACTIVATE` — press Q to activate (distinct from disable_drop).
  - `option: ALL_CLICK` - all clicks detections.
- `messages:`
  - `when-using`: shown on success.
  - `on-cooldown`: shown when item is on cooldown.
    - Supports PlaceholderAPI and CrisCore placeholders. Use `%criscore_cooldown_<item-id>%`.
      - If your item id has hyphens, placeholders convert `-` to `_`. Example: id `scroll-strength` => `%criscore_cooldown_scroll_strength%`.
  - `denied_sound` and `particles-denied`: when usage is blocked (world disabled, cooldown, etc.).
- `extras-success` and `extras-denied` can display titles/subtitles/actionbars specifically for this activator outcome.
- At the item root you can also set global `title/subtitle/actionbar` shown on success.


Sounds and Particles
--------------------
- `sound:` and `messages.denied_sound:` accept valid Bukkit sound names.
- `particles-success:` and `messages.particles-denied:` accept particle keys (e.g., CRIT, WITCH, VILLAGER_ANGRY, VILLAGER_HAPPY, HEART, FLAME, ENCHANTMENT_TABLE, SPELL_WITCH, SLIME, CLOUD, etc.).
- See `EFFECTS_REFERENCE.txt` for a curated list of examples.


Commands (1.21+ examples)
-------------------------
- Commands are executed from console by default. If the line starts with `criscore` or `criscoreadmin`, it will be performed by the player.
- Use modern syntax:
  - `effect give %player_name% minecraft:strength 120 1 true`
  - `give %player_name% minecraft:experience_bottle 50`
  - `xp add %player_name% 50 points`
  - `effect give %player_name% minecraft:regeneration 10 1 true`
- Placeholders available:
  - `%player_name%`, and PAPI placeholders (if PlaceholderAPI is installed)


Examples from This Plugin
-------------------------
1) Heart (simple, anti-drop, global displays)
--------------------------------------------
name: "&cHeart Fragment"
material: NETHER_STAR
custom-model-data: 1001
glow: true
consume-use: true
cooldown: 60
disable_drop: true
disable_drop_message: "&cYou cannot drop this!"
activators:
  use:
    option: RIGHT_CLICK
    sound: "ENTITY_PLAYER_LEVELUP"
    particles-success: "HEART"
    commands:
      - "effect give %player_name% minecraft:absorption 60 0 true"
    messages:
      when-using: "&aYou used a Heart Fragment!"
      on-cooldown: "&cCooldown: {cooldown}"

2) Scroll of Strength (per-activator displays)
----------------------------------------------
name: "&6Scroll of Strength"
material: PAPER
glow: true
consume-use: true
cooldown: 400
activators:
  example1:
    option: RIGHT_CLICK
    sound: "ENTITY_IRON_GOLEM_ATTACK"
    particles-success: "CRIT"
    extras-success:
      title:
        message: "&a&lStrength II"
        fade-in: 5
        stay: 40
        fade-out: 10
      subtitle:
        message: "&7You feel stronger!"
      actionbar:
        message: "&e&lStrength II &7activated!"
    commands:
      - "effect give %player_name% minecraft:strength 120 1 true"
    messages:
      on-cooldown: "&cThis item is on cooldown &c%criscore_cooldown_scroll_strength%&c!"
      denied_sound: "ENTITY_VILLAGER_NO"
      particles-denied: "VILLAGER_ANGRY"
    extras-denied:
      title:
        message: "&c&lStrength II"
        fade-in: 5
        stay: 40
        fade-out: 10
      subtitle:
        message: "&7You feel weaker!"
      actionbar:
        message: "&c&lStrength II &7activation failed!"

3) Magic Scroll (DROP_ACTIVATE example)
--------------------------------------
name: "&dMagic Scroll"
material: PAPER
custom-model-data: 1200
consume-use: true
cooldown: 120
activators:
  drop:
    option: DROP_ACTIVATE
    sound: "ENTITY_EXPERIENCE_ORB_PICKUP"
    particles-success: "ENCHANTMENT_TABLE"
    messages:
      when-using: "&dArcane surge!"
      on-cooldown: "&cWait &f%criscore_cooldown_magic_scroll% &cbefore using again."
    commands:
      - "xp add %player_name% 50 points"
      - "effect give %player_name% minecraft:luck 60 1 true"

4) Custom Head (texture by Base64)
----------------------------------
name: "&bMystery Head"
material: head-<BASE64_OR_TEXTURE_URL>
consume-use: false
cooldown: 0
activators:
  click:
    option: RIGHT_CLICK
    messages:
      when-using: "&bSpooky!"
    particles-success: "CLOUD"
    sound: "ENTITY_ENDERMAN_AMBIENT"


5) Requirements (need-to-activate) and Money Requires
-----------------------------------------------------
# This item only works if player has at least 20 health (10 hearts),
# has at least 20 armor points, is in world "world", and has either
# 1000 Vault money or 1000 Coins (configured separately).

name: "&aTanky Activation Test"
material: NETHERITE_INGOT
consume-use: false
cooldown: 10
activators:
  use:
    option: ALL_CLICK
    commands:
      execute-as: [console]
      - "criscoreadmin add healt %player_name% 1"
    messages:
      when-using: "&aActivated!"
      on-cooldown: "&cWait: %criscore_cooldown_tanky_activation_test%"
    extras-denied:
      title:
        message: "&c&lRequirements not met"
        fade-in: 5
        stay: 40
        fade-out: 10
      subtitle:
        message: "&7See chat for details"

need-to-activate:
  requirement1:
    conditions:
      - HEALTH,20
    messages:
      - "&cYou need at least &4❤20 &chealth (10 hearts)."
  requirement2:
    conditions:
      - ARMOR_POINTS,20
    messages:
      - "&cYou need at least &f20 &carmor points."
  requirement3:
    conditions:
      - WORLD_NAME,world
    messages:
      - "&cUse this in world: &fworld"

# Optional money requires: choose one or include both; they are all required
# Formats: BALANCE_VAULT,<amount> or BALANCE_COINS,<amount>
money_requires:
  - BALANCE_VAULT,1000
  - BALANCE_COINS,1000
  - BALANCE_COINSENGINE,100 # Coins Engine Support
money_requires_messages:
  - "&cYou do not have enough balance to use this item."

Supported condition keys:
- KILLS,<min>              - Player kills (plugin stats)
- DEATHS,<min>             - Player deaths (plugin stats)
- OFFHAND_ITEM              - Must have any offhand item
- HAS_POTION_EFFECT         - Any active potion effect
- HAS_EFFECT_SPEED          - Specific potion effects also available:
- HAS_EFFECT_STRENGTH
- HAS_EFFECT_REGEN
- HAS_EFFECT_FIRE_RESISTANCE
- HAS_EFFECT_JUMP_BOOST
- IS_ON_FIRE                - Player burning
- IS_FROZEN                 - Frozen state (1.17+)
- IS_INVISIBLE              - Invisible (via effect)
- WORLD_NAME,<name>        - Exact world name
- BIOME,<biome>            - Current biome name
- REGION,<name>            - Requires WorldGuard; fails if WG not installed
- IS_UNDERWATER             - Eye is in water
- IS_IN_LAVA                - Standing in lava
- IS_ON_GROUND              - Standing on ground
- Y_LEVEL,<minY>           - Y coordinate >= value
- TIME_OF_DAY,<minTick>    - World time >= value (0..24000)
- IS_RAINING                - World is raining
- IS_NIGHT                  - Time between 13000 and 23000
- HEALTH,<min>
- MAX_HEALTH,<min>
- ARMOR_POINTS,<min>
- ATTACK_DAMAGE,<min>
- ATTACK_SPEED,<min>
- MOVEMENT_SPEED,<min>
- LUCK,<min>
- KNOCKBACK_RESISTANCE,<min>
- SATURATION,<min>
- FOOD_LEVEL,<min>
- LEVEL,<min>
- EXPERIENCE,<min>

Notes:
- If a requirement fails, the item will show its `extras-denied` (if present),
  play denied sound/particles if configured, and print the requirement's
  `messages` lines to the player.
- Money requires check balance only; they do NOT deduct money.
- REGION needs WorldGuard. If WG is not present, REGION requirements will fail.


Conflicts and Tips
------------------
- DROP_ACTIVATE vs disable_drop:
  - If you want Q to ACTIVATE the item, keep `disable_drop: false` or unset; otherwise the drop-block will cancel before the activator runs.

- Cooldown placeholders:
  - Item ids in placeholders use underscores: `%criscore_cooldown_<item_id_with_underscores>%`.
    - Example: file id `scroll-strength` becomes `%criscore_cooldown_scroll_strength%`.

- World restrictions:
  - If the item is used in a world listed in `disable-world:`, usage is denied; your `messages.particles-denied` and `messages.denied_sound` apply.

- Commands syntax:
  - Use 1.21+ syntax shown above. Old forms like `give experience` no longer work.

- Titles/Subtitles/Actionbars:
  - You can define global displays at root and per-activator displays under `extras-success` / `extras-denied`.
  - All support PlaceholderAPI.

- Head textures:
  - If using Base64, the plugin extracts the skin URL from the decoded payload.
  - If a direct texture URL is used, ensure it is a valid textures.minecraft.net URL.


Troubleshooting
---------------
- Item not loading:
  - Confirm the file ends with `.yml` and is in `plugins/CrisStealCore/items/`.
  - Check console for load errors.

- Cooldown always shows 0s in messages:
  - Ensure the placeholder matches your item id with underscores.
  - Verify the item actually went on cooldown (use /papi parse for debugging if PlaceholderAPI is installed).

- Sounds/particles not playing:
  - Verify the names are valid for your server version; use entries from `EFFECTS_REFERENCE.txt`.

- Nothing happens on Q:
  - Remove/disable `disable_drop` if using `DROP_ACTIVATE`.


That’s it! Create as many item files as you want, fully dynamic—no hardcode required.