incanto 0.65.0 → 0.67.0

package/skills/incanto-physics-and-input.md

@@ -293,6 +293,75 @@ Types — 2D: `fixed` (weld) · `revolute` (pin/hinge) · `rope` (max distance)
 distance at creation. `anchor`/`targetAnchor` are local offsets (px / m).
 Chains work (pendulums, bridges: each link a body + joint to the previous).
 
+## Pushing a body around (the API that was in no skill)
+
+A dynamic `RigidBody2D`/`RigidBody3D` has a force API and none of these appeared
+in any shipped skill, so an agent building a physics puzzle reported the engine
+as having "no force/impulse API at all" and designed around its absence:
+
+```ts
+const body = this.getNode('/root/Crate') as RigidBody3D;
+body.applyImpulse([0, 6, 0]);      // an instant kick, in mass*units/second
+body.velocity = [2, 0, 0];         // or set the velocity outright
+```
+
+`applyImpulse` is what the character controller itself runs on. It is an
+IMPULSE, not a force: it changes velocity once, so a continuous push is one call
+per frame from `update(dt)` scaled by `dt`.
+
+Readable/writable body state: `velocity`, `mass`, `gravityScale`, `friction`,
+`restitution`, `fixedRotation`. There is no torque call and no `angularVelocity`
+yet — a body's spin can be neither set nor read.
+
+## What is inside this Area right now?
+
+`triggerEnter(other)` / `triggerExit(other)` tell you about CROSSINGS. A pressure
+plate, a capture point, "how many enemies are in the blast" and a shop trigger
+all want OCCUPANCY, and asking used to mean keeping your own `Set` fed by those
+two signals — plus a geometric re-check every frame, because a body that is
+teleported or freed inside a sensor does not reliably announce its exit.
+
+```ts
+const load = plate.overlapping('cargo')
+  .reduce((kg, b) => kg + ((b as RigidBody3D).mass ?? 0), 0);
+door.open = load >= 60;
+```
+
+`Area2D`/`Area3D` `overlapping(group?)` returns what the solver currently says is
+inside, and drops freed nodes on read. **It includes the STATIC world** — a plate
+laid into the floor genuinely contains the floor — so pass a group to ask the
+question you usually mean.
+
+## Joints: the three things that decide whether yours works
+
+1. **There is no hinge in 3D.** The types are `fixed | spherical | rope | spring`.
+   A hinge is **two `spherical` joints at two points along the axis** — that
+   constrains rotation to the line between them, and it is exactly how a seesaw
+   or a door is built. (2D has `revolute` and needs none of this.)
+2. **`collide` decides whether the two ends touch, and its default reads the
+   type.** Rapier lets jointed bodies collide, and a hinge wants its bodies
+   overlapping at the pivot — so the contact solver fights the joint and flings
+   them. Before this, a first hinge produced a bar that spun chaotically forever
+   and threw a 40 kg box thirty metres, and the author nearly filed "spherical
+   joints inject energy".
+
+   | joint | default | why |
+   |---|---|---|
+   | `fixed` · `spherical` · `revolute` | **off** | a pivot's bodies overlap by construction |
+   | `rope` · `spring` | **on** | a tether anchors a thing to the world, and it still has to rest on it |
+
+   Set `true`/`false` to say it outright. **It governs the two JOINTED bodies
+   only** — never their contact with the rest of the world. Defaulting a spring
+   off drops a barrel roped to the floor straight through it, which is how this
+   table was arrived at.
+3. **`anchor`/`targetAnchor` are local offsets from each body's ORIGIN**,
+   resolved against the bodies' positions at load. If the two disagree the solver
+   snaps the body into place on the first frame, and a 4 cm typo is silent. Author
+   them with arithmetic (generate the scene) rather than by hand.
+
+There are no joint limits or motors yet: bound a lever's travel with static
+collision geometry in its way.
+
 ## Raycasts
 
 **Where `physics` comes from.** From a `Behavior` — where AI lives, and where

package/skills/incanto-playtesting.md

@@ -51,10 +51,24 @@ two.
 | `fell` | the player left the world past `--fall-below` (default: 50 m under the spawn in 3D, 1000 px under it in 2D) |
 | `error` | `stats().errors` went above zero — a behavior threw |
 | `stuck` | the clock ran out AND the player never got more than 3 m (96 px) from its spawn — it is wedged, or nothing moves it |
+| `swapped` | the game changed scene. The bot binds player, destinations and the win/lose oracle ONCE, from the tree it started in, so nothing after a `goToScene` is measured — the run stops there and says so. It is not a defect, and the destinations it never got to are reported as unmeasured rather than missed. Judge a multi-scene game with a scripted `runScript`. |
 | `unfinished` | the clock ran out on a player that was getting around. Not a defect: a win that needs a SEQUENCE (talk to the NPC, then fetch, then return) is out of reach of a random walker, forever |
 | `never reached` | destinations the bot never came within `--reach-radius` of (default 2 m in 3D, 32 px in 2D) |
 | `never fired` | signals a `connections[]` entry listens to that never happened |
-| `danger` | how many times the player's `Health` emitted `damaged` |
+| `danger` | how many times the player's `Health` emitted `damaged` — and when that is ZERO, WHICH zero it is: a scene with no hazard wired at all is a walkabout and worth shouting about; a scene full of them that never landed one is a report about the BOT, which a real player would outrun less easily. Hazards are counted from the scene FILE, because a `Spawner` detaches its prefab at ready and a wave game's hazards are not in the tree yet. |
+
+**The bot can use the MOUSE.** If your scene has `Clickable` nodes, it presses
+and releases over them at random — through the real `Clickable`, the real
+`mouseJustPressed` edge and your real connection, with a picker that answers
+from the tree (the recipe under "Testing a mouse-driven game headlessly"). It
+drove actions and nothing else before, so a tactics game, a tower defense and a
+duel all reported the identical `? plays — 8 runs played without reaching a
+win`. A scene with nothing clickable is untouched: it does not gain an
+`engine.picker` it never had.
+
+A random clicker still cannot finish a game that needs a SEQUENCE — select a
+trooper, then a tile, then end the turn — and that is reported as unmeasured,
+not failed.
 
 **Nothing here is a guess about your design.** The scene already declares what
 winning is; this only listens.

package/skills/incanto-save-slots.md

@@ -89,7 +89,27 @@ game that shipped six weeks ago. Check what you read.
 Built-ins that already save: `Health` (current, dead), `ScoreKeeper` (score,
 lives, won/lost), `Collector` (total).
 
-## Every node you save needs a uid
+## Every node you save — and every node that VANISHES — needs a uid
+
+A collectible does not save state; it DISAPPEARS, and disappearing is the thing
+the save has to record. `#freed` is keyed by uid, so a pickup without one is
+silently omitted: the score that counted it restores, and the pickup restores
+too. Measured on a starter with 1 uid across 141 nodes:
+
+```
+coins after collecting : 9
+save["#freed"]         : undefined
+restore report         : { restored: 1, expected: 1, freed: 0 }
+coins AFTER load       : 12          <- three coins resurrected
+auditScene warnings    : []          <- and every checker was green
+```
+
+`captureState` now reports this as an ERROR naming the nodes, because the save
+it just wrote is already wrong. It does not guess a replacement: a uid survives
+a rename and a reparent, and a saved PATH would point at whatever node moved
+into that slot after your next edit.
+
+
 
 The uid is the join key, because it is the one identifier that survives a rename
 or a reparent. The editor assigns one to every node it touches. A hand-written

package/skills/incanto-verifying-your-game.md

@@ -858,3 +858,22 @@ const inputToWorld = Math.atan2(at()[1] - before[1], at()[0] - before[0]);
 
 `examples/village-quest-3d/verify.ts` does exactly this and fails with
 "the player cannot reach it on foot" when it cannot.
+
+
+## When node refuses your TypeScript
+
+The bins' shebang is node, and node's type stripping **erases** types — it does
+not transform. Three ordinary things it refuses, all of which vite and bun
+compile without comment:
+
+| what you wrote | what node says |
+|---|---|
+| `import scene from './game.scene.json'` | needs an import attribute of "type: json" |
+| `import { quest } from './quest'` | Cannot find module …/quest |
+| `constructor(private root: Node3D)` | TypeScript parameter property is not supported in strip-only mode |
+
+**You do not have to change any of them.** Every bin that loads a `--behaviors`
+file re-runs itself under bun when node refuses it, so the command just works.
+If bun is not on PATH the message says which of the three it hit.
+
+Prefix with `bunx --bun` to skip the round trip.

package/skills/incanto-web-integration.md

@@ -58,9 +58,30 @@ export function GamePage() {
 Rule of thumb: score/menus/dialogs that look like WEB UI → DOM overlay;
 anything the game itself must own (and runScript must verify) → UILayer.
 
-Pin a DOM element to a world position: `game.renderer.screenFromWorld(wx, wy)`
-(and `worldFromScreen(sx, sy)` the other way, for taps and clicks)
-each frame (subscribe `engine.updated`), then `transform: translate(x, y)`.
+Pin a DOM element to a world position each frame (subscribe `engine.updated`),
+then `transform: translate(x, y)`:
+
+```ts
+game.renderer.screenFromWorld(wx, wy)         // 2D
+game.renderer.screenFromWorld(wx, wy, wz)     // 3D — takes THREE arguments
+```
+
+Going the other way, for taps and clicks:
+
+```ts
+game.renderer.worldFromScreen(sx, sy)             // 2D → { x, y }
+game.renderer.worldFromScreen(sx, sy, planeY?)    // 3D → { x, y, z } on a
+                                                  //   horizontal plane (default y=0)
+game.renderer.rayFromScreen(sx, sy)               // 3D → { origin, dir } for
+                                                  //   physics.castRay on uneven ground
+```
+
+**A pixel in 3D is a ray, not a point**, which is why the 3D form needs a
+surface: `worldFromScreen` lands it on the ground plane, and `rayFromScreen`
+hands you the ray when the ground is terrain or a stack of crates. Both return
+null when the ray misses (looking at the sky). `pick(sx, sy)` gives you the NODE
+under a pixel — a different question, and the only one 3D could answer before
+0.66.
 
 Perf note: `useNodeProp` deep-compares per frame — subscribe to LEAF values
 (`'UI/Score', 'text'`), not big objects like a whole `animations` map.

package/skills/incanto-your-first-game.md

@@ -83,13 +83,13 @@ and it is entirely JSON.
 ```jsonc
 "connections": [
   { "signal": "died",     "from": "Player", "to": "Score",  "handler": "loseLife" },
-  { "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "revive" },
+  { "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "reviveFull" },
   { "signal": "won",      "from": "Score",  "to": "Flow",   "handler": "win" },
   { "signal": "lost",     "from": "Score",  "to": "Flow",   "handler": "gameOver" }
 ]
 ```
 
-**`lifeLost → revive` is not optional.** A `Health` that has died stays dead:
+**`lifeLost → reviveFull` is not optional.** A `Health` that has died stays dead:
 `damage`, `heal` and regen all stop, so without that wire the player becomes a
 walking corpse after the first death — full HP bar, immune to everything,
 `died` never firing again, lives frozen, and the game quietly unlosable. It
@@ -158,7 +158,7 @@ floats over small ledges already.
 The tell for both is one line of `incanto-playtest` output:
 
 ```
-danger: the player took damage 0 times in 4 runs — nothing here can hurt you
+danger: nothing in this scene can hurt the player — no DamageOnContact, no hazard group
 ```
 
 Read it. It is the truth.
@@ -219,7 +219,7 @@ Things that cost real time, in the order you will meet them.
 
 | when | the trap |
 | --- | --- |
-| a game with LIVES | `died` stops a `Health` for good — wire `lifeLost → revive` or you can spend only one. |
+| a game with LIVES | `died` stops a `Health` for good — wire `lifeLost → reviveFull` or you can spend only one. **Not `revive`**: `lifeLost` carries the life COUNT and `revive(hp?)` reads it as health, so you come back at 2 HP, then 1, then 0. |
 | wiring a score | `died` carries nothing; `addScore(n)` wants one → `NaN`. Wire `dealtDamage` from the killer. |
 | enemies feel harmless | `repeatEvery` on the contact hitbox, or one hit is all you get. |
 | enemies never arrive | a chaser cannot climb — `stepHeight`, and it loses to a large downward velocity you apply yourself. |

package/templates-app/beacon-isle-3d/package.json

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.65.0",
+    "incanto": "^0.67.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/beacon-isle-3d/src/game.scene.json

@@ -122,7 +122,8 @@
           "props": {
             "pausePanelPath": "%PauseMenu"
           }
-        }
+        },
+        "uid": "n_59r4gykhbcuemdgu"
       },
       {
         "name": "Terrain",
@@ -1605,7 +1606,8 @@
               "volume": 0.5
             }
           }
-        ]
+        ],
+        "uid": "n_z47j96sgcxut952d"
       },
       {
         "name": "Ward1",
@@ -1973,7 +1975,8 @@
                 "oncePerTarget": false,
                 "repeatEvery": 1.2
               }
-            }
+            },
+            "uid": "n_z8vhukdcirpi88je"
           },
           {
             "name": "HissSfx",
@@ -1987,7 +1990,8 @@
               "maxDistance": 30
             }
           }
-        ]
+        ],
+        "uid": "n_n468rqi1ozzm61uu"
       },
       {
         "name": "Shade1_2",
@@ -2091,7 +2095,8 @@
                 "oncePerTarget": false,
                 "repeatEvery": 1.2
               }
-            }
+            },
+            "uid": "n_bq1hz55sxw1i1im1"
           },
           {
             "name": "HissSfx",
@@ -2105,7 +2110,8 @@
               "maxDistance": 30
             }
           }
-        ]
+        ],
+        "uid": "n_ny13372zziqzgpom"
       },
       {
         "name": "Shade2_1",
@@ -2209,7 +2215,8 @@
                 "oncePerTarget": false,
                 "repeatEvery": 1.2
               }
-            }
+            },
+            "uid": "n_y9jsyb615rpdggas"
           },
           {
             "name": "HissSfx",
@@ -2223,7 +2230,8 @@
               "maxDistance": 30
             }
           }
-        ]
+        ],
+        "uid": "n_r53mg0r2ctvvkvjj"
       },
       {
         "name": "Shade2_2",
@@ -2327,7 +2335,8 @@
                 "oncePerTarget": false,
                 "repeatEvery": 1.2
               }
-            }
+            },
+            "uid": "n_fg4pcm0kcpbzpqui"
           },
           {
             "name": "HissSfx",
@@ -2341,7 +2350,8 @@
               "maxDistance": 30
             }
           }
-        ]
+        ],
+        "uid": "n_y5kshgw9213y7eeo"
       },
       {
         "name": "Shade3_1",
@@ -2445,7 +2455,8 @@
                 "oncePerTarget": false,
                 "repeatEvery": 1.2
               }
-            }
+            },
+            "uid": "n_l9e6uonnlyg7m16w"
           },
           {
             "name": "HissSfx",
@@ -2459,7 +2470,8 @@
               "maxDistance": 30
             }
           }
-        ]
+        ],
+        "uid": "n_ojzy1ypkshyepyvy"
       },
       {
         "name": "Shade3_2",
@@ -2563,7 +2575,8 @@
                 "oncePerTarget": false,
                 "repeatEvery": 1.2
               }
-            }
+            },
+            "uid": "n_7xn82zimw6skfh3j"
           },
           {
             "name": "HissSfx",
@@ -2577,7 +2590,8 @@
               "maxDistance": 30
             }
           }
-        ]
+        ],
+        "uid": "n_l5g65a25w1r2yvby"
       },
       {
         "name": "Player",
@@ -2622,7 +2636,8 @@
             },
             "script": {
               "name": "SwordStrike"
-            }
+            },
+            "uid": "n_cyhj8t0qy5t3k94v"
           },
           {
             "name": "Skin",
@@ -2727,7 +2742,8 @@
             "nightDarkness": 0.32,
             "maxSunElevationDeg": 48
           }
-        }
+        },
+        "uid": "n_v447j9q4dnw2gwtj"
       },
       {
         "name": "Boss",
@@ -2878,7 +2894,8 @@
                 "oncePerTarget": false,
                 "repeatEvery": 1.5
               }
-            }
+            },
+            "uid": "n_sfo65nky8me2m1lr"
           },
           {
             "name": "RoarSfx",
@@ -2892,7 +2909,8 @@
               "maxDistance": 90
             }
           }
-        ]
+        ],
+        "uid": "n_er3epyju7e5xopzg"
       },
       {
         "name": "Camera",
@@ -2997,7 +3015,8 @@
           }
         ]
       }
-    ]
+    ],
+    "uid": "n_ndhsdrkhi26aksvr"
   },
   "connections": [
     {

package/templates-app/platformer-2d/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.65.0",
+    "incanto": "^0.67.0",
     "three": "^0.184.0"
   },
   "devDependencies": {