PackItems is a high-performance custom item management and action routing system for Spigot 1.21+ servers.
It automatically extracts item assets, generates compressed resource packs, and deploys them to clients using a built-in HTTP hosting system, while providing an immersive YAML-driven execution layer for custom tools, weapons, and interactive items.
- Automatic asset extraction and item model definition generation
- Integrated high-performance HTTP server for automated distribution
- Single-pass compressed zip building with cryptographic SHA-1 validation
- Automatic prompt execution forcing pack installation on server join
- Directory-isolated per-item configuration structures
- Complete custom model data index mapping control
- Flexible trigger routing framework tracking interaction, movement, and combat states
- Rich sequential action execution pipeline with explicit flow control capabilities
- In-depth player attribute modifiers, custom stack sizing, and enchantment overrides
- Native compatibility with TextAPI tag formatting and placeholders
- Localized player cooldown tracking with fallback vanilla graphic overlays
- Optimized multi-threaded execution suite preventing runtime processing ticks
mvn clean package
Place the generated jar inside:
/plugins/PackItems-1.0.1.jar
Restart the server.
The main configuration file manages the integrated HTTP network listener and distribution policies for deployment.
resource-pack:
enabled: true
send-on-join: true
force: false
server:
enabled: true
host: "0.0.0.0"
port: 8080
path: "/packitems.zip"
public-url: ""
Custom items are declared inside unique subfolders located within the items parent folder. Every item declaration requires a valid item.yml and a companion texture file.
/plugins/PackItems/items/
├── ruby_sword/
│ ├── item.yml
│ ├── texture.png
│ └── model.json
└── heavy_shield/
├── item.yml
└── texture.png
The item.yml configuration manages metadata parameters, baseline item profiles, structural modifiers, and mapped trigger chains.
name: "<gradient:#ff0044:#ff00aa>Ruby Sword</gradient>"
lore:
- "<gray>A legendary sword forged in deep crimson blood.</gray>"
- "<dark_purple>Power Level: IX</dark_purple>"
material: DIAMOND_SWORD
render: HANDHELD
item:
max-stack-size: 1
unbreakable: true
custom-model-data: 1001
flags:
- HIDE_ATTRIBUTES
- HIDE_ENCHANTS
enchantments:
- type: SHARPNESS
level: 5
- type: UNBREAKING
level: 3
attributes:
- attribute: GENERIC_ATTACK_DAMAGE
amount: 8.5
operation: ADD_NUMBER
slot: HAND
- attribute: GENERIC_ATTACK_SPEED
amount: -2.4
operation: ADD_NUMBER
slot: HAND
actions:
RIGHT_CLICK_AIR:
- type: check_cooldown
- type: message
text: "<red>You have unleashed the crimson shockwave!</red>"
- type: play_particle
particle: FLAME
count: 20
- type: add_potion_effect
effect: INCREASE_DAMAGE
duration: 100
amplifier: 1
- type: set_cooldown
ticks: 120
| Key | Description | Valid Parameter Types |
|---|---|---|
name |
Item display title matching TextAPI syntax | Raw or tag-formatted string |
lore |
Text collection assigned under the item metadata | Ordered text list entries |
material |
Underlying Minecraft baseline structural item | Standard Bukkit Material Enum name |
render |
Generation model formatting style in hands | FLAT or HANDHELD |
item.max-stack-size |
Maximum limit allowed inside inventory slots | Numeric values from 1 to 64 |
item.unbreakable |
Prevents degradation of internal items durability | true or false |
item.custom-model-data |
Custom model data identification index assignment | Explicit positive integers |
item.flags |
Meta flags managing visibility details on tags | Standard Bukkit ItemFlag list |
item.enchantments |
Enchantments added directly to the object | Explicit type and level mappings |
item.attributes |
Attribute modifier values injected into user traits | Attribute, amount, operation, slot |
Triggers indicate exactly when action lists are parsed during player context interactions.
RIGHT_CLICK_AIR: Player right-clicks while aiming at open air.RIGHT_CLICK_BLOCK: Player right-clicks an active physical block target.LEFT_CLICK_AIR: Player swings their item or left-clicks open air space.LEFT_CLICK_BLOCK: Player left-clicks or strikes an active block structure.SHIFT_RIGHT_CLICK_AIR: Player sneaks and performs a right-click into the sky.SHIFT_RIGHT_CLICK_BLOCK: Player sneaks and performs a right-click on a block.SHIFT_LEFT_CLICK_AIR: Player sneaks and performs a left-click into the air.SHIFT_LEFT_CLICK_BLOCK: Player sneaks and performs a left-click on a block.
HIT_ENTITY: Player delivers a standard melee attack onto an active entity target.CRIT_ENTITY: Player lands an official critical hit attack strike while airborne.PROJECTILE_HIT: Projectile launched from this active item strikes a block or entity.BOW_SHOOT: Player fires an arrow utilizing a standard bow base material item.CROSSBOW_SHOOT: Player fires an object utilizing a crossbow base material item.TRIDENT_THROW: Player launches a trident tracking item into the world.
JUMP: Player executes a standard vertical jump action into the air.SNEAK_START: Player toggles their state and starts crouching.SNEAK_STOP: Player toggles their state and stops crouching.SWAP_HAND: Player triggers the hotkey to switch items to their offhand slot.DROP_ITEM: Player drops the custom item out of their active inventory.
BLOCK_BREAK: Player successfully destroys a block using the active item.BLOCK_PLACE: Player positions and finishes setting down a block structure.FALL_DAMAGE: Player encounters kinetic impact or falling damage parameters.DEATH: Player health markers reach absolute zero values.
Actions represent distinct instructions processed in a sequential pipeline when a trigger conditions match.
Transmits private styled text directly to the triggering user context.
type: message
text: "<green>Your weapon glows with holy light.</green>"
Transmits a server-wide announcement incorporating standard player name formatting.
type: broadcast
text: "<yellow>%player% has discovered an ancient relic!</yellow>"
Plays an auditory track centered at the exact location metrics of the player.
type: sound
sound: ENTITY_LIGHTNING_BOLT_THUNDER
volume: 1.0
pitch: 1.5
Forcibly terminates audio tracks based on sound reference keys or channel categories.
type: stop_sound
sound: MUSIC_DISC_PIGSTEP
category: RECORDS
Immediately halts action processing loops, terminating any subsequent actions down the line.
type: abort
Cancels the intercepted vanilla game engine interaction event, preventing blocks from breaking, items from moving, or weapons from firing.
type: cancel_event
Deducts an explicit number of units from the active hand item stack.
type: consume_item
amount: 1
Inflicts durability degradation damage directly onto tools matching damageable definitions.
type: damage_item
amount: 5
Injects extra health points into the player up to their maximum health cap parameter.
type: heal
amount: 6.0
Deals raw untyped damage directly onto the acting player entity profile.
type: damage
amount: 4.0
Ignites the player entity for a specified integer duration of tracking ticks.
type: set_fire
ticks: 60
Instantly quenches fire ticks, removing any active burning status on the player.
type: extinguish
Gives an active potion status condition effect to the player context.
type: add_potion_effect
effect: REGENERATION
duration: 200
amplifier: 2
Removes a single targeting status potion effect type from the player.
type: remove_potion_effect
effect: BLINDNESS
Clears out all running active potion effects simultaneously from the target.
type: clear_potion_effects
Restores raw food hunger points and saturation levels up to the maximum cap of 20.
type: feed
amount: 5
Forces the player to dispatch a localized server command string directly.
type: command_player
command: "home"
Dispatches an elevated administrative console command replacing the user placeholder value.
type: command_console
command: "give %player% diamond 1"
Spawns a localized cloud of visual particle objects around the user coordinates.
type: play_particle
particle: SOUL
count: 30
Tracks the player eye vector using ray trace algorithms up to a specific limit, spawning high-voltage lightning strikes at the intersection coordinate.
type: strike_lightning
range: 24.0
Triggers a high-impact explosion tracking target blocks, target entities, or fallback user coordinates.
type: explosion
power: 4f
Applies immediate velocity vector acceleration directly to the player.
type: push
x: 0.0
y: 1.2
z: 0.0
Overwrites the physical block state being targeted with an alternative material type.
type: set_block
material: AIR
Instructs the targeted block instance to break naturally while yielding its matching dropped materials.
type: break_block
Inflicts combat damage tracking flags directly on hit entities or targets.
type: damage_target
amount: 7.0
Applies restorative medical health adjustments onto target entities.
type: heal_target
amount: 4.0
Sets the focused target block or ray traced target entity on fire.
type: ignite_target
ticks: 100
range: 10.0
Injects a status effect map directly into the hit entity target.
type: add_potion_effect_target
effect: GLOWING
duration: 300
amplifier: 0
Inspects usage map records for restrictions, aborting the action flow if an item is still cooling down.
type: check_cooldown
Enforces a global item-scoped cooldown tick timer while applying a standard visual cooldown sweep over matching hand materials.
type: set_cooldown
ticks: 80
/packitems
/packitems reload
/packitems rebuild
/packitems list
/packitems give <player> <item_id> [amount]
| Subcommand | Description |
|---|---|
reload |
Wipes registry map definitions and completely reloads item configurations |
rebuild |
Triggers resource pack compilation, zipping, and cryptographic calculation |
list |
Lists the identifying tracking codes of all registered items |
give |
Generates a custom item stack instance and gives it to a specific player |
- Constant-time O(1) tracking lookups utilizing concurrent hash map frameworks
- Single-pass structural event routing featuring custom debounce protection logic
- Memory-mapped tracking keys ensuring identity mapping using native NamespacedKey indicators
- Multi-threaded asset delivery threads managing resource zip downloads asynchronously
- Completely cached configuration parameters mitigating heavy runtime disc lookup operations
- Auto-cleanup operations flushing isolated session datasets upon player disconnect events
packitems.command
Default:
op
| Node | Description | Default |
|---|---|---|
packitems.reload |
Permits execution of the configuration reload module | op |
packitems.rebuild |
Permits manual compilation of asset packages | op |
packitems.list |
Permits review of registered item identifier lists | op |
packitems.give |
Permits item distribution mechanics to active players | op |
packitems.use.<item_id> |
Restricts or grants active item usage for a specific ID | all |
packitems.use.* |
Global wildcard node allowing use of all custom items | all |
- Spigot 1.21+
- Paper 1.21+
- Java 21+
- Kotlin 2.4+
- TextAPI Integration
