itemscore-helper 1.2.0 → 1.2.1

package/README.md

@@ -2,15 +2,24 @@
 
 Set up **any** AI assistant to build and edit custom Minecraft items for the [ItemsCore](https://www.coredevelopment.shop/plugins/itemscore) plugin. Works with Claude, Codex, Cursor, Gemini, and anything else that supports MCP or custom instructions. You do not need to know how to code.
 
-## Easiest: let your AI set itself up
+## Easiest: paste one prompt into your AI
 
-Run this, copy what it prints, and paste it into your AI (Claude, Cursor, Gemini, Codex, anything):
+Copy the prompt below and paste it into your AI (Claude, Cursor, Gemini, Codex, anything). It downloads and connects the ItemsCore tools itself, then asks what item you want - no terminal knowledge needed:
 
-```bash
-npx itemscore-helper prompt
+```text
+You are my coding agent and I do not know how to code, so do the whole setup yourself - actually run the commands, do not just tell me what to run.
+
+1. In my project folder, run this to download and connect the ItemsCore tools:
+   npx -y itemscore-helper install
+   It installs a local helper and wires an "itemscore" MCP server into this project. When it finishes, reload your MCP servers (or ask me to restart this app) so the itemscore tools load. If you truly cannot run commands, add this to your MCP config instead:
+   {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}
+
+2. Read https://www.coredevelopment.shop/llms.txt 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.
 ```
 
-Your AI reads the prompt, sets up the ItemsCore tools itself, then asks what item you want. No config files, no terminal knowledge needed.
+The same prompt is on the [docs page](https://www.coredevelopment.shop/docs/itemscore) with a one-click Copy button.
 
 ## Or set it up in one command
 
@@ -32,7 +41,6 @@ The MCP server is `npx -y itemscore-helper serve`. It speaks the standard stdio
 | Command | What it does |
 |---|---|
 | `npx itemscore-helper` | Auto-detect your AI tools and connect the local MCP server |
-| `npx itemscore-helper prompt` | Print a prompt to paste into your AI so it sets itself up |
 | `npx itemscore-helper --dry-run` | Show what would change, without writing anything |
 | `npx itemscore-helper serve` | Run the local MCP server (this is what your AI runs) |
 | `npx itemscore-helper print` | Print the skill instructions to stdout |
@@ -81,7 +89,7 @@ After connecting, give your AI the `SKILL.md` file as its instructions (paste it
 ## How you use it
 
 1. Ask your AI for an item.
-2. It writes a small `.item` (JSON) file and validates it.
+2. It writes a small `.import` (JSON) file and validates it.
 3. Put that file in `plugins/ItemsCore/imports/` on your server.
 4. Run `/ic import <name>` in-game. The item is live and stays editable in the in-game editor.
 

package/bin/cli.js

@@ -11,16 +11,16 @@ const DOCS_URL = "https://www.coredevelopment.shop/docs/itemscore"
 const SKILL_DIR = path.join(__dirname, "..", "skill")
 
 const SETUP_PROMPT = [
-  "Help me build a custom item for my Minecraft server with the ItemsCore plugin. Set yourself up first, then we'll build it together.",
+  "You are my coding agent and I do not know how to code, so do the whole setup yourself - actually run the commands, do not just tell me what to run.",
   "",
-  "1. Fetch and read " + LLMS_URL + " - it explains how ItemsCore items work, the item JSON format, and every method you can use.",
-  "",
-  "2. Set up the ItemsCore tools so you can look up methods and validate items for me. In my project folder, run:",
+  "1. In my project folder, run this to download and connect the ItemsCore tools:",
   "   npx -y itemscore-helper install",
-  '   Then reload your MCP servers (or restart this app) so the "itemscore" tools appear. If you cannot run commands, add this to your MCP config instead:',
+  '   It installs a local helper and wires an "itemscore" MCP server into this project. When it finishes, reload your MCP servers (or ask me to restart this app) so the itemscore tools load. If you truly cannot run commands, add this to your MCP config instead:',
   '   {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}',
   "",
-  "3. Once you are set up, tell me you are ready and ask what item I want. Write a valid .item file, validate it, then tell me to drop it in plugins/ItemsCore/imports/ and run /ic import. The item stays fully editable in the in-game editor.",
+  "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.",
 ].join("\n")
 
 function copyDir(src, dest) {
@@ -52,14 +52,13 @@ function printHelp() {
     "",
     "Usage",
     "  npx itemscore-helper            Auto-detect your AI tools and connect the local MCP server",
-    "  npx itemscore-helper prompt     Print a prompt to paste into your AI so it sets itself up",
     "  npx itemscore-helper --dry-run  Show what would be changed, without writing anything",
     "  npx itemscore-helper serve      Run the local MCP server (this is what your AI runs)",
     "  npx itemscore-helper print      Print the skill instructions (SKILL.md) to stdout",
     "  npx itemscore-helper mcp        Print the MCP server config",
     "  npx itemscore-helper help       Show this help",
     "",
-    "Zero terminal? Run `npx itemscore-helper prompt`, copy it, and paste it into your AI - it sets itself up.",
+    "Don't want to use a terminal? Copy the setup prompt from " + DOCS_URL + " and paste it into your AI - it does the rest.",
     "Supports Claude (Code & Desktop), Cursor, Gemini CLI, Codex, Windsurf and any MCP client.",
     "Docs: " + DOCS_URL,
     "",
@@ -76,10 +75,6 @@ function printSkill() {
   process.stdout.write(fs.readFileSync(path.join(SKILL_DIR, "SKILL.md"), "utf8"))
 }
 
-function printPrompt() {
-  console.log(SETUP_PROMPT)
-}
-
 function manualLines() {
   return [
     "  Add this to your AI client's MCP config (same for Claude, Cursor, Gemini):",
@@ -139,7 +134,6 @@ function main() {
   }
   if (args.cmd === "help") return printHelp()
   if (args.cmd === "mcp") return printMcp()
-  if (args.cmd === "prompt") return printPrompt()
   if (args.cmd === "print") return printSkill()
   if (args.cmd !== "install") {
     console.error("Unknown command: " + args.cmd + "\nRun: npx itemscore-helper help")

package/bin/mcp.js

@@ -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 .item file.",
+        "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.",
       inputSchema: { item: z.unknown().describe("The clean item JSON object to validate") },
     },
     async ({ item }) => jsonResult(M.validateItem(idx, item))

package/data/itemscore-api.json

@@ -352,7 +352,7 @@
           "returnsValue": true,
           "useless": false,
           "documented": true,
-          "description": "Builds a movement equation (using 't' for time) used to shape custom projectile paths.",
+          "description": "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.",
           "category": "Projectiles",
           "example": "core.createEquationVector(\"cos(t)\", \"0\", \"sin(t)\")"
         },
@@ -2509,7 +2509,7 @@
           "returnsValue": false,
           "useless": false,
           "documented": true,
-          "description": "Fires a custom ItemsCore projectile from a player, following the given path equation for a set number of ticks.",
+          "description": "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.",
           "category": "Projectiles",
           "example": "core.shootProjectile(player, player.getEyeLocation(), \"FIREBALL\", null, 60, true, core.createEquationVector(\"t\", \"0\", \"t\"))"
         },

package/lib/manifest.js

@@ -88,6 +88,123 @@ function getMethod(idx, name, binding) {
   return out
 }
 
+const NUMERIC_TYPES = new Set([
+  "int", "long", "double", "float", "short", "byte",
+  "Integer", "Long", "Double", "Float", "Short", "Byte", "Number",
+])
+
+// Object types that cause a hard ClassCastException when mismatched (cannot be coerced at runtime).
+// Mismatching any of these against each other, or against a primitive/literal, is a real bug.
+const HARD_OBJECT_TYPES = new Set(["Location", "ParticleDisplay", "Vector", "World"])
+
+// Return types of the few bukkit getters agents use constantly. Lets us catch a swap even when one
+// side is a raw Spigot call (e.g. player.getLocation()) that is not in the manifest.
+const BUKKIT_GETTER_RETURNS = {
+  getlocation: "Location",
+  geteyelocation: "Location",
+  getworld: "World",
+  getdirection: "Vector",
+  getvelocity: "Vector",
+}
+
+// A handful of action variables whose type we know for sure.
+const KNOWN_VARIABLE_TYPES = {
+  landlocation: "Location",
+  lastlocation: "Location",
+}
+
+function simpleType(t) {
+  if (!t) return ""
+  const dot = t.lastIndexOf(".")
+  return dot >= 0 ? t.slice(dot + 1) : t
+}
+
+// Returns a description of what an argument produces, as { kind, type? }.
+// kind is one of: "unknown", "string", "number", "boolean", "type".
+function producedType(idx, arg) {
+  if (arg === null) return { kind: "unknown" }
+  if (typeof arg === "string") return { kind: "string" }
+  if (typeof arg === "number") return { kind: "number" }
+  if (typeof arg === "boolean") return { kind: "boolean" }
+  if (typeof arg !== "object") return { kind: "unknown" }
+
+  if (typeof arg.var === "string") {
+    const known = KNOWN_VARIABLE_TYPES[arg.var.toLowerCase()]
+    return known ? asProduced(known) : { kind: "unknown" }
+  }
+  if (typeof arg.call === "string") {
+    const call = arg.call
+    if (call.includes(".")) {
+      const receiver = call.slice(0, call.indexOf("."))
+      const method = call.slice(call.indexOf(".") + 1)
+      if (idx.BINDING_NAMES.includes(receiver)) {
+        const found = getMethod(idx, method, receiver)
+        if (found.length === 1 && found[0].returns && found[0].returns !== "void") {
+          return asProduced(found[0].returns)
+        }
+        return { kind: "unknown" }
+      }
+      const getter = BUKKIT_GETTER_RETURNS[method.toLowerCase()]
+      return getter ? asProduced(getter) : { kind: "unknown" }
+    }
+    return { kind: "unknown" }
+  }
+  return { kind: "unknown" }
+}
+
+function asProduced(simpleName) {
+  const s = simpleType(simpleName)
+  if (NUMERIC_TYPES.has(s)) return { kind: "number" }
+  if (s === "boolean" || s === "Boolean") return { kind: "boolean" }
+  if (s === "String" || s === "CharSequence") return { kind: "string" }
+  return { kind: "type", type: s }
+}
+
+// Conservative: returns true unless the arg is a definite, uncoercible mismatch.
+function argCompatible(expectedRaw, produced) {
+  const expected = simpleType(expectedRaw)
+  if (!expected || expected === "Object") return true
+  if (produced.kind === "unknown") return true
+
+  if (expected === "String" || expected === "CharSequence") return true
+  if (NUMERIC_TYPES.has(expected)) {
+    if (produced.kind === "type") return NUMERIC_TYPES.has(produced.type)
+    return true
+  }
+  if (expected === "boolean" || expected === "Boolean") {
+    if (produced.kind === "type") return false
+    return true
+  }
+  if (HARD_OBJECT_TYPES.has(expected)) {
+    if (produced.kind === "type") return produced.type === expected || !HARD_OBJECT_TYPES.has(produced.type)
+    return false
+  }
+  return true
+}
+
+function describeProduced(produced) {
+  if (produced.kind === "type") return produced.type
+  if (produced.kind === "string") return "string"
+  if (produced.kind === "number") return "number"
+  if (produced.kind === "boolean") return "boolean"
+  return "value"
+}
+
+function validateArgs(idx, method, args, p, errors) {
+  if (!method || !Array.isArray(method.params) || !Array.isArray(args)) return
+  for (let i = 0; i < args.length && i < method.params.length; i++) {
+    const param = method.params[i]
+    const expected = param.type || param.jvmType
+    const produced = producedType(idx, args[i])
+    if (!argCompatible(expected, produced)) {
+      errors.push(
+        p + '.args[' + i + '] (parameter "' + param.name + '") expects ' + simpleType(expected) +
+        " but a " + describeProduced(produced) + " was passed. Check the argument order against the method signature: " + method.signature
+      )
+    }
+  }
+}
+
 function validateStep(idx, step, p, errors, warnings) {
   if (typeof step !== "object" || step === null) {
     errors.push(p + " must be an object")
@@ -105,8 +222,14 @@ function validateStep(idx, step, p, errors, warnings) {
       const found = getMethod(idx, method, receiver)
       if (found.length === 0) {
         errors.push(p + '.call "' + call + '" references unknown method "' + method + '" on binding "' + receiver + '"')
-      } else if (found[0].useless) {
-        warnings.push(p + '.call "' + call + '" is flagged useless (no real effect)')
+      } else {
+        if (found[0].useless) {
+          warnings.push(p + '.call "' + call + '" is flagged useless (no real effect)')
+        }
+        // Only type-check when the method is unambiguous (one overload) so we never guess wrong.
+        if (found.length === 1 && Array.isArray(step.args)) {
+          validateArgs(idx, found[0], step.args, p, errors)
+        }
       }
     } else if (!idx.KNOWN_RECEIVERS.has(receiver)) {
       warnings.push(p + '.call receiver "' + receiver + '" is not a known variable; make sure it is defined earlier or exists at runtime')
@@ -144,6 +267,9 @@ function validateItem(idx, item) {
         if (action.needBlock !== undefined && (typeof action.needBlock !== "string" || !NEED_BLOCK_VALUES.includes(action.needBlock))) {
           errors.push(ap + ".needBlock must be one of " + NEED_BLOCK_VALUES.join(", "))
         }
+        if (action.cooldown !== undefined && typeof action.cooldown !== "string" && typeof action.cooldown !== "number") {
+          warnings.push(ap + '.cooldown should be a duration like "5s", "1m", "1h" or a number of seconds')
+        }
         if (!Array.isArray(action.steps)) errors.push(ap + ".steps must be an array")
         else action.steps.forEach((s, si) => validateStep(idx, s, ap + ".steps[" + si + "]", errors, warnings))
       })
@@ -181,6 +307,7 @@ function itemSchema(idx) {
     action: {
       trigger: "string (required) - one of: " + idx.TRIGGER_NAMES.join(", "),
       needBlock: "BOTH | AIR | BLOCK - optional per-action override",
+      cooldown: 'optional - per-player reuse delay for this action. Any duration: a number plus a unit s/m/h, e.g. "5s", "45s", "2m", "90s", "1h" (a bare number means seconds). Omit or "0" for no cooldown.',
       steps: "Step[] - executed in order, combined by operatorToNext",
     },
     step: {
@@ -193,6 +320,8 @@ function itemSchema(idx) {
     },
     bukkitObjects:
       "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 (for example player.sendMessage, player.getHealth, player.getWorld, victim.setFireTicks), not only the ItemsCore methods. These are not in the method list below; see https://hub.spigotmc.org/javadocs/spigot/ for the full Spigot API. Prefer a core method when one exists.",
+    projectiles:
+      'For core.shootProjectile + core.createEquationVector the equation axes are relative to where the player looks: X = forward, Y = up, Z = left. A straight forward-flying projectile puts the motion on X, e.g. core.createEquationVector("t * 0.4", "0", "0"). Use Y for arc/gravity and Z to curve sideways.',
     bindings: idx.bindings.map((b) => ({ name: b.name, description: b.description || "", methodCount: (b.methods || []).length })),
     variables: idx.variables,
     triggers: idx.triggers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itemscore-helper",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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",
@@ -31,7 +31,7 @@
   "homepage": "https://www.coredevelopment.shop/docs/itemscore",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Tc554/itemscore-helper.git"
+    "url": "https://github.com/Core-Pluginss/ItemsCore-Helper.git"
   },
   "license": "MIT",
   "author": "TastyCake",

package/skill/ITEM_FORMAT.md

@@ -31,6 +31,7 @@ This is the offline reference for the item format ItemsCore imports. When the li
 |---|---|---|
 | `trigger` | string, required | One of the triggers below |
 | `needBlock` | `BOTH` \| `AIR` \| `BLOCK` | Optional per-action override of the item default |
+| `cooldown` | duration string | Optional per-player reuse delay. Any duration: a number plus a unit s/m/h, e.g. `"5s"`, `"45s"`, `"2m"`, `"90s"`, `"1h"` (a bare number means seconds) |
 | `steps` | Step[] | Run in order, combined by each step's `operatorToNext` |
 
 ### Triggers
@@ -131,6 +132,10 @@ These are not in the `core` / `particles` / `values` / `api` method list. For th
 
 Always confirm a method's exact name and parameters with `get_method` / `search_methods` before using it. Do not guess.
 
+## Projectiles
+
+`core.shootProjectile` and `core.createEquationVector` use a movement equation whose axes are relative to where the player looks: **X = forward, Y = up, Z = left**. A straight forward-flying projectile puts the motion on X, e.g. `core.createEquationVector("t * 0.4", "0", "0")`. Use Y for arc/gravity and Z to curve left/right.
+
 ## Worked example: a healing ability wand
 
 ```json

package/skill/SKILL.md

@@ -9,7 +9,7 @@ ItemsCore is a Minecraft (Bukkit/Spigot) plugin that lets a server owner create
 
 ## The one rule that matters
 
-Always produce a **clean item JSON** (the format described below). Never hand-write the plugin's internal `.item` YAML or its generated JavaScript `code`. When the user imports your JSON, the plugin builds **both** the runnable code **and** the in-game GUI action graph from it. That means an item you create this way still works **and** stays fully editable in the in-game editor. Hand-writing raw code produces an item the GUI cannot open, which is exactly the problem this format avoids.
+Always produce a **clean item JSON** (the format described below). Never hand-write the plugin's internal item YAML or its generated JavaScript `code`. When the user imports your JSON, the plugin builds **both** the runnable code **and** the in-game GUI action graph from it. That means an item you create this way still works **and** stays fully editable in the in-game editor. Hand-writing raw code produces an item the GUI cannot open, which is exactly the problem this format avoids.
 
 ## Step 1: Get the API (do this first)
 
@@ -86,7 +86,7 @@ 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>.item` (or `<name>.json`).
+1. Save the JSON as `<name>.import` (or `<name>.json`).
 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.