npm - incanto - Versions diffs - 0.69.0 → 0.70.0 - Mend

incanto 0.69.0 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (146) hide show

package/bin/_behaviors-loader.mjs +22 -0
package/bin/_read-json.mjs +28 -0
package/bin/incanto-assets.mjs +5 -4
package/bin/incanto-check.mjs +58 -31
package/bin/incanto-editor.mjs +128 -5
package/bin/incanto-env.mjs +3 -2
package/bin/incanto-feel.mjs +24 -13
package/bin/incanto-frame.mjs +8 -1
package/bin/incanto-multiplay.mjs +11 -9
package/bin/incanto-new.mjs +105 -10
package/bin/incanto-play.mjs +158 -16
package/bin/incanto-playtest.mjs +66 -23
package/bin/incanto-skills.mjs +14 -2
package/bin/incanto-verify.mjs +125 -44
package/bin/incanto.mjs +3 -2
package/dist/2d.d.ts +281 -34
package/dist/2d.js +4 -4
package/dist/3d.d.ts +157 -9
package/dist/3d.js +7 -7
package/dist/{agent8-CvsfVskX.js → agent8-CmNF01gA.js} +61 -8
package/dist/{audio-player-C0j2k-yB.d.ts → audio-player-DaMxqfNE.d.ts} +2 -2
package/dist/{behavior-rm8vVzu_.d.ts → behavior-DZExDn9o.d.ts} +744 -46
package/dist/{create-game-CwxEDlCm.js → create-game-Bwvh6q8A.js} +142 -59
package/dist/{create-game-CvJ1wSRP.js → create-game-C7ffQWW7.js} +97 -47
package/dist/debug.d.ts +1 -1
package/dist/debug.js +2 -3
package/dist/diagnostics-Cu85N3tL.d.ts +12 -0
package/dist/{editor-switch-CnIOiyNJ.d.ts → editor-switch-CFU9mCec.d.ts} +22 -13
package/dist/editor.js +1065 -863
package/dist/env.d.ts +1 -1
package/dist/env.js +5 -3
package/dist/{environment-presets-BO-7XoFV.js → environment-presets-D6Q5BxeE.js} +298 -45
package/dist/{gameplay-D1KixWK8.js → gameplay-BfHkuzVb.js} +809 -211
package/dist/gameplay.d.ts +187 -7
package/dist/gameplay.js +1 -1
package/dist/{heightmap-CRK0M4jT.js → heightmap-BYgD5Edk.js} +1 -1
package/dist/index.d.ts +156 -13
package/dist/index.js +10 -12
package/dist/json-CfTjpvW8.js +67 -0
package/dist/{loader-DadV2QCT.d.ts → loader-Cff09LMm.d.ts} +2 -2
package/dist/net.d.ts +27 -3
package/dist/net.js +2 -2
package/dist/{noise-CGUMx44x.js → noise-D3nPpmFg.js} +1 -1
package/dist/{physics-2d-CF5yyjbj.js → physics-2d-CE0Qvy3V.js} +136 -11
package/dist/{physics-3d-DbYaEcZy.js → physics-3d-CpH-2gn5.js} +104 -23
package/dist/{teardown-CMqFVxO9.js → picking-CQJ_PJKh.js} +103 -12
package/dist/react.d.ts +2 -2
package/dist/react.js +2 -2
package/dist/{register-mmfugpaQ.js → register-6DYnKZcy.js} +546 -817
package/dist/{register-DbVArsns.js → register-Bkk0wSDB.js} +332 -23
package/dist/{replay-BEHLDcQV.js → replay-DjAkAzMq.js} +224 -14
package/dist/{replay-BQfkX4x7.d.ts → replay-Dmw-PKQu.d.ts} +20 -3
package/dist/{schema-B6ugCV1Q.d.ts → rng-Bb-IutXB.d.ts} +38 -21
package/dist/{rng-DP-SR7eg.js → rng-CDOMybym.js} +22 -0
package/dist/{loader-DZE7B07H.js → save-slots-BXVg148r.js} +4570 -2322
package/dist/{split-screen-Cg76MCV5.d.ts → split-screen--k-XpBjr.d.ts} +36 -4
package/dist/{split-screen-CauMwu6y.js → split-screen-PL78oVXP.js} +159 -26
package/dist/{sprite-animation-CY-mrr1L.js → sprite-animation-CqR2o3SA.js} +39 -8
package/dist/{src-CYEu-_S9.js → src-Cxfiv1Hg.js} +2 -17
package/dist/test-iHYVUcDK.js +4036 -0
package/dist/test.d.ts +531 -30
package/dist/test.js +3 -3
package/dist/touch-BnCyPA0G.js +519 -0
package/dist/vite.d.ts +20 -37
package/dist/vite.js +176 -6
package/dist/{webgl-unavailable-Z5_g8x9H.js → webgl-unavailable-C8aDbGmR.js} +44 -0
package/editor/assets/agent8-D0MS174y.js +1 -0
package/editor/assets/{debug-CMULinBW.js → debug-BnXkKuYu.js} +2 -2
package/editor/assets/index-CIu3uc3l.js +11046 -0
package/editor/index.html +1 -1
package/package.json +4 -14
package/schemas/scene.schema.json +30 -3
package/skills/incanto-3d-character.md +14 -1
package/skills/incanto-3d-models.md +12 -0
package/skills/incanto-assets.md +9 -1
package/skills/incanto-audio.md +8 -2
package/skills/incanto-behaviors-and-scripts.md +83 -6
package/skills/incanto-building-2d-games.md +77 -8
package/skills/incanto-building-3d-games.md +58 -4
package/skills/incanto-editor.md +46 -7
package/skills/incanto-environment.md +19 -1
package/skills/incanto-game-feel.md +70 -0
package/skills/incanto-gameplay-behaviors.md +109 -19
package/skills/incanto-hud.md +128 -7
package/skills/incanto-localization.md +13 -5
package/skills/incanto-multiplayer.md +83 -3
package/skills/incanto-node-reference.md +222 -58
package/skills/incanto-performance.md +52 -0
package/skills/incanto-physics-and-input.md +123 -24
package/skills/incanto-playtesting.md +78 -2
package/skills/incanto-save-slots.md +161 -6
package/skills/incanto-scene-json-authoring.md +69 -12
package/skills/incanto-verifying-your-game.md +196 -10
package/skills/incanto-web-integration.md +28 -0
package/skills/incanto-your-first-game.md +3 -1
package/templates-app/beacon-isle-3d/generate-world.ts +77 -9
package/templates-app/beacon-isle-3d/package.json +2 -2
package/templates-app/beacon-isle-3d/src/behaviors.ts +22 -0
package/templates-app/beacon-isle-3d/src/game.scene.json +103 -378
package/templates-app/beacon-isle-3d/src/main.ts +11 -1
package/templates-app/beacon-isle-3d/tsconfig.json +1 -1
package/templates-app/beacon-isle-3d/verify.ts +3 -1
package/templates-app/molehill-2d/.incanto/playtest/lost-seed1.json +4277 -0
package/templates-app/molehill-2d/PROJECT/Context.md +58 -0
package/templates-app/molehill-2d/PROJECT/Requirements.md +39 -0
package/templates-app/molehill-2d/PROJECT/Status.md +27 -0
package/templates-app/molehill-2d/PROJECT/Structure.md +48 -0
package/templates-app/molehill-2d/docs/project-2d-rules.md +44 -0
package/templates-app/molehill-2d/index.html +73 -0
package/templates-app/molehill-2d/package.json +23 -0
package/templates-app/molehill-2d/src/behaviors.ts +198 -0
package/templates-app/molehill-2d/src/game.scene.json +1255 -0
package/templates-app/molehill-2d/src/main.ts +41 -0
package/templates-app/molehill-2d/tsconfig.json +13 -0
package/templates-app/molehill-2d/verify.ts +247 -0
package/templates-app/molehill-2d/vite.config.ts +12 -0
package/templates-app/platformer-2d/package.json +2 -2
package/templates-app/platformer-2d/src/game.scene.json +128 -600
package/templates-app/platformer-2d/src/main.ts +11 -1
package/templates-app/platformer-2d/tsconfig.json +1 -1
package/templates-app/star-survivor/package.json +2 -2
package/templates-app/star-survivor/src/game.scene.json +41 -195
package/templates-app/star-survivor/src/main.ts +11 -1
package/templates-app/star-survivor/tsconfig.json +1 -1
package/templates-app/tps-3d/PROJECT/Context.md +1 -1
package/templates-app/tps-3d/package.json +2 -2
package/templates-app/tps-3d/src/behaviors.ts +19 -1
package/templates-app/tps-3d/src/game.scene.json +78 -217
package/templates-app/tps-3d/src/main.ts +13 -2
package/templates-app/tps-3d/tsconfig.json +1 -1
package/templates-app/village-quest-3d/.incanto/playtest/swapped-seed1.json +1735 -0
package/templates-app/village-quest-3d/package.json +2 -2
package/templates-app/village-quest-3d/src/behaviors.ts +21 -0
package/templates-app/village-quest-3d/src/grove.scene.json +54 -221
package/templates-app/village-quest-3d/src/main.ts +11 -1
package/templates-app/village-quest-3d/src/village.scene.json +199 -838
package/templates-app/village-quest-3d/tsconfig.json +1 -1
package/templates-app/village-quest-3d/verify.ts +14 -1
package/dist/duplicate-Dj4L-5AA.js +0 -22
package/dist/json-CwwhxQgb.js +0 -36
package/dist/registry-CF70EArN.js +0 -212
package/dist/rolldown-runtime-D7D4PA-g.js +0 -13
package/dist/test-D6ISmuFE.js +0 -2383
package/dist/touch-DEAmqGdf.js +0 -225
package/editor/assets/agent8-BDvaZMQJ.js +0 -1
package/editor/assets/index-CZIRr5EL.js +0 -10958

