itemscore-helper 1.2.2 → 1.3.0

package/bin/cli.js

@@ -20,7 +20,7 @@ const SETUP_PROMPT = [
   "",
   "2. Read " + LLMS_URL + " so you know the ItemsCore item format and every method available.",
   "",
-  "3. Tell me you are ready, then ask what item I want. Build a valid .import file (clean item JSON), validate it, and tell me to drop it in plugins/ItemsCore/imports/ and run /ic import in-game. The item stays fully editable in the in-game editor.",
+  "3. Tell me you are ready, then ask what item I want. Build the clean item JSON, validate it with the validate_item tool, and save it as a file ending in .import (for example flame_sword.import) - never .item. Tell me to drop it in plugins/ItemsCore/imports/ and run /ic import in-game. To change an item I already imported, edit the JSON and import it again with the same name (it overwrites the existing item). The item stays fully editable in the in-game editor.",
 ].join("\n")
 
 function copyDir(src, dest) {

package/bin/mcp.js

@@ -24,7 +24,7 @@ async function main() {
     { name: "itemscore", version: String(idx.manifest.pluginVersion || "1") },
     {
       instructions:
-        "ItemsCore is a Minecraft (Bukkit/Spigot) plugin that lets server owners build custom RPG items with no Java. Use these tools to look up the scripting API, then author a clean item JSON (get_item_schema / generate_item_template), validate it (validate_item), and tell the user to drop it in plugins/ItemsCore/imports/ and run /ic import <file>. Items authored this way stay editable in the in-game GUI." +
+        "ItemsCore is a Minecraft (Bukkit/Spigot) plugin that lets server owners build custom RPG items with no Java. Use these tools to look up the scripting API, then author a clean item JSON (get_item_schema / generate_item_template) and validate it (validate_item). IMPORTANT: save the file with a .import extension, for example flame_sword.import - never .item (.item is the plugin's own saved-item format, the user must not author that). Tell the user to drop the .import file in plugins/ItemsCore/imports/ and run /ic import <name>. To change an item that is already imported, build the updated JSON with the SAME name and import it again - it overwrites the existing item and keeps its stats and recipe (run /ic export <name> first to get the current JSON if you do not have it). Items authored this way stay editable in the in-game GUI." +
         (idx.isBundled
           ? " (Using the bundled API snapshot. To match this server's exact API including addon methods, run /ic exportapi and point this server at the generated plugins/ItemsCore/itemscore-api.json via --manifest or the ITEMSCORE_API env var.)"
           : " (Using the live API manifest at " + idx.source + ".)"),
@@ -106,7 +106,7 @@ async function main() {
     {
       title: "Validate an ItemsCore item",
       description:
-        "Validate a clean item JSON object against the ItemsCore schema. Reports errors (must fix) and warnings (likely fine). Run this before giving the user a .import file.",
+        "Validate a clean item JSON object against the ItemsCore schema (unknown methods, wrong argument count, wrong argument order/type). Reports errors (must fix) and warnings (likely fine). Run this before saving. Save the result as a .import file (for example flame_sword.import), never .item.",
       inputSchema: { item: z.unknown().describe("The clean item JSON object to validate") },
     },
     async ({ item }) => jsonResult(M.validateItem(idx, item))

package/lib/manifest.js

@@ -289,6 +289,33 @@ function validateItem(idx, item) {
     }
   }
 
+  if (item.events !== undefined && item.customEvents === undefined) {
+    warnings.push('the custom-event field is named "customEvents", not "events"; rename it so the plugin reads it')
+  }
+
+  if (item.customEvents !== undefined) {
+    if (!Array.isArray(item.customEvents)) errors.push("customEvents must be an array")
+    else {
+      item.customEvents.forEach((ce, ci) => {
+        const cp = "customEvents[" + ci + "]"
+        if (typeof ce !== "object" || ce === null) {
+          errors.push(cp + " must be an object")
+          return
+        }
+        if (typeof ce.event !== "string" || ce.event.length === 0) {
+          errors.push(cp + '.event is required and must be a full Bukkit event class name, e.g. "org.bukkit.event.block.BlockBreakEvent"')
+        } else if (!ce.event.includes(".")) {
+          warnings.push(cp + '.event "' + ce.event + '" should be a fully-qualified class name like org.bukkit.event.block.BlockBreakEvent')
+        }
+        if (ce.cooldown !== undefined && typeof ce.cooldown !== "string" && typeof ce.cooldown !== "number") {
+          warnings.push(cp + '.cooldown should be a duration like "5s", "1m", "1h" or a number of seconds')
+        }
+        if (!Array.isArray(ce.steps)) errors.push(cp + ".steps must be an array")
+        else ce.steps.forEach((s, si) => validateStep(idx, s, cp + ".steps[" + si + "]", errors, warnings))
+      })
+    }
+  }
+
   if (item.stats !== undefined && !Array.isArray(item.stats)) errors.push("stats must be an array when present")
   if (item.lore !== undefined && !Array.isArray(item.lore)) errors.push("lore must be an array of strings when present")
   if (item.enchantments !== undefined && !Array.isArray(item.enchantments)) errors.push("enchantments must be an array when present")
@@ -314,8 +341,15 @@ function itemSchema(idx) {
       customModelData: "number",
       skullOwner: "string - player name for PLAYER_HEAD skins",
       stats: "object[] - stat modifiers (see editor)",
-      actions: "Action[] - the behavior graph",
-      events: "object[] - custom event definitions",
+      actions: "Action[] - the built-in trigger behavior graph",
+      customEvents: "object[] - react to ANY Bukkit event by its full class name (see customEvent)",
+    },
+    customEvent: {
+      event:
+        'string (required) - the FULL Bukkit event class name, e.g. "org.bukkit.event.block.BlockBreakEvent", "org.bukkit.event.entity.EntityDeathEvent". The plugin checks it exists on import.',
+      cooldown: "optional - per-player reuse delay, same format as an action cooldown",
+      steps:
+        "Step[] - same step format as an action. Variables available: player (the player from the event), item, event (the fired Bukkit event), plus core/particles/values/api.",
     },
     action: {
       trigger: "string (required) - one of: " + idx.TRIGGER_NAMES.join(", "),
@@ -354,7 +388,7 @@ function generateItemTemplate(kind) {
       actions: [
         { trigger: "rightAction", needBlock: "BOTH", steps: [{ call: "core.broadcastMessage", args: ["A wand was cast!"], operatorToNext: "END" }] },
       ],
-      events: [],
+      customEvents: [],
     }
   }
   return {
@@ -369,7 +403,7 @@ function generateItemTemplate(kind) {
     actions: [
       { trigger: "leftAction", needBlock: "BOTH", steps: [{ call: "core.broadcastMessage", args: ["Hello from my custom sword!"], operatorToNext: "END" }] },
     ],
-    events: [],
+    customEvents: [],
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itemscore-helper",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "One command sets up any AI (Claude, Codex, Cursor, Gemini, and others) to build and edit custom Minecraft items for the ItemsCore plugin. Auto-detects your AI tools and connects a local MCP server that runs entirely on your machine.",
   "bin": {
     "itemscore-helper": "bin/cli.js",

package/skill/ITEM_FORMAT.md

@@ -18,8 +18,8 @@ This is the offline reference for the item format ItemsCore imports. When the li
 | `customModelData` | number | Resource-pack model id |
 | `skullOwner` | string | Player name, for `PLAYER_HEAD` skins |
 | `stats` | object[] | Stat modifiers (authored in the editor; preserved on re-import) |
-| `actions` | Action[] | The behavior graph (see below) |
-| `events` | object[] | Custom event definitions |
+| `actions` | Action[] | The built-in trigger behavior graph (see below) |
+| `customEvents` | object[] | React to ANY Bukkit event by its full class name (see Custom events) |
 
 ## Action
 
@@ -112,6 +112,29 @@ For most items, every step uses `END`. Operators other than `END` build a single
 | `landLocation` | arrowLandAction |
 | `lastLocation` | projectile hit events |
 
+## Custom events
+
+`actions` only cover the built-in triggers above. To react to ANY other Bukkit event, add a `customEvents` entry with the event's full class name. The plugin checks the class exists on import and blocks the import if it does not.
+
+```json
+"customEvents": [
+  {
+    "event": "org.bukkit.event.block.BlockBreakEvent",
+    "steps": [
+      { "call": "core.sendColorMessage", "args": [ { "var": "player" }, "&aYou broke a block while holding this!" ], "operatorToNext": "END" }
+    ]
+  }
+]
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `event` | string, required | The FULL Bukkit event class, e.g. `org.bukkit.event.block.BlockBreakEvent`, `org.bukkit.event.entity.EntityDeathEvent`, `org.bukkit.event.player.PlayerInteractEvent` |
+| `cooldown` | duration string | Optional, same format as an action cooldown |
+| `steps` | Step[] | Same step format as an action (below) |
+
+Variables in a custom event step: `player` (the player the plugin finds on the event), `item`, `event` (the fired event itself - read its data with calls like `{ "call": "event.getBlock", "args": [] }`), plus `core` / `particles` / `values` / `api`. A custom event only fires while the player has the item (held, worn, or anywhere in the inventory for talismans). Use the exact class name; do not guess the package.
+
 ## Bukkit objects expose their full Spigot API
 
 `player`, `shooter`, `victim`, `arrow`, `event`, and any entity, block, world, location, or `ItemStack` returned by a method are real Bukkit/Spigot objects. You can call any standard Spigot method on them in a step, not only the ItemsCore methods:
@@ -160,7 +183,7 @@ Always confirm a method's exact name and parameters with `get_method` / `search_
       ]
     }
   ],
-  "events": []
+  "customEvents": []
 }
 ```
 
@@ -184,7 +207,7 @@ Always confirm a method's exact name and parameters with `get_method` / `search_
       ]
     }
   ],
-  "events": []
+  "customEvents": []
 }
 ```
 

package/skill/SKILL.md

@@ -53,7 +53,7 @@ Minimal shape:
       ]
     }
   ],
-  "events": []
+  "customEvents": []
 }
 ```
 
@@ -64,6 +64,7 @@ Rules:
 - Each step has a `call`, an `args` array, and `operatorToNext`. `call` is `core.method`, `particles.method`, a Bukkit call like `player.getLocation`, or a bare variable name to read it.
 - An arg is a JSON literal, `{ "var": "player" }` to pass a variable, or a nested `{ "call": ..., "args": ... }` to pass one method's result into another.
 - `operatorToNext` joins a step to the next one. Use `END` to end a statement. Other values (`ADD`, `EQUALS`, `AND`, ...) build expressions and conditions. See `ITEM_FORMAT.md`.
+- `actions` only cover the built-in triggers. To react to any OTHER Bukkit event, add a `customEvents` entry with the event's full class name (e.g. `org.bukkit.event.block.BlockBreakEvent`) and the same `steps` format - variables are `player`, `item`, `event`. The import is blocked if the class name is not found on the server, so use the exact fully-qualified name.
 
 Find the exact method you need with `search_methods` / `get_method` before using it. Do not invent method names.
 
@@ -86,17 +87,18 @@ Run `validate_item` on your JSON. Fix every entry under `errors` before continui
 
 ## Step 4: Hand it to the user
 
-1. Save the JSON as `<name>.import` (or `<name>.json`).
+1. Save the JSON with a `.import` extension, for example `flame_sword.import`. **Always use `.import`, never `.item`.** `.item` is the plugin's own internal saved-item format - if you name the file `.item` the user will be confused and the import flow will not pick it up correctly. (The file is plain JSON; the `.import` extension just marks that it belongs in the imports folder.)
 2. Tell the user to put the file in `plugins/ItemsCore/imports/` on their server.
 3. Tell them to run `/ic import <name>` in-game.
 
 On success the plugin replies: `Imported <name> (N action(s)). It is now live and GUI-editable.` The item is immediately usable and can be opened in the editor with `/itemeditor <name>`.
 
-## Editing an existing item
+## Editing an item that is already imported
 
-1. User runs `/ic export <name>` in-game. The plugin writes `plugins/ItemsCore/exports/<name>.json`.
-2. User shares that file with you. Edit the clean JSON.
-3. Validate, then re-import the same way. Importing by the same `name` updates the item and preserves its stats, recipe, and attributes.
+Items are identified by their `name`. **To change an item that already exists, do not start over - update it in place:**
+
+- **Behavior / actions (abilities, particles, projectiles, stats):** build the updated clean JSON with the **same `name`** and import it again exactly like a new item (save as `<name>.import`, `/ic import <name>`). Importing over an existing name **overwrites** the item and keeps its stats, recipe, and attributes. If you do not already have the item's JSON, have the user run `/ic export <name>` first - the plugin writes `plugins/ItemsCore/exports/<name>.json`, which you edit and re-import. Do **not** hand-edit the stored `plugins/ItemsCore/items/<name>.item` file for behavior changes: its `code` and `actions` are machine-encoded (strings as char codes, shared YAML anchors) and editing them by hand will corrupt the item.
+- **Cosmetic only (display name, lore, material, custom model data, skull owner):** these top fields *are* plain text in the stored item file. You may edit `plugins/ItemsCore/items/<name>.item` directly and tell the user to run `/ic reload <name>` to apply it. For anything touching `code` or `actions`, use the re-import flow above instead.
 
 If the item is a **legacy code-only item** (made before this format, so the editor cannot open it), have the user run `/ic adopt <name>` first. That converts its code into GUI actions; then export, edit, and re-import as above.