ItemsCore
Build fully custom items, armor sets and talismans for your server - with no Java and no recompiling. Design everything in an in-game editor with a coding-like interface that gives you zero limitations, or let an AI write items for you. Works on Minecraft 1.8 - 26.2.
It also ships dupe detection, multi-server data sync and a player-inventory moderation tool for staff.
Installation
- Drop ItemsCore.jar into your server's plugins/ folder.
- Start the server once. The config and an items/ folder are generated in plugins/ItemsCore/.
- Run /itemeditor to open the item browser, or /itemeditor <name> to edit a specific item.
Optional integrations are detected automatically if installed: PlaceholderAPI, Vault and AuraSkills.
Free vs Premium
Both editions are identical in features. The only difference is how many custom items can be loaded, so the free version is a real, full-featured trial.
| Edition | Loaded items | Features |
|---|---|---|
| Free | 1 item at a time | Everything. |
| Premium | Unlimited | Everything. |
Editor basics
Open the editor with /itemeditor (or /itemeditor <name> to edit one). Everything below is set from a single item screen. Colours use & codes, and on supporting versions hex with &#rrggbb.
| Option | What it does |
|---|---|
| Item Material | Hold the item you want and click the button - it copies your held item. |
| Identifier | The internal id used in config files and commands. No spaces. Also stored on the item with a generated UUID for dupe detection. |
| Fancy Name | The coloured display name shown in-game. |
| Lore | Edit a line, right-click to remove it, shift-click for the next/new line, shift-right-click for the previous. |
| Enchantments | Opens a GUI of every enchantment; click one and enter a level. Click an added enchant to remove it. |
| Flags | Toggle Bukkit item flags on and off (e.g. hide attributes). |
| Custom Model Data | For resource-pack models. |
Click type & heads
The click type controls when click / right-click actions are allowed to run:
| Click type | Runs when the player clicks… |
|---|---|
| BLOCK | only a block |
| AIR | only air (empty space) |
| BOTH | either - the default |
This is set per action, so one item can have a right-click ability that only triggers in the air and a separate block interaction.
Skull owner
When the item is a player head, set Skull Owner to a username to use that player's skin as the texture.
Custom model data
Set Custom Model Data to a number to point the item at a model in your resource pack. Combined with a base material this is how most servers render fully custom item textures while keeping a normal Minecraft item underneath. The value is just an integer your pack maps to a model.
Actions
An action is behaviour attached to a trigger - for example "when the player right-clicks". You build it visually in three steps:
- Pick an action or event. Choose the trigger (left-click, right-click, etc). One item can have many actions. You can also click Create new custom event and build your own from 50+ supported server events, each with its player variables.
- Add methods. Click Click to add a method and pick from the categories. Right-click an empty method slot to load a saved template, right-click a built method to save it as a template, and right-click a category to set a method from it directly.
- Fill parameters. Simple types (text, numbers, booleans) are typed in directly. Right-click a parameter to open the methods menu and use another method's result as the value. Middle-click switches a parameter to chest mode for list/array values.
Methods run top to bottom. Between two methods you can drop an operator to build maths or conditions; leave it on None for the normal "run one after another" case. See the Triggers reference for what each trigger exposes, and Methods for everything you can call.
Crafting recipes
Give a custom item a shaped crafting recipe so players can craft it at a normal crafting table. Open the recipe GUI from the item editor and place ingredients in the 3x3 grid exactly as they should be laid out.
- Vanilla ingredients - any normal Minecraft material.
- Custom ingredients - another ItemsCore item can be required in a slot, matched by its identity, not just its material.
- Amounts - a slot can require more than one of an ingredient. Crafting consumes the exact amount you set, and the result only appears when enough is present.
Stats
Stats are named numbers you define once and then attach to items. Create and manage them with /stats (permission itemscore.stats). In an item's stats GUI you pick from your created stats and set the value for that specific item.
Read a stat inside an action with core.getItemStatValue(item, "strength") or a player's combined stat with core.getPlayerStatValue(player, "strength"), and expose stats through PlaceholderAPI.
Talismans
The talisman toggle changes when an item's stats and actions apply:
- Normal item - effects apply while it is equipped as armor or held in hand.
- Talisman - effects apply while the item simply sits anywhere in the player's inventory.
Talismans are perfect for passive bonuses that should not cost an armor or hotbar slot. Check it from code with core.isTalisman(item).
How the code works
Every action compiles to a small script. The visual builder writes it for you, so you never have to type it, but the shape is simple:
A handful of variables are always available depending on the trigger: core, particles, values, api and item always; player on most triggers; event for cancelling; and others like shooter, victim or arrow on the relevant triggers. The core toolbox covers messaging, movement, combat, world edits, sounds, particles, projectiles, timing, player variables and (with Vault) economy.
- Use core.doIf / core.doIfElse / core.chanceOf for conditions.
- Use core.runCodeLater and core.loop for delays and repetition.
- Strings are encoded safely behind the scenes, so quotes inside quotes never break - even for deeply nested abilities.
Events
Events are the same idea as actions, but separated out because they react to things happening to the player rather than a direct click. Each exposes its own variables, and you can stop the event with core.cancelEvent(event).
| Event | Fires when | Key variables |
|---|---|---|
| DamageEvent | the item is used to attack an entity | attacker victim cause damage |
| PlayerDamageEvent | the holder/wearer takes damage | player cause damage |
| ProjectileHitEntityEvent | a shootProjectile projectile hits an entity | shooter victim lastLocation |
| ProjectileHitBlockEvent | that projectile hits a block | shooter lastLocation |
| ArmorEquipEvent | the armor is equipped | player item |
| ArmorUnEquipEvent | the armor is unequipped | player item |
| PlayerMoveEvent | the player moves holding/wearing the item | player item |
Beyond these, the Create new custom event button lets you react to any of 50+ Bukkit events directly, each with the player it resolves and the raw event object.
Cooldowns
Each action can have its own per-player cooldown. Open the cooldown clock in the action's GUI and type any duration - a number with a unit, like 5s, 90s, 2m or 1h (a bare number means seconds). While the cooldown is active that action will not run for that player.
On-cooldown message
You can also send the player a message when they try to use the action too soon. Shift-click the cooldown clock to set the message; shift-right-click clears it. The message supports & colours and these time-left placeholders:
| Placeholder | Becomes |
|---|---|
| %remaining_seconds% | whole seconds left, rounded up |
| %remaining_minutes% | whole minutes left, rounded up |
| %remaining_hours% | whole hours left, rounded up |
| %remaining% | formatted time, e.g. 1m 30s |
| %remaining_millis% | milliseconds left |
Examples
Fire burst (left-click)
Particle projectile (right-click)
25% chance to strike lightning
Supported plugins & addons
ItemsCore detects these automatically when they are installed:
| Plugin | What it unlocks |
|---|---|
| Vault | Connect to the server economy - core.balance, core.deposit, core.withdraw. |
| PlaceholderAPI | Parse placeholders in strings with core.parsePlaceholder(player, text), and expose item stats (see Placeholders). |
| AuraSkills | Skills, mana and stats - pairs well with custom items for RPG servers. |
Developers can extend ItemsCore further with addons that add their own methods, attributes, listeners and actions. See the Developer Documentation.
Placeholders
With PlaceholderAPI installed, ItemsCore registers the itemscore expansion so you can show item stats in scoreboards, holograms, tab lists and anywhere else placeholders are parsed.
| Placeholder | Returns |
|---|---|
| %itemscore_statValue_<stat>_<item>% | the raw stat value for that item, e.g. 50 |
| %itemscore_statFancyName_<stat>% | the stat's display name |
| %itemscore_statFancyValue_<stat>_<item>% | the formatted value (the stat's value template with the number filled in) |
| %itemscore_statFancyString_<stat>_<item>% | the display name and formatted value together |
Replace <stat> with the stat name and <item> with the item identifier, for example %itemscore_statValue_damage_magic_sword%.
AI helper
You can let an AI build and edit ItemsCore items for you, with no coding. To keep it in one place and always up to date, the whole thing - a one-paste setup prompt, the local MCP server, and the full guide - lives in the helper repo: github.com/Core-Pluginss/ItemsCore-Helper. Open it, copy the prompt into your AI, and it sets itself up and builds your item.
The AI reads this exact API, validates what it writes, and hands you a .import file. Importing it rebuilds a normal, GUI-editable item - so anything the AI makes you can still tweak by hand in the editor.
Commands
Run /ic (or its full alias /itemscore) on its own to see the command list. Run a subcommand on its own, like /ic database, to see just that group's commands.
| Command | Description |
|---|---|
| /itemeditor [name] | Open the item browser, or edit a specific item. |
| /ic | Show the full command list. |
| /ic menu | Open the items menu. Left-click an item to edit it, right-click to give / set recipe / delete, or use the button to create a brand new item. (/ic gui still works.) |
| /ic reload [item] | Reload all items, or one item. Returns a success / error list and retries previously-failed items. |
| /ic export <item> | Export an item to clean JSON (exports/). |
| /ic import <file> | Import a clean JSON from imports/ as a live, GUI-editable item. |
| /ic adopt <item> | Make a code-only item editable in the GUI. |
| /ic delete <item> confirm | Delete a custom item (removes it from memory, its file, and the database if enabled). |
| /ic exportapi | Write the machine-readable API manifest (itemscore-api.json). |
| /ic database | Multi-server sync tools (see below): status, migrate, restore. |
| /ic libraries | Show the status of the runtime-downloaded MongoDB / Redis drivers. /ic libraries verify downloads or repairs them. |
| /stats | Create and manage custom stats. |
| /addons | Open the addons menu to browse the ItemsCore addons installed on the server. |
| /playerinventory <player> | Open a player's inventory for moderation. |
| /toggledupealerts /tda | Toggle the dupe-detection alerts staff receive in chat when a duplicated item is found. |
Permissions
| Permission | Grants |
|---|---|
| itemscore.admingui | /ic / /itemscore and every subcommand |
| itemscore.itemeditor | /itemeditor |
| itemscore.stats | /stats |
| itemscore.addons | /addons |
| itemscore.playerinventory | /playerinventory |
| itemscore.toggledupealerts | /toggledupealerts (/tda) |
Multi-server sync
Running a network? ItemsCore can keep data consistent across servers using a shared MongoDB database, with optional Redis for instant propagation. Each category is configured independently in config.yml under database - keep it in files (the default) or make it database-wide:
| Category | What syncs |
|---|---|
| items | your custom items |
| global-variables | server-wide variables |
| player-variables | per-player variables |
| config | the whole config (except the database section, which stays local) |
- Set your MongoDB URI and database name, then enable the categories you want - or flip enable-all to turn on every category at once.
- The database stays fully off until you enable at least one category, so single-server setups are unaffected.
- Redis is optional. With it, changes propagate instantly; without it, servers poll on an interval. ItemsCore always falls back to files if the database is unreachable - a bad connection never takes the plugin down.
Migrating
| Command | Description |
|---|---|
| /ic database status | Show the connection state and which categories are database-wide. |
| /ic database migrate confirm | Push your current file data up into the database. |
| /ic database restore confirm | Pull the database data back down into files. |
Triggers
A trigger is when an action fires. Each one exposes the variables listed here.
| Trigger | Fires when | Variables |
|---|---|---|
| leftAction | Player left-clicks while holding the item. | playeritemevent |
| leftSAction | Player sneak + left-clicks while holding the item. | playeritemevent |
| rightAction | Player right-clicks while holding the item. | playeritemevent |
| rightSAction | Player sneak + right-clicks while holding the item. | playeritemevent |
| shiftAction | Player starts sneaking while holding or wearing the item. | playeritemevent |
| dropAction | Player drops the item (the drop is cancelled). | playeritemevent |
| swapAction | Player swaps hands (F key) with the item. | playeritemevent |
| shootAction | Player shoots a projectile while holding the item. | shooteritemevent |
| pickupAction | Player picks up the item. | playeritemevent |
| arrowLandAction | An arrow shot while holding the item lands. | shooteritemarrowlandLocationevent |
| armorEquipEvent | The item (armor) is equipped. | playeritemevent |
| armorUnEquipEvent | The item (armor) is unequipped. | playeritemevent |
| playerMoveEvent | Player moves while holding or wearing the item. | playeritemevent |
| playerDamageEvent | Player holding or wearing the item takes damage. | playeritemevent |
| projectileHitEntityEvent | A custom projectile from this item hits an entity. | shootervictimitemlastLocationevent |
| projectileHitBlockEvent | A custom projectile from this item hits a block. | shooteritemlastLocationevent |
Variables
Values you can use directly inside an action.
| Variable | Type | Available |
|---|---|---|
| core | ActionCore$Core | Always available. |
| particles | ActionCore$Particles | Always available. |
| values | ActionCore$CustomValues | Always available. |
| api | ItemsCoreAPI | Always available. |
| item | Item | Always available (the custom item this action belongs to). |
| event | Event | Always available (the Bukkit event; cancel with core.cancelEvent(event)). |
| player | Player | Most triggers. |
| shooter | LivingEntity | shootAction, arrowLandAction, projectile hit events. |
| victim | Entity | projectileHitEntityEvent. |
| arrow | Entity | arrowLandAction. |
| landLocation | Location | arrowLandAction. |
| lastLocation | Location | projectile hit events. |
Methods
Everything you can call in an action, generated directly from the plugin so it always matches your version. Pick a binding, browse by category, or search.
coreMain toolbox. Most actions live here: damage, teleport, sounds, projectiles, variables, loops, conditionals.
▶Blocks10
Breaks a block naturally, dropping its normal loot.
Breaks a block naturally as if mined with the given custom item, dropping its loot.
Changes a block into the material with the given name.
Changes a block into the given material.
Gets the block at the given x, y, z coordinates in a world.
Gets the block at a given location.
Returns all blocks in a box around a location, reaching the given distance on each axis.
Returns the material (type) of a block.
Turns a block into air, making it disappear without drops.
Removes a whole list of blocks at once, turning them all to air.
▶Combat6
Deals the given amount of damage to a living entity (half a heart = 1).
Damages a living entity and credits the damage to an attacker, so kills are attributed correctly.
Heals a player by the given amount, capped at their max health (half a heart = 1).
Knocks an entity away from a location, with extra strength set by the multiplier.
Sets a player's health to an exact amount (half a heart = 1).
Damages every entity near a player (except the player) within the given x, y, z range.
▶Economy3
Returns a player's money balance (requires the Vault plugin).
Adds money to a player's balance and returns whether it succeeded (requires the Vault plugin).
Removes money from a player's balance and returns whether it succeeded (requires the Vault plugin).
▶Effects1
Gives a player a potion effect for a duration (in ticks) at the given strength level.
▶Entities5
Finds an entity in a world by its numeric entity id, or nothing if not found.
Finds an entity in a world by its UUID text, or nothing if not found.
Returns all entities near a player within the given x, y, z distances.
Removes an entity from the world (kills it without drops).
Spawns an entity of the given type at the x, y, z position and returns its UUID as text.
▶Items17
Empties a player's entire inventory.
Drops an item on the ground at a location.
Drops the given material on the ground at a location.
Returns the boots a player is wearing.
Returns the chestplate a player is wearing.
Returns the helmet a player is wearing.
Returns the item in a specific inventory slot of a player.
Builds the actual in-game ItemStack for one of your custom items.
Returns the value of one of a custom item's stats by name, or 0 if the item does not have it.
Returns the leggings a player is wearing.
Looks up a Minecraft material (block or item type) by its name.
Gives a player one of the given material as an item.
Checks whether an item is a custom ItemsCore item with the given id.
Checks whether a custom item is a talisman (a passive item kept in the inventory).
Creates a new player head item showing the given player's skin.
Sets an existing player-head item to show the given player's skin.
Removes one of the item the player is currently holding from their hand.
▶Logic6
Cancels the current event so the normal action (like the block break or damage) does not happen.
Returns true with the given percent chance (0-100). Great for random ability procs.
Runs a piece of script code only if the condition is true.
Runs one piece of script code if the condition is true, otherwise runs the other piece.
Runs a piece of script code right now.
Runs a piece of script code after a delay measured in ticks (20 ticks = 1 second).
▶Loops4
Repeatedly runs a piece of script code a set number of times, waiting the given ticks between each run (-1 times means forever). The current loop number is available as tIndex.
Runs a piece of script code once for each item in an array, with the current item available as currentArrayObject.
Keeps running a piece of script code every few ticks while a condition stays true.
Waits until a condition becomes true, then runs a piece of script code (the safe value limits how long it waits).
▶Messaging3
Broadcasts a message to every player on the server.
Turns & color codes in a piece of text into real Minecraft colors.
Sends a chat message to one player, supporting & color codes and hex (&#rrggbb).
▶Movement11
Builds a direction/velocity vector from x, y, z math expressions.
Stops a player from flying.
Lets a player fly.
Freezes an entity in place for the given duration (in ticks) by keeping it at its current spot.
Turns an entity to face the given yaw and pitch without moving it.
Pushes a player using x, y, z math expressions as the velocity direction and strength.
Pushes a player using a ready-made velocity vector.
Teleports an entity to the given x, y, z in its current world (keeps its facing direction).
Dashes a player forward in the direction they are looking, up to the given range (skipBlocks=true lets them pass through walls).
Teleports one entity directly to another entity's position.
Teleports an entity to a specific location.
▶Particles2
Spawns a particle effect at the x, y, z position every tick for the given number of ticks.
Spawns a particle effect at a location every tick for the given number of ticks.
▶Players12
Makes a player run a command as if they typed it in chat.
Returns the location of a player's eyes (their head, where they are looking from).
Finds an online player by their name, or returns nothing if they are offline.
Finds an online player by their UUID.
Finds an online player by their UUID written as text.
Returns the value of one of a player's custom stats by name.
Hides a player so no other online player can see them.
Hides a player from everyone, then makes them visible again after the given number of ticks.
Returns the list of all players currently online on the server.
Changes a player's game mode (survival, creative, adventure, spectator).
Makes a hidden player visible to everyone again.
Makes a player visible to everyone, then hides them again after the given number of ticks.
▶Projectiles3
Builds a movement equation (using 't' for time in ticks) that shapes a custom projectile path. Axes are relative to the shooter's facing: X = forward (the way they look), Y = up, Z = left. A normal forward-flying projectile puts the motion on X, e.g. createEquationVector("t * 0.4", "0", "0"); use Y for arc and Z to curve sideways.
Makes a player shoot an arrow in the direction they are looking.
Fires a custom ItemsCore projectile from a player, following the given path equation for a set number of ticks. The equation axes are relative to where the player looks: X is forward, Y is up, Z is left - so a straight forward shot puts the motion on X.
▶Sound2
Looks up a Minecraft sound by its name.
Plays a sound to a player at a location with the given volume and pitch.
▶Utility2
Returns the current system time in milliseconds, handy for cooldowns.
Replaces PlaceholderAPI placeholders in text with their real values for a player.
▶Variables5
Reads a global (server-wide) saved variable by name, creating it empty if it does not exist.
Reads a saved variable stored on a player, creating it empty if missing (use temp=true for variables cleared on logout).
Reads a player's saved variable, or sets and returns a default value if it does not exist yet.
Saves a global (server-wide) variable by name so it persists and can be read later.
Saves a variable on a player (use temp=true for variables cleared when they log out).
▶World8
Returns a new location shifted by the given x, y, z amounts.
Makes a copy of a location so you can change it without affecting the original.
Creates an explosion of the given power at the x, y, z position in a world.
Creates an explosion of the given power at a location.
Builds a location object from a world and x, y, z coordinates.
Gets a world by its name, or nothing if no world has that name.
Strikes lightning at the given x, y, z position in a world.
Strikes lightning at a location.
particlesParticle shapes and displays (circles, helixes, custom particles).
▶Particle Shapes48
Draws a static atom with orbit rings and a nucleus of particles at the display's location.
Animates an atom with spinning orbit rings of particles at the display's location for a number of ticks.
Draws a black sun shape made of shrinking circles at the display's location.
Animates a swirling blackhole of particles at the display's location for a number of ticks (mode changes the shape).
Draws a cage of vertical particle bars between two corner locations, useful for trapping effects.
Animates a chaotic double-pendulum swing of particles at the display's location for a number of ticks.
Draws a circle (or oval) of particles at the display's location.
Draws a moving beam of pulsing circles that travels forward in the display's direction for a number of ticks.
Continuously spawns a raincloud effect using the two given particle displays.
Draws a cone of particles standing up from the display's location.
Draws a crescent moon shape of particles at the display's location.
Draws a hollow cube (all six faces filled) of particles between two corner locations.
Draws a cylinder of particles standing up from the display's location.
Draws a diamond (rotated square) shape of particles standing up at the display's location.
Draws a DNA double-helix of particles rising from the display's location, with bond lines between the strands.
Animates a growing DNA strand with colored nucleotide bonds rising from the display's location.
Draws a straight line of particles out from a player's eyes in the direction they are looking.
Draws an ellipse (oval) arc of particles between the start and end angles at the display's location.
Animates an expanding explosion shockwave of particles at the display's location.
Draws an eye shape of particles at the display's location.
Draws a solid filled disc of particles at the display's location.
Draws a fully solid cube of particles between two corner locations.
Draws a flower-petal pattern, running the given task at each petal point around the display's location.
Draws a heart shape of particles at the display's location.
Animates a spiral helix of particles rising in the display's direction (fadeUp and fadeDown taper the ends).
Draws nested wireframe cubes connected like a 4D hypercube between two corner locations.
Draws an illuminati triangle-with-an-eye symbol of particles at the display's location.
Draws an infinity (figure-eight) symbol of particles at the display's location.
Draws a flat Julia-set fractal pattern of particles at the display's location.
Draws a jagged branching lightning bolt of particles from a start point in a direction.
Draws a straight line of particles between two locations.
Continuously draws growing magic circles that travel forward in the display's direction.
Draws a flat Mandelbrot fractal pattern of particles at the display's location.
Draws a pentagram star inside a circle at the display's location.
Draws a polygon outline of particles with the given number of points at the display's location (use connection to make stars).
Draws a multi-colored rainbow arc of particles at the display's location.
Draws a filled flat rectangle of particles between two corner locations.
Draws a ring (donut/torus) shape of particles at the display's location.
Draws a sword-slash arc of particles at the display's location (useWideSide makes the wider half of the swing).
Draws an animated sword slash that travels forward in the display's direction over a distance.
Draws a hollow sphere of particles at the display's location.
Draws a spiky ball of particles (a sphere with random spikes sticking out) at the display's location.
Animates scattering lines of particles from a start point toward a randomly spread end area.
Animates a spiky star burst of particles at the display's location.
Draws only the edges (wireframe) of a cube of particles between two corner locations.
Animates a rotating 4D tesseract of particles at the display's location for a number of ticks.
Animates a spinning vortex of spreading particles at the display's location for a number of ticks.
Draws a wavy rippling surface of particles at the display's location.
▶Particles8
Creates a colored dust particle display from red, green, blue (0-255) and a size.
Builds a fully customized particle definition (count, size, color, block/item data and more) to turn into a display.
Turns a custom particle definition into a particle display you can use in shapes.
Creates a particle display from a particle name, used as the look for particle shapes.
Returns a random whole number between the two values (both ends included).
Returns a random decimal number between the two values.
Sets the direction a particle display points in.
Sets the location where a particle display will be drawn.
valuesConstant and value helpers usable as method arguments.
▶Variables2
Turns a piece of text into its real type (number, true/false, or text) automatically.
Reads a script variable that is currently available by its name.
apiItemsCore API accessors usable from actions.
▶Economy1
Checks whether the Vault economy plugin is installed and available.
▶Items4
Finds one of your custom items by its name, or nothing if no item has that name.
Returns the custom name of an item stack.
Gives a player one of your custom items.
Returns the custom item a player is holding, or nothing if it is not an ItemsCore item.
▶Players1
Returns the helper used to ask a player for typed chat input.