package/editor/index.html CHANGED Viewed

@@ -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-CZIRr5EL.js"></script>
+    <script type="module" crossorigin src="./assets/index-CIu3uc3l.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -55,7 +55,9 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
-    "test": "vitest run --project unit --root ../.."
+    "test": "vitest run --project unit --root ../..",
+    "prepack": "node scripts/strip-dev-deps.mjs",
+    "postpack": "node scripts/strip-dev-deps.mjs --restore"
   },
   "peerDependencies": {
     "@agent8/gameserver": ">=1.10.0",
@@ -70,18 +72,6 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@agent8/gameserver": "1.10.2",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@types/three": "catalog:",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "three": "catalog:",
-    "tsdown": "0.22.2",
-    "typescript": "catalog:",
-    "vitest": "catalog:"
-  },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",

package/schemas/scene.schema.json CHANGED Viewed

@@ -1771,6 +1771,11 @@
             "current": {
               "type": "boolean",
               "default": false
+            },
+            "lookAt": {
+              "type": "string",
+              "description": "A node path: '%UniqueName', '/Absolute/From/Root', or relative to this node ('../Skin').",
+              "default": ""
             }
           },
           "additionalProperties": false
@@ -1903,6 +1908,10 @@
             "slopeLimitDeg": {
               "type": "number",
               "default": 45
+            },
+            "stepHeight": {
+              "type": "number",
+              "default": 35
             }
           },
           "additionalProperties": false
@@ -2800,8 +2809,15 @@
               "default": null
             },
             "density": {
-              "type": "string",
-              "enum": ["lush", "sparse", "none"],
+              "anyOf": [
+                {
+                  "type": "string",
+                  "enum": ["lush", "sparse", "none"]
+                },
+                {
+                  "type": "number"
+                }
+              ],
               "default": "sparse"
             },
             "area": {
@@ -5532,6 +5548,10 @@
               "minItems": 2,
               "maxItems": 2,
               "default": [0, 0]
+            },
+            "angularVelocity": {
+              "type": "number",
+              "default": 0
             }
           },
           "additionalProperties": false
@@ -9442,7 +9462,14 @@
               "default": true
             },
             "underwater": {
-              "type": "boolean",
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "object"
+                }
+              ],
               "default": true
             },
             "swell": {

package/skills/incanto-3d-character.md CHANGED Viewed

@@ -252,7 +252,16 @@ That is the EXACT formula `CharacterController3D` uses for move-facing
 an enemy that idles facing you): use the direction from self TO the target —
 `dx = target.position[0] - self.position[0]`, `dz = target.position[2] - self.position[2]`,
 then `rotation[1] = atan2(dx, dz)*RAD2DEG`. Movement-facing is just this with the
-target being "where I'm walking." There is ONE facing formula; only the direction differs.
+target being "where I'm walking." There is ONE facing formula for anything with a
+SKIN; only the direction differs.
+**NOT a camera.** A `Camera3D` looks down its own local **−Z**, and — more to the
+point — it has an UP that a rod does not. This formula aims a camera perfectly and
+rolls it: over 72 headings, dot 1.000 in all 72 and **upside down in 36**. No
+two-angle recipe can fix it (Euler XYZ makes `[pitch, yaw, 0]` = Rx·Ry, while a
+level camera is Ry·Rx, so its third angle is non-zero). Use
+`Camera3D.lookAt: "%Target"` — a node path, re-aimed every frame with world up.
+See `incanto-building-3d-games.md`.
 - **The 180° is NOT a facing formula.** It is only the AT-REST MOUNT — the character
   starts turned away from the behind-the-shoulder camera until it first moves. Adding
@@ -354,6 +363,10 @@ const rx = Math.atan2(-Dy, Dz);
 t.rotation = [rx*RAD2DEG, ry*RAD2DEG, 0];
 ```
+(This is a ROD: a stretched box has no up, so two angles are enough for it and
+`rodAxis · (target − muzzle) ≈ 1` is a complete check. A camera is not a rod —
+that same check scores 1.000 on an upside-down one. See the Camera3D note above.)
 The "obvious" `[-atan2(dy, hypot(dx,dz)), atan2(dx,dz), 0]` is only correct for a LEVEL
 shot — for XYZ order the yaw denominator must be `hypot(Dy,Dz)`, not the ground `hypot(dx,
 dz)`. With the wrong form the rod skews off-axis when you aim up/down, so its near end

package/skills/incanto-3d-models.md CHANGED Viewed

@@ -76,6 +76,18 @@ meta (name/authors) + humanoid bone count. Decision rules:
   (a center.y of half the height usually means feet at origin: good).
 - **animation names** are exact strings for the `animation` prop.
+**At runtime the node itself will tell you**, which is what a harness or a
+behaviour picking a random idle needs:
+```ts
+model.availableAnimations();   // embedded clip names PLUS the scene's $animation assets
+model.boneNames();             // every bone, for BoneAttachment3D's `bone`
+model.findBone('RightHand');   // the Object3D, matching mixamorig prefixes too
+```
+`availableAnimations` is the one to check before setting `animation` from data:
+a clip name that is not in the list plays nothing and says nothing.
 ## Scene JSON
 ```json

package/skills/incanto-assets.md CHANGED Viewed

@@ -69,7 +69,7 @@ Every catalog entry has a `url` that is directly usable; there are two classes:
   // Tree3D — a bare node already loads oak leaves from the agent8 CDN; override
   // leafTexture only to swap in a different built-in cutout (e.g. ash)
   { "type": "Tree3D", "props": { "type": "broadleaf",
-      "leafTexture": "https://agent8-games.verse8.io/assets/3D/default/textures/vegetation/ash_color.png" } }
+      "leafTexture": "https://agent8-games.verse8.io/assets/3D/default/textures/vegetation/ash_color.png" } },
   // MeshInstance3D material — built-in ground/bark color as a map (+ a normal map)
   { "type": "MeshInstance3D", "props": { "material": {
@@ -238,3 +238,11 @@ node keeps its own texture cache. In **2D** the same question is `renderer.asset
 (`$ref`, url and reason per failed entry), and the scene EDITOR reads it: a
 failed asset is red in the explorer with the url in its tooltip and the
 consequence in its inspector.
+**And a texture INSIDE a model.** A `.gltf` + `.bin` + a missing `textures/`
+folder — the ordinary shape of a Blender "glTF Separate" export or a Sketchfab
+download — used to be the one silent case: GLTFLoader swallows a sub-resource
+failure, so the model resolved as a SUCCESS (`status: 'ready'`, `error: null`,
+empty `assetErrors()`, `stats().errors` 0) and the character simply rendered
+flat white. A half-loaded model was indistinguishable from a whole one. Now the
+missing texture is in `assetErrors()` by its URL, like every other one.

package/skills/incanto-audio.md CHANGED Viewed

@@ -421,7 +421,11 @@ engine.updated.connect(() => {
 ```
 - **`engine.sfx.now`** — seconds on the audio clock, the one the sound is
-  actually placed on. `0` headless and before the first sound.
+  actually placed on. With no AudioContext — headless, and before the first
+  sound — it is the engine's own elapsed real time, so the loop above queues the
+  whole chart in the verify VM exactly as it does in a browser. (It was a frozen
+  `0`, which made that loop queue the first 80 ms of notes and then nothing ever
+  again: 1 of 21 beats, with no error anywhere.)
 - **`AudioPlayer.playAt(when)`** and **`engine.sfx.play(params, gain, { when })`** —
   PRESETS only. A `src` clip goes through an `<audio>` element, which has no
   scheduling clock, so `playAt` on one plays immediately.
@@ -448,7 +452,9 @@ const songSeconds = engine.music.playhead;   // null = nothing playing, or no cl
 ```
 It is the raw element time, so a looping track wraps to 0 each pass — a loop
-boundary to chart against, not a fault.
+boundary to chart against, not a fault. Headless there is no element and no
+duration to wrap at, so it counts up from 0 for as long as the track plays —
+enough for a harness to prove the chart advanced.
 ## Decision guide

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

@@ -50,10 +50,21 @@ silently breaks the link (`getNodeOrNull` returns null, nothing throws).
 ```ts
 static readonly props = {
   target: { default: '', nodePath: true },   // fed to getNode/getNodeOrNull
+  home: { default: '', nodePath: true, required: true },   // and you MUST set it
   damage: { default: 10 },
 };
 ```
+`""` is the "not set" value of a node-path prop, and `getNodeOrNull('')` returns
+`null` for it — so `const t = this.node.getNodeOrNull(this.target)` is safe to
+write without a guard.
+**`required: true` when the prop is not optional.** It turns "left empty" into a
+LOAD error naming the prop and the node (`'script:Archer' needs a "home" — it is
+empty. (at '/Level/Enemies/Slime3')`) instead of a behavior that silently does
+nothing all game. It costs one word and it is the best message the engine has
+for an unset prop.
 ## The three-artifact contract (keep them in sync!)
 1. scene JSON `"script": {"name": "CoinCounter"}`
@@ -75,10 +86,47 @@ under an existing name (re-registering a different class without it → `DUPLICA
   `createGame2D/3D` — they pass `{ engine }` to `loadScene`, attaching it BEFORE
   `onReady` fires. Under a manual boot it throws `TREE_VIOLATION` until
   `engine.setScene(scene)`: prefer `createGame` (or `loadScene(json, { engine })`),
-  or defer engine-dependent work to the first `update`. Two onReady caveats even
-  with the engine attached: `engine.scene` is still null (setScene runs after),
-  and the scene's `input` actions are not declared yet — query input from
-  `update`/`fixedUpdate`, never `onReady`.
+  or defer engine-dependent work to the first `update`. Caveats even with the
+  engine attached: `engine.scene` is still null (setScene runs after), and the
+  scene's `input` actions are not declared yet — query input from
+  `update`/`fixedUpdate`, never `onReady`. The scene's `strings` and its
+  `connections[]` ARE both in place by then, so `engine.t(...)` resolves and a
+  signal you emit from `onReady` reaches its JSON handler.
+## When your script throws
+A throw is CONTAINED, not fatal — but only after the scene has loaded, and the
+two halves are different on purpose:
+- **at load** (`loadScene`, including every `onReady` in the initial pass) a
+  throw is a hard failure. That is where an authoring mistake belongs: you want
+  to hear about it before the game runs, not to play a game with a piece
+  missing.
+- **at runtime** — a spawned prefab, a clone, a node a behaviour adds — a throw
+  from `onEnterTree`, `onReady`, `onExitTree`, `update` or `fixedUpdate`
+  quarantines THAT script and nothing else. The node keeps its state, the rest
+  of the scene keeps running, and `engine.log` names the node, the script and
+  the hook.
+The runtime half used to cover only `update`/`fixedUpdate`, so a spawned
+prefab's `onReady` bug unwound into the `update()` of whatever spawned it: the
+innocent Spawner was quarantined, spawning stopped permanently, and the log
+named the wrong node.
+**A signal listener is quarantined the same way** — the one that throws is
+disconnected, everything else keeps running, and the log names the node that
+OWNS the listener rather than the one that emitted:
+```
+[incanto] a 'scoreChanged' listener owned by behavior 'Hud' on /World/Hud threw
+— THIS LISTENER is now off; /World/Score, which emitted it, and the rest of the
+scene keep running.
+```
+Both spellings, `node.on(...)` and a JSON `connections` wire. Only the JSON
+half used to be covered, so a cosmetic HUD handler with a typo in it disabled
+the SCRIPT OF THE NODE THAT EMITTED — on the five shipped examples that do
+`controller.on('movementStateChanged', …)`, that stops the player moving.
 - `this.rng` — seeded engine randomness: `next()` [0,1), `range(min,max)`,
   `int(min,max)` (inclusive), `pick(arr)`. **Never `Math.random()` in game logic** —
   with `new Engine({ seed: 42 })` a run replays identically (scripted verification).
@@ -115,19 +163,46 @@ What behavior code actually calls at runtime — all instance methods, no global
 | `parent.addChild(node)` | attach a DETACHED node (already-parented → `TREE_VIOLATION`); sibling name collisions auto-rename (`Enemy` → `Enemy2`) |
 | `duplicateNode(node)` | deep-clone via serialize→rebuild — returns a **detached** node; attach it explicitly with `addChild` |
 | `node.queueFree()` | deferred destruction — flushed at the END of the current update pass (queued during a flush = freed next pass) |
-| `node.free()` | immediate detach + teardown (children first, signals disconnected) |
+| `node.free()` | immediate detach + teardown (children first; the signals it owns AND the ones it subscribed to elsewhere are both disconnected — see below) |
 | `root.getNodesByName('Enemy')` | EVERY node with that name in the subtree, document order |
 | `node.getNodeOrNull(path)` | like `getNode` but `null` instead of `NODE_NOT_FOUND` |
 | `node.getNode('%Player')` | unique-name lookup across the whole tree (≥2 matches → `DUPLICATE_UNIQUE_NAME`) |
+| `node.findChild('Skin')` | the first descendant with that name, or `null` — `findChild(name, false)` searches direct children only |
+| `parent.removeChild(node)` | DETACH without tearing down: the node keeps its children and its props, and is yours to `addChild` somewhere else. Nothing frees it — a detached node nobody re-attaches is a leak |
+| `node.reparent(newParent)` | detach-and-attach in one call, which is the safe order (`addChild` on a still-parented node is a `TREE_VIOLATION`) |
+| `node.getPath()` | its absolute path, `/Level/Enemies/Slime3` — what every error message and report prints, and what to log when a lookup surprises you |
+| `other.isInGroup('enemy')` | **the question a trigger asks** — the first line of nearly every `triggerEnter` handler. `node.groups` is a SET, not the array the JSON writes it as, so `groups.includes(…)` is a TypeError |
+| `node.addToGroup('enemies')` / `node.removeFromGroup('enemies')` | tag at RUNTIME; `groups` in the JSON is the same set, declared |
 | `this.node.tree?.getNodesInGroup('enemies')` | group query (also `tree.callGroup(group, method, ...args)`) |
 | `engine.stop()` / `engine.start()` | pause / resume the loop — stop resets the clock and accumulator, so no banked sim time leaks into the resume |
 | `engine.step()` | advance exactly ONE fixed step + one update (both dt = the fixed step) — the unit of time for headless tests |
 | `engine.tick(timestampMs)` | manual frame advance — takes an **absolute** ms timestamp (rAF-style), NOT a dt; the first call after (re)start only primes the clock |
 | `engine.setScene(scene)` | swap scenes: the previous root is freed, the input map is cleared and redeclared from the new scene's `input{}`, the clock resets (`time`, `unscaledTime`, and **`timeScale` back to 1** — a level restarted out of a frozen game-over must not boot frozen), then `sceneChanged` fires |
+| `node.off(signal, fn)` | disconnect ONE listener you connected with `on` — pass the same function reference. (`free()` disconnects everything a node owns, so this is for a listener that must stop while the node lives on) |
+| `node.signal('died')` | the `Signal` object itself, for `connect`/`disconnect` by hand; undeclared names throw, like `emit` |
+| `node.listenerCount('died')` | how many are listening — a test's way to prove a wire was made, or dropped |
 | `engine.stats()` | live perf counters `{ fps, frameMs, nodes, running }` — fps/frameMs average the last ~60 REAL `tick` frames (headless `step()` runs report 0), nodes is the current tree size. GPU counters (triangles/draw calls) live on `renderer.stats()` / the merged `game.stats()` |
 The recurring traps: `duplicateNode` does NOT insert the clone anywhere — a
-"spawner that does nothing" usually forgot `addChild`. `engine.tick(16)` does
+"spawner that does nothing" usually forgot `addChild`.
+**The template you clone FROM is a live node.** Its behaviors run, its timers
+tick, its turret shoots — `visible: false` hides a node, it does not switch it
+off. `Spawner` and `WaveSpawner` sidestep this by DETACHING their `prefab` at
+ready; a shelf of templates you clone yourself is still in the tree, so author
+their scripts `"enabled": false` and wake the clone:
+```ts
+const tower = duplicateNode(this.node.getNode('/Game/Prefabs/Tower'));
+tower.behavior?.enable();          // the template stays asleep, this one works
+this.node.getNode('/Game/Towers').addChild(tower);
+```
+Without it an invisible tower at the origin defends your map, and the game looks
+fine. **And look the template up by PATH, not `%Name`**: a clone keeps its
+template's name, so `%Tower` is unambiguous exactly until the first one is
+placed, and then it throws `DUPLICATE_UNIQUE_NAME` from inside your build
+handler — a game that works once. `engine.tick(16)` does
 not mean "advance 16ms": tick wants wall-clock timestamps, so scripted loops
 should call `engine.step()` instead. And `queueFree` inside `update` is always
 safe — the node keeps existing until the pass ends.
@@ -209,6 +284,8 @@ no TypeScript, and all five are clean.
 { "name": "Spawner", "type": "Timer", "props": { "waitTime": 2, "autostart": true } }
 ```
 Emits `timeout` every `waitTime` s (`oneShot` for once). API: `start(time?)`, `stop()`, `running`.
+A `waitTime` of 0 is a load error: the update guard stops a timer with no period
+on its first frame, so it would never fire and never say so.
 ## CharacterController2D (JSON-only playable characters)

package/skills/incanto-building-2d-games.md CHANGED Viewed

@@ -15,6 +15,7 @@ Prerequisite: `incanto-scene-json-authoring.md` (this directory) for the file fo
 ```bash
 bunx incanto new my-game --template platformer-2d    # tilemap, jump feel, follow cam, coins
 bunx incanto new my-game --template star-survivor    # endless waves, auto-attack, upgrades
+bunx incanto new my-game --template molehill-2d      # played with the MOUSE — no character at all
 bunx incanto new --list                              # every starter, 3D and 2D
 ```
@@ -95,6 +96,10 @@ stop hand-placing dozens of ColorRect walls:
 - `.` / space = empty; digits `0-9` = atlas tile index directly; any OTHER char
   must be in `legend` — unknown chars **hard-fail at load** (fix the map, not
   the runtime).
+- **A legend value is an INDEX, not a description.** Every other tilemap format
+  puts solidity in the tile definition, so `"legend": { "#": { "solid": true } }`
+  is the natural guess — and it used to load clean and produce a level with no
+  floor. It is a hard error now, naming the `solid` prop that was meant.
 - `solid` tiles are merged into a handful of `StaticBody2D` rect colliders
   (greedy rectangles), so a 100×50 level costs a few bodies, not thousands.
 - Cell (0,0) hangs its TOP-LEFT on the node's origin; position the node to
@@ -103,7 +108,25 @@ stop hand-placing dozens of ColorRect walls:
 - No texture yet? Colliders still work — pair with ColorRect2D placeholders or
   just leave it invisible while you block out the level.
 - Change the map at runtime by REPLACING `cells` (mutations are not watched):
-  `map.cells = [...rows]` — geometry and colliders rebuild next frame.
+  `map.cells = [...rows]` — geometry and colliders rebuild next frame. For ONE
+  cell use `setTile` below, which does that correctly.
+**Pointing at tiles** — the whole input of a tile game, and four calls:
+```ts
+const cell = map.cellAt(...this.engine.pointerWorld() ?? []);  // [cx, cy] | null
+if (cell && map.tileAt(...cell) === 1) {
+  map.setTile(cell[0], cell[1], '.');          // dig it out (a CHARACTER)
+  marker.position = map.worldAt(...cell);      // the cell's CENTRE
+}
+```
+`cellAt` is null off the grid, `tileAt` is `-1` for an empty cell or one that is
+not there, and `worldAt` gives the cell's **centre** — the half-tile a
+hand-rolled version forgets. All four measure from the node's WORLD position
+(ancestors composed), which is the other thing hand-rolling gets wrong. An
+ancestor that SCALES or rotates the map moves the picture and not the answer,
+and `incanto-check` says so.
 ### `Sprite2D`
 | Prop | Default | Notes |
@@ -212,6 +235,13 @@ offsets that survive any canvas size: a `Label` at `[-16, 16]` under a
 `top-right` layer hugs the corner everywhere. Misspelled anchors fail at load
 listing the valid set. With a viewport design, UI coordinates are design px.
+**Two spellings, and the engine means it.** `UILayer` writes them with hyphens
+(`top-left`); the `HudLayer` widgets write them in camel case (`topLeft`). Nine
+of the same anchors, two vocabularies, and neither accepts the other's — a
+`UiText` with `"anchor": "top-left"` is a load error, and so is a `UILayer` with
+`"topLeft"`. Both errors print their own valid set, so you are one edit from
+right; this note is so you know why.
 ### A `UILayer` still SCALES. On a phone, use `HudLayer`
 `UILayer` ignores the camera; it does not ignore the viewport. Its contents are
@@ -274,13 +304,33 @@ between a readable and an unusable phone build.
   touched. Its inverse, `renderer.screenFromWorld(wx, wy)`, pins DOM to the
   world (see incanto-web-integration).
+  **From a Behavior, ask the ENGINE** — `this.engine` is all a behavior has, and
+  the renderer is not on it:
+  ```ts
+  const at = this.engine.pointerWorld();          // world px, or null
+  if (at) this.node.position = at;                // it IS a position array
+  this.engine.toWorld(sx, sy);                    // any screen point
+  this.engine.toScreen(this.node.position);       // → { x, y, behind }
+  ```
+  The renderer installs these, exactly as it installs `engine.picker`: `pickAt`
+  answers WHICH NODE the cursor is on, `pointerWorld` answers WHERE it is, and a
+  drag-and-launch needs the second one. Both are null with no renderer, and a
+  `runScript` `click` step (or `incanto-play`'s `at`) installs a geometric
+  version for the run — so aiming is testable headless, not only clicking.
 ## Game flow recipes
 - **Scene transition** (level 2, title → game):
   ```ts
   import { loadScene } from 'incanto';
-  game.engine.setScene(loadScene(level2Json));
+  game.engine.setScene(loadScene(level2Json, { engine: game.engine }));
   ```
+  Pass `{ engine }`: `onReady` runs during the LOAD, so a behaviour that reads
+  `this.engine` or `this.rng` there — `Wander` draws its first heading in it —
+  throws `TREE_VIOLATION` without it.
   `setScene` frees the old root, clears + redeclares the input map from the new
   scene's `input{}`, and emits `sceneChanged` — `createGame2D`'s touch overlay
   rebuilds itself on that signal, the PHYSICS world registers the new scene's
@@ -295,7 +345,7 @@ between a readable and an unusable phone build.
   last one is why the game-over recipe below is safe — a swap out of a frozen
   screen boots the next level running, not frozen.
 - **Game over / restart**: swap to a fresh load of the SAME JSON —
-  `engine.setScene(loadScene(levelJson))`. `loadScene` treats the JSON as
+  `engine.setScene(loadScene(levelJson, { engine }))`. `loadScene` treats the JSON as
   read-only (everything it keeps is cloned), so reloading the same imported
   object yields a clean run; only clone (`structuredClone(levelJson)`) first if
   your own code mutated that object. (`createGame`'s `scene` option already
@@ -323,7 +373,7 @@ constructor).
 ## Particles (effects in one node)
 ```json
-{ "name": "Torch", "type": "Particles2D", "props": { "preset": "fire" } }
+{ "name": "Torch", "type": "Particles2D", "props": { "preset": "fire" } },
 { "name": "Boom", "type": "Particles2D",
   "props": { "preset": "explosion", "rate": 0, "burst": 60 } }
 ```
@@ -423,7 +473,7 @@ anything a 540 px window can show.
 ```
 camera /Game/Camera centred [480, 274] showing 960×540px
-11 in view, 2 outside it
+11 in view, 2 outside it, 1 hidden (visible: false)
   onScreen  /Game/Level (TileMap2D) [0, 0] screen [0.333, -0.007] 160px
   onScreen  /Game/Gems/Gem1/Icon (Sprite2D) [512, 428] screen [0.067, 0.57] 157px
   offscreen /Game/Goblins/Goblin2/Skin (AnimatedSprite2D) [1002, 512] … 574px
@@ -434,14 +484,26 @@ camera /Game/Camera centred [480, 274] showing 960×540px
 edge". A node counts as in view when its BOX is — a `ColorRect2D`'s `size`, a
 `TileMap2D`'s whole grid (which hangs from its TOP-LEFT, not its centre), or a
 collider. A bare `Sprite2D` declares no size, so read `offscreen` there as "its
-ORIGIN is outside the view". Nothing is ever "behind" a 2D camera and nothing is
-lit, so neither is reported; `overlap` is real interpenetration, not resting on
-a platform. HUD widgets are screen-space and are left out entirely.
+ORIGIN is outside the view". `hidden` is `visible: false` on the node or on any
+ancestor — counted apart from `offscreen` because the fix differs, and printed as
+`NOTHING IS DRAWN` when it is every drawable in the scene. Nothing is ever
+"behind" a 2D camera and nothing is lit, so neither is reported; `overlap` is
+real interpenetration, not resting on a platform. HUD widgets are screen-space
+and are left out entirely.
 Then read `stats().errors` (something threw and got skipped) and `assetErrors()`
 (a texture 404'd). All of these are silent failures otherwise — the screen just
 looks wrong, or empty, and nothing throws.
+**A game with no jump key is fine.** `jumpAction`, `dashAction` and even
+`moveAction` may name an action the scene never declares — a top-down RPG has
+nothing to jump over — and the character simply never does that thing. Until
+this was fixed the controller THREW every frame, the node was quarantined, and
+the character could not move either: a top-down game that declared only `move`
+reported `✗ error in 1/1` and stood still, with the reason in a log nobody
+prints. An action you TYPED that does not exist is still reported, once, because
+that is a typo and not an omission.
 ## Platformer game feel (CharacterController2D)
 A jump that only fires while `isOnFloor()` is true feels BROKEN, and players do
@@ -491,6 +553,13 @@ entry, which is what the states you have no artwork for should be:
 }
 ```
+**The whole map is checked when the scene loads**, not when a clip first plays:
+a clip is `{frames, fps, loop}` and nothing else, so `frame`, `frameRate`,
+`speed` and `repeat` — all real fields in the sheet formats people convert from
+— are load errors naming the field you meant. Only the aliases used to be
+checked, so a misspelled `frames` was a hard error the first time the character
+walked, twenty minutes in.
 `incanto-assets copy` and `spriteFromLibraryMeta` already print these aliases,
 so pasting their output next to the wiring above works as-is; point any of them
 somewhere better when you have the art. Aliases may chain (`fall` → `jump` →

package/skills/incanto-building-3d-games.md CHANGED Viewed

@@ -81,7 +81,7 @@ All 3D nodes extend `Node3D` and therefore have the transform props:
 ### `MeshInstance3D`
 | Prop | Default | Notes |
 |---|---|---|
-| `mesh` | `"box"` | `box \| sphere \| capsule \| plane \| cylinder \| gem` — `gem` is a faceted crystal (icosahedron); with `material.flatShading: true` + low `roughness` it reads as a sparkling jewel (spin/tumble it for the sparkle) |
+| `mesh` | `"box"` | `box \| sphere \| capsule \| plane \| cylinder \| gem` — `gem` is a faceted crystal (icosahedron); with `material.flatShading: true` + low `roughness` it reads as a sparkling jewel (spin/tumble it for the sparkle). **This list is the whole list**: for a CURVED hull — a car body, a boat, a canopy, a fuselage — there is no primitive, and stacking boxes never gives you one. Use `LoftMesh3D` (below) |
 | `size` | `[1,1,1]` | box: extents · sphere/gem: radius = x · capsule: radius = x, height = y · plane: x·z ground (laid FLAT on XZ) · cylinder: radius = x, height = y |
 | `material` | `{}` | `{color: '#hex', metalness: 0..1, roughness: 0..1, opacity: 0..1, clearcoat: 0..1, clearcoatRoughness: 0..1, envMapIntensity: >=0, wireframe, flatShading, depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false, depthTest/Write true). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `depthTest: false` (+ a high `renderOrder`) makes a flat `plane`/`cylinder` an ALWAYS-ON-TOP ground decal — AoE telegraphs, selection/spawn rings — that never z-fights with or is hidden by bumpy terrain (`depthWrite: false` keeps it from occluding later effects). `map`/`normalMap` are texture URLs (lazy-loaded, headless-safe; map samples sRGB, normalMap linear), tiled `repeat` times across each face — box/plane UVs span 0..1 per face, so for worldspace density use `repeat: [length/tile, height/tile]` (e.g. a 6×2.5 m brick wall at one tile per 2 m → `[3, 1.25]`). `color` tints the map (near-white keeps the texture's own color). CAR PAINT: `clearcoat: 1` adds a glossy lacquer layer with its own reflection over a metallic base (`clearcoatRoughness` ~0.05-0.1 = mirror lacquer) — THE premium vehicle-paint look; `envMapIntensity` scales how strongly the surface mirrors the scene's sky/HDRI (glass windows want ~2, matte surfaces <1; needs a `sky`/`hdri` environment to reflect — at night with no sky there is nothing to mirror). NB: under ACES a very bright `emissiveIntensity` blows out to white — keep it modest (~1–2) + a saturated color for a vivid GLOWING look. Unknown keys, malformed `repeat`, or `repeat` without a map hard-fail at load |
 | `castShadow` / `receiveShadow` | `false` | |
@@ -270,10 +270,43 @@ and `Fill.position = [-(1 - frac) / 2, 0, 0.01]`. The offsets stay local to the
 (rotated) bar, so the drain always hugs the bar's left edge.
 ### `Camera3D`
-`fov: 60`, `near: 0.1`, `far: 1000`, `current: false`.
+`fov: 60`, `near: 0.1`, `far: 1000`, `current: false`, `lookAt: ""`.
 Mark exactly ONE camera `current: true` (otherwise the first camera in tree order is used).
-Aspect ratio is automatic. To frame an origin-centered scene, a good default is
-`position: [7, 6, 9]`, `rotation: [-26, 36, 0]`.
+Aspect ratio is automatic.
+**Point it with `lookAt`, not with a `rotation` you worked out.**
+```json
+{ "name": "Cam", "type": "Camera3D",
+  "props": { "current": true, "position": [7, 6, 9], "lookAt": "%Player" } }
+```
+`lookAt` is a node path, re-aimed every frame, so it also tracks a target that
+moves. It orients with WORLD UP, which is the part you cannot write yourself in
+scene JSON — and cannot write in game code either without importing three, which
+this engine's own guardrail forbids ("mutate node props — never touch three.js
+objects").
+This is not a convenience. A hand-written `rotation` for a camera is
+**wrong at every heading but one**, and the way it is wrong is invisible from
+inside the frame:
+- The one published direction→rotation formula (`incanto-3d-character.md`, "the
+  +Z-FORWARD rule", *"There is ONE facing formula"*) is derived for a SKIN — a rod,
+  which has no meaningful up. Measured over 72 look headings, applying it to a
+  camera aims perfectly (dot 1.000 in all 72) and puts the world **upside down in
+  36 of them**. Its own published check, `rodAxis · (target − eye) ≈ 1`, scores
+  1.000 on every upside-down one.
+- **No two-angle recipe can be right.** `rotation` is Euler XYZ, so
+  `[pitch, yaw, 0]` is Rx·Ry while a level camera is Ry·Rx: an upright camera's
+  third angle is NON-ZERO. The `[-26, 36, 0]` this document recommended for years
+  aims at 0.9924 and tilts the horizon **16°**; the level answer is
+  `[-33.69, 32.91, 19.91]`, which nobody would write by hand.
+- A camera looks down its own local **−Z**, unlike every skin in the engine.
+`framing()` now prints `up [x, y, z]` and the roll in degrees, so a tilted or
+inverted camera is something you can SEE in a report rather than something you
+notice in a screenshot.
 ### Lights
 - `DirectionalLight3D` — `color: '#ffffff'`, `intensity: 1`, `castShadow: false`.
@@ -524,6 +557,13 @@ for (const o of off) console.error(`  ${o.path}: ${o.gap > 0 ? 'floats' : 'burie
 Put it in your `verify.ts` next to `auditScene`. It costs nothing and it is the
 difference between shipping a floating bridge and not.
+**Mark what is not meant to touch the ground.** `snapToGround: false` is the
+escape and it INHERITS, so one mark exempts a whole assembly: a cloud made of
+puffs, a palm made of trunk segments, a lamp at the top of a lighthouse, a rock
+sunk into the slope on purpose. Put it on the group, not on its parts — before
+0.73 it read the node's own prop only, and this repo's own flagship template
+reported 64 floating cloud puffs.
 ## The loading screen has to cover the WHOLE boot
 Downloading the assets is the first half. Building a dressed scene and
@@ -569,6 +609,20 @@ previous explosion across the level) as
 point sprites in meters: preset distances auto-scale ÷100 (presets are authored
 in 2D px). See incanto-building-2d-games for the full prop list.
+**Firing one from a behaviour is `replay()`** — move the emitter, then replay:
+```ts
+const dust = this.node.getNode('Dust') as Particles3D;
+dust.position = [x, 0.2, z];
+dust.replay();                 // `emitting: false` stays false; this is the game asking
+```
+Not `play`, not `burst`, not `emit` (that one belongs to signals). The 2D skill
+has always named it and this one did not, so a 3D game built from this page
+alone had a one-shot it could not fire. `particles()` is the same node's test
+hook — the live particle list, for a harness asking whether anything came out.
+`engine.effects.countOf('explosion')` is the cheaper question.
 Points render through a built-in soft sprite with a SOLID opaque core (not hard
 squares), so colours read even at small sizes, and `'normal'` blend fades cleanly
 to transparent (per-particle RGBA alpha). `paletteColors` (per-particle