incanto 0.64.1 → 0.66.0

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

@@ -293,8 +293,89 @@ 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
+line of sight is decided — it is `this.physics`. At the boot site it is
+`game.physics`, and anywhere you hold the engine it is `engine.physics`. All
+three are the same object; it is `null` in a game with no physics bodies, so
+`?.` and treat a missing world as "nothing in the way", or don't.
+
+```ts
+// inside a Behavior
+const hit = this.physics?.castRay(eye, dir, range, this.node);
+const blocked = hit != null && hit.node !== player;
+```
+
 Both runtimes expose the same query (2D in PIXELS y-down, 3D in meters):
 
 ```ts
@@ -302,7 +383,9 @@ const hit = physics.castRay(origin, dir, maxLen, excludeBody?, { staticOnly?: tr
 // → { distance, normal, node } | null   (sensors never block rays)
 ```
 
-Exclude the shooter's own body when casting from inside it.
+Exclude the shooter's own body when casting from inside it — a ray that starts
+inside its own collider hits itself at distance 0, which reads as "blocked" and
+is the reason a vision cone can come back permanently blind.
 
 3D also has a THICK ray — a sphere sweep — for probes where skimming matters
 (the camera boom, ledge feelers):

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/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.64.1",
+    "incanto": "^0.66.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

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

package/templates-app/star-survivor/package.json

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

package/templates-app/tps-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.64.1",
+    "incanto": "^0.66.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.64.1",
+    "incanto": "^0.66.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -1,9 +0,0 @@
-{
-  "hurt": {
-    "onto": "%Shade1_1"
-  },
-  "lose": {
-    "skip": "no fail state by design \u2014 `onPlayerDown` shows a banner and reloads the level after 1.6s"
-  },
-  "seconds": 20
-}

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

@@ -1,5 +0,0 @@
-{
-  "hurt": { "onto": "%Spikes1" },
-  "lose": true,
-  "seconds": 20
-}

package/templates-app/star-survivor/coverage.json

@@ -1,5 +0,0 @@
-{
-  "hurt": "afk",
-  "lose": true,
-  "seconds": 30
-}

package/templates-app/tps-3d/coverage.json

@@ -1,5 +0,0 @@
-{
-  "hurt": "afk",
-  "lose": true,
-  "seconds": 30
-}

package/templates-app/village-quest-3d/coverage.json

@@ -1,9 +0,0 @@
-{
-  "hurt": {
-    "onto": "%Wolf1"
-  },
-  "lose": {
-    "skip": "no fail state by design \u2014 `onPlayerDown` shows a banner and reloads the level after 1.6s"
-  },
-  "seconds": 20
-}