incanto 0.33.0 → 0.35.0

package/editor/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-BWCudoz1.js"></script>
+    <script type="module" crossorigin src="./assets/index-CMlKFT0C.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -325,6 +325,9 @@
         {
           "$ref": "#/$defs/UiImage"
         },
+        {
+          "$ref": "#/$defs/UiLanguageSelect"
+        },
         {
           "$ref": "#/$defs/UiPanel"
         },
@@ -1202,6 +1205,7 @@
             },
             "target": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             },
             "bone": {
@@ -1308,6 +1312,7 @@
             },
             "target": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             },
             "bone": {
@@ -1316,6 +1321,7 @@
             },
             "lookAt": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             },
             "maxAngleDeg": {
@@ -1423,6 +1429,7 @@
             },
             "follow": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             },
             "smoothing": {
@@ -2076,6 +2083,7 @@
             },
             "skinPath": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": "../Skin"
             },
             "skinYawOffset": {
@@ -2469,6 +2477,7 @@
             },
             "terrain": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             }
           },
@@ -2663,6 +2672,7 @@
             },
             "terrain": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             }
           },
@@ -2723,6 +2733,10 @@
             "visible": {
               "type": "boolean",
               "default": true
+            },
+            "focusNavigation": {
+              "type": "boolean",
+              "default": false
             }
           },
           "additionalProperties": false
@@ -2952,6 +2966,7 @@
             },
             "target": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             },
             "anchor": {
@@ -3089,6 +3104,7 @@
             },
             "target": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             },
             "anchor": {
@@ -4869,6 +4885,7 @@
             },
             "terrain": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             },
             "carve": {
@@ -5990,6 +6007,7 @@
             },
             "terrain": {
               "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
               "default": ""
             }
           },
@@ -6087,7 +6105,7 @@
     },
     "UiBanner": {
       "type": "object",
-      "x-signals": ["bannerShown"],
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "bannerShown"],
       "properties": {
         "name": {
           "type": "string"
@@ -6129,6 +6147,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": false
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "size": {
               "type": "number",
               "default": 42
@@ -6166,6 +6196,7 @@
     },
     "UiBar": {
       "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped"],
       "properties": {
         "name": {
           "type": "string"
@@ -6207,6 +6238,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": false
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "value": {
               "type": "number",
               "default": 100
@@ -6272,7 +6315,7 @@
     },
     "UiButton": {
       "type": "object",
-      "x-signals": ["pressed"],
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "pressed"],
       "properties": {
         "name": {
           "type": "string"
@@ -6314,6 +6357,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "text": {
               "type": "string",
               "default": "OK"
@@ -6363,7 +6418,15 @@
     },
     "UiDialogue": {
       "type": "object",
-      "x-signals": ["lineShown", "choiceMade", "dialogueFinished"],
+      "x-signals": [
+        "dragStarted",
+        "dragCancelled",
+        "droppedOn",
+        "dropped",
+        "lineShown",
+        "choiceMade",
+        "dialogueFinished"
+      ],
       "properties": {
         "name": {
           "type": "string"
@@ -6405,6 +6468,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": false
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "charsPerSecond": {
               "type": "number",
               "default": 40
@@ -6442,6 +6517,7 @@
     },
     "UiImage": {
       "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped"],
       "properties": {
         "name": {
           "type": "string"
@@ -6483,6 +6559,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": false
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "src": {
               "type": "string",
               "default": ""
@@ -6535,8 +6623,104 @@
       },
       "required": ["name", "type"]
     },
+    "UiLanguageSelect": {
+      "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiLanguageSelect"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "topLeft"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
+            "label": {
+              "type": "string",
+              "default": "Language"
+            },
+            "options": {
+              "type": "string",
+              "default": ""
+            },
+            "value": {
+              "type": "string",
+              "default": ""
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "UiPanel": {
       "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped"],
       "properties": {
         "name": {
           "type": "string"
@@ -6578,6 +6762,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": false
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "layout": {
               "type": "string",
               "enum": ["column", "row", "grid"],
@@ -6644,7 +6840,7 @@
     },
     "UiSelect": {
       "type": "object",
-      "x-signals": ["changed"],
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
       "properties": {
         "name": {
           "type": "string"
@@ -6686,6 +6882,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "label": {
               "type": "string",
               "default": ""
@@ -6727,7 +6935,7 @@
     },
     "UiSlider": {
       "type": "object",
-      "x-signals": ["changed"],
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
       "properties": {
         "name": {
           "type": "string"
@@ -6769,6 +6977,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "label": {
               "type": "string",
               "default": ""
@@ -6826,6 +7046,7 @@
     },
     "UiText": {
       "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped"],
       "properties": {
         "name": {
           "type": "string"
@@ -6867,6 +7088,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": false
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "text": {
               "type": "string",
               "default": ""
@@ -6912,7 +7145,7 @@
     },
     "UiToggle": {
       "type": "object",
-      "x-signals": ["changed"],
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
       "properties": {
         "name": {
           "type": "string"
@@ -6954,6 +7187,18 @@
               "type": "boolean",
               "default": true
             },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
             "label": {
               "type": "string",
               "default": ""

package/skills/incanto-assets.md

@@ -129,3 +129,24 @@ scene built that way stays plain JSON you can also hand-write.
 
 Swap in real art later by changing ONLY the `assets{}` entry — node props
 stay untouched.
+
+
+## Textures are shared automatically (3D)
+
+A hundred `Sprite3D`s pointing at one atlas cost **one** fetch, one decode and
+one GPU upload. The renderer's asset store keys textures by URL plus their
+sampler settings, so you never need to hoist a texture yourself or worry that
+spawning enemies re-downloads their sheet.
+
+Two consequences worth knowing:
+
+- **Do not mutate a texture you got from a node.** `Sprite3D` and `Terrain3D`
+  hold the shared master. The two nodes with per-node UV state
+  (`AnimatedSprite3D`'s frame window, `MeshInstance3D`'s `material.repeat`) get
+  a private clone automatically — you do not have to ask for it.
+- **`pixelArt: true` also turns mipmaps off**, which is what makes pixel art stay
+  crisp at distance instead of blurring into mud.
+
+A texture that 404s now shows up in `game.assetErrors()` alongside models, by the
+URL you wrote — so "why is my sprite invisible" is answerable without opening the
+network tab.

package/skills/incanto-behaviors-and-scripts.md

@@ -38,6 +38,22 @@ class CoinCounter extends Behavior {
 registerBehavior('CoinCounter', CoinCounter);  // EXPLICIT — before loadScene
 ```
 
+**A behavior that holds progress should be able to save it.** `serialize()` /
+`deserialize(data)` are two more optional hooks in the same list, and they are
+what makes "continue where you left off" possible — see
+`incanto-save-slots.md`. Save only what a fresh `onReady` could not recreate.
+
+**A prop that holds a node path must say so.** Mark it `nodePath: true` and the
+editor rewrites it when the target is renamed; leave it off and the rename
+silently breaks the link (`getNodeOrNull` returns null, nothing throws).
+
+```ts
+static readonly props = {
+  target: { default: '', nodePath: true },   // fed to getNode/getNodeOrNull
+  damage: { default: 10 },
+};
+```
+
 ## The three-artifact contract (keep them in sync!)
 
 1. scene JSON `"script": {"name": "CoinCounter"}`

package/skills/incanto-editor.md

@@ -81,9 +81,25 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   CharacterBody2D) are ROLLED BACK entirely with the error in the banner; the
   tree never shows a state the engine would reject. Right-click for
   duplicate / rename (or double-click the name) / cut / copy / paste-as-child /
-  delete — all act on the multi-selection. `+` adds a child of any registered
+  delete — all act on the multi-selection. **Rename REPAIRS references**: every
+  `connections[].from/to` and every node-path prop pointing at the node (or into
+  its subtree) is rewritten in the same edit, across all three path forms
+  (`%Unique`, `/root/…`, relative `../Skin`), and the editor reports what it
+  changed. A prop is rewritten only if its type declares `nodePath: true`, so a
+  text prop that merely reads "Player" is never touched. `+` adds a child of any registered
   type, `✕` deletes the selection. Selecting the ⚙ scene row edits the header
   (dimension, gravity with real inputs, environment/input/assets/multiplayer).
+- **CONNECTIONS on the selected node** — the inspector's last section shows what
+  the node **emits** and what it **receives**, each row being signal → target →
+  handler with a ✕ to remove and `+ connect` to add. Signals come from the node
+  type merged with its behavior's `static signals`; the target picker lists every
+  node in the scene; the handler is a dropdown of real methods when the target
+  has no script, and free text when it does (those handlers live in your
+  TypeScript, which the editor never loads). An end that no longer resolves is
+  marked red with the reason. For what a row cannot express — `filter`, `once`,
+  bound args — the scene header still has `connections` as raw JSON.
+  **Validation now runs WITH connections**: the editor used to strip them before
+  loading, so it reported green for a scene the game hard-fails to open.
 - **Viewport with DIRECT MANIPULATION** — a mode toolbar (top left) + the
   Unity/Godot keys: **W move · E rotate · R scale** (active mode highlighted).
   A collider-visibility toggle sits beside the mode tools, and it shows the

package/skills/incanto-gameplay-behaviors.md

@@ -58,6 +58,12 @@ Two kinds of node path resolve from DIFFERENT origins — mixing them up is the
   enemy (a child of the Spawner) reaches the player with the ABSOLUTE
   `/root/Player`, never a bare `Player` (which would look under the enemy).
 
+Renaming a node in the editor now REWRITES both kinds for you (and reports what
+it changed), so the paths above stay valid across a rename. Hand-edited JSON
+still has to be kept in sync yourself — `bunx incanto-check` catches the
+connections, but a behavior prop pointing at a name that no longer exists
+resolves to null in silence.
+
 **Never write `/root/<RootName>/...`.** If your root node is named `Game`, the
 path is `/root/Player` — NOT `/root/Game/Player`: `/root/` already *is* the
 `Game` root, so `/root/Game/...` double-counts it and dangles at load. Likewise

package/skills/incanto-hud.md

@@ -101,7 +101,7 @@ so structure in the tree becomes structure on screen. Panels nest.
     { "name": "Volume", "type": "UiSlider", "props": { "label": "volume", "value": 0.8 } },
     { "name": "Invert", "type": "UiToggle", "props": { "label": "invert Y" } },
     { "name": "Quality", "type": "UiSelect", "props": { "options": "low,medium,high", "value": "high" } },
-    { "name": "Resume", "type": "UiButton", "props": { "label": "Resume" } }
+    { "name": "Resume", "type": "UiButton", "props": { "text": "Resume" } }
   ] }
 ```
 
@@ -121,3 +121,75 @@ widget use `UiButton`'s `pressed`.
 Setting `.value` from a behavior updates the control and does **NOT** re-emit
 `changed` — restoring a saved setting must not fire the handler that saved it.
 
+## Playable on a controller (focus navigation)
+
+A menu you can only click is not playable on a gamepad, and "add controller
+support" was not something a JSON scene could express at all.
+
+```json
+{ "name": "Hud", "type": "HudLayer", "props": { "focusNavigation": true }, "children": [ … ] }
+```
+
+Arrow keys / d-pad move the focus between the **focusable** widgets under that
+layer, `Enter` / `A` activates, and the focused one wears a ring.
+`UiButton`/`UiSlider`/`UiToggle`/`UiSelect` are focusable by default;
+`UiText`/`UiBar`/`UiImage`/`UiPanel` are not, so arrowing never lands on a label.
+
+What activation MEANS is per widget: a button presses, a toggle flips (left/right
+sets it explicitly, which reads better on a pad), a select walks its list, a
+slider nudges by one `step`.
+
+**It is OFF by default**, deliberately: a game whose HUD happens to contain a
+button must not lose its arrow keys the moment one exists. Turn it on for the
+screens that ARE menus and off again when play resumes —
+`hud.focusNavigation = false`. `hud.focus(widget)` sets the starting item, since
+opening a menu should land somewhere rather than nowhere.
+
+The gamepad codes are the ones the engine already produces from a pad
+(`Pad12`–`Pad15` d-pad, `Pad0` = A), so nothing extra is declared.
+
+## Dragging things between slots (inventory)
+
+An inventory is the one screen where "click it" is not enough, and every game
+that wanted one dropped out of scene JSON to hand-roll pointer handlers. Two
+props and four signals, on the widgets you already have — no new node type:
+
+```json
+{ "name": "SlotA", "type": "UiPanel", "props": { "dropTarget": true }, "children": [
+  { "name": "Potion", "type": "UiImage", "props": { "src": "$potion", "draggable": true } }
+] },
+{ "name": "SlotB", "type": "UiPanel", "props": { "dropTarget": true } }
+```
+
+| signal | on | args |
+| --- | --- | --- |
+| `dragStarted` | the dragged widget | itself |
+| `droppedOn` | the dragged widget | the target it landed on |
+| `dropped` | the drop target | the widget that landed |
+| `dragCancelled` | the dragged widget | itself (landed on nothing) |
+
+Both ends are told, because both usually have work to do: the item leaves its old
+slot, the slot takes it. **Who owns the item is your game's business** — these
+report the GESTURE, not a model, so an inventory that stacks, swaps or refuses is
+your `connections` and a behavior, not a prop nobody could have guessed.
+
+A drop on a CHILD of a slot counts as a drop on the slot (the cursor lands on the
+icon inside it, which is the normal case), a drop on nothing cancels, and a
+widget never drops onto itself.
+
+
+
+## More than one language
+
+Any text prop here can name a translation key instead of a literal:
+
+```json
+{ "name": "Score", "type": "UiText", "props": { "text": "@t:hud.score" } }
+```
+
+Strings live in the scene header's `strings` block, English is the base, and a
+key a locale omits falls back to English silently — which is the RIGHT answer
+whenever the English term is more precise or the translation would not fit.
+`UiLanguageSelect` is the picker, already wired.
+
+Read `incanto-localization.md` before adding a second language.