itemscore-helper 1.2.3 → 1.3.0

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.3",
+  "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.