🧩 CustomItems

A powerful YAML-based custom item engine for Paper

CustomItems is a framework-style plugin that allows server owners to create advanced custom items using only YAML.

No coding.
No recompiling.
No limits.

Design mining tools, PvP weapons, abilities, combos, cooldowns, AoE effects, and more using a clean Trigger → Condition → Action system.

If you can describe it in logic, you can build it.

---

✨ Features

• Fully YAML-driven custom items
• Trigger → Condition → Action engine
• PvP & PvE ready
• Works with protection & combat plugins
• No silent failures (clear console warnings)
• Safe, performance-friendly execution
• Unlimited custom items
• Designed as a framework, not a one-off plugin

---

⚙️ Core Concept

Every custom item follows the same structure:

WHEN something happens → Trigger
IF rules pass → Conditions
DO something → Actions

Example:

ENTITY_HIT:
  conditions:
    - type: COOLDOWN
      seconds: 5
  actions:
    - type: DAMAGE
      amount: 4

**🔔 Triggers (WHEN)

Triggers define when an item activates.

Trigger	Description
BLOCK_BREAK	When a block is broken
ENTITY_HIT	When an entity is hit
RIGHT_CLICK	When the player right-clicks
🧠 Conditions (IF)

Conditions decide whether actions are allowed to run.

Available Conditions
Condition	Description
COOLDOWN	Per-item cooldown
HIT_COUNTER	Triggers every N hits
Condition Examples

Cooldown:

- type: COOLDOWN
  seconds: 5


Hit combo:

- type: HIT_COUNTER
  every: 3

**⚡ Actions (WHAT)

Actions define what the item actually does.

Combat & Ability Actions
Action	Description
DAMAGE	Deal extra damage
APPLY_EFFECT	Apply potion effects
APPLY_VELOCITY	Push or pull entities
SELECT_HIT_ENTITY	Select the hit entity
SELECT_NEARBY_ENTITIES	Select nearby entities
SELECT_SELF	Select the player
Tool Actions
Action	Description
BREAK_PATTERN	3×3 / cube mining
DURABILITY_COST	Custom durability usage
🎯 Target System (VERY IMPORTANT)

Some actions need to know who they affect.

**🔑 Golden Rule

If you use from: → you MUST select a target first

Target Keywords
Keyword	Meaning
self	The player
targets	Selected entities
Enemy Debuff Example
- type: SELECT_HIT_ENTITY
  store: targets

- type: APPLY_EFFECT
  from: targets
  effect: SLOW
  duration: 60

Player Buff Example
- type: SELECT_SELF
  store: targets

- type: APPLY_EFFECT
  from: targets
  effect: INCREASE_DAMAGE
  duration: 80

**🧱 Example Items
**🔨 3×3 Mining Pickaxe
BLOCK_BREAK:
  actions:
    - type: BREAK_PATTERN
      radius: 1
      shape: CUBE

**❄️ Frost Combo Sword
ENTITY_HIT:
  conditions:
    - type: HIT_COUNTER
      every: 3
  actions:
    - type: SELECT_HIT_ENTITY
    - type: APPLY_EFFECT
      effect: SLOW

**🌀 Void Pull Blade
ENTITY_HIT:
  actions:
    - type: SELECT_NEARBY_ENTITIES
      radius: 5
    - type: APPLY_VELOCITY
      mode: TOWARDS_PLAYER

**🛡 Compatibility

Paper / Purpur

Minecraft 1.20+ / 1.21+

Compatible with:

Region protection plugins

PvP plugins

Combat-tag plugins

Anti-cheat plugins

**🚀 Performance & Safety

Safe event priorities

Cancelled events respected

No region bypass

No NaN velocity crashes

No silent config failures

Designed for long-running servers

**📁 Configuration

items.yml → Define all custom items

config.yml → General settings (future expansion)

**🧩 Extensible Framework

Developers can add:

New triggers

New conditions

New actions

Without breaking existing items.

**⚠️ Common Mistakes

Effects not applying? → You forgot to SELECT a target

Item does nothing? → Check console warnings for typos

Damage too high? → Remember damage stacks with vanilla damage

**📦 Planned Features

Particle actions

Sound actions

Math / scaling expressions

Health-based conditions

GUI item editor

**🏁 Final Note

CustomItems is not just a plugin — it’s a framework.

Once you understand:

SELECT → APPLY


You can create anything.