itemscore-helper 1.2.2 → 1.2.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itemscore-helper",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "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/SKILL.md

@@ -86,17 +86,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.