incanto 0.64.1 → 0.66.0

package/dist/2d.d.ts

@@ -1,10 +1,10 @@
-import { P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-DsgayMsH.js";
+import { P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-BXNLfIJk.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
 import { r as FrameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-DolLJWJn.js";
+import { t as LoadSceneOptions } from "./loader-Cga7FVP4.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-D5GJgb_x.js";
+import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-_UAcHxnC.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
 
@@ -157,6 +157,11 @@ declare class StaticBody2D extends PhysicsBody2D {
 */
 declare class Area2D extends PhysicsBody2D {
   static override readonly typeName: string;
+  /**
+  * Who is inside RIGHT NOW — the standing answer behind the enter/exit pair.
+  * See `Area3D.overlapping`. Empty in a scene with no physics world.
+  */
+  overlapping(group?: string): PhysicsBody2D[];
 }
 /** Dynamic simulated body. */
 declare class RigidBody2D extends PhysicsBody2D {
@@ -271,6 +276,11 @@ declare class Physics2D {
   private scopedLines;
   /** Create newly-arrived joints; tear down departed ones. */
   private syncJoints;
+  /** Who is currently inside each sensor/body, maintained from the event drain. */
+  private readonly overlaps;
+  private trackOverlap;
+  /** The bodies currently overlapping `node`. Freed nodes are dropped on read. */
+  overlapping(node: PhysicsBody2D): PhysicsBody2D[];
   /**
   * World-space raycast in PIXELS (y-down). `exclude` skips that body — a
   * shooter probing from inside its own collider needs it. Sensors (Area2D)
@@ -719,6 +729,31 @@ declare class Joint2D extends Node2D {
   length: number;
   stiffness: number;
   damping: number;
+  /**
+  * Do the two linked bodies still collide with EACH OTHER?
+  *
+  * `null` (default) decides from the joint type, because the two families want
+  * opposite answers:
+  *
+  * - **pivots** (`fixed`, `spherical`, `revolute`) → **off**. A hinge's bodies
+  *   overlap at the pivot by construction, so the contact solver fights the
+  *   joint and flings them. A puzzle builder's first hinge produced a bar that
+  *   spun chaotically forever and threw a 40 kg box thirty metres, and they
+  *   nearly filed "spherical joints inject energy":
+  *
+  *   ```
+  *   t=   0  Plank r=[0,0,0]      Box [ 0.00, 5.50,  2.40]
+  *   t=3000  Plank r=[-66,24,64]  Box [-29.70, 0.40, -4.91]
+  *   ```
+  *
+  * - **tethers** (`rope`, `spring`) → **on**. These anchor a thing to the world,
+  *   and the thing has to rest on what it is tethered to. Defaulting these off
+  *   drops a barrel roped to the floor straight through it — measured, in this
+  *   repo's own conformance room.
+  *
+  * Set `true`/`false` to say it outright.
+  */
+  collide: boolean | null;
   override onEnterTree(): void;
   /** @internal The two bodies, resolved (throws on a bad target at step time). */
   _resolveBodies(): {

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-B1KM6dA6.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-dGsbnJ87.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BPJcJRRP.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-Dd7H4bJV.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-D0CxCveZ.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-Cji5A6sX.js";
 //#region src/2d/library-sprite.ts
 /**
 * What a `CharacterController2D`/`3D` will ask a skin to play, and the clip in

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
-import { D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-DsgayMsH.js";
+import { D as QualityCaps, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-BXNLfIJk.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
 import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-DolLJWJn.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-D5GJgb_x.js";
+import { t as LoadSceneOptions } from "./loader-Cga7FVP4.js";
+import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-_UAcHxnC.js";
 import { n as PathGrid } from "./pathfinding-_fGrCFmH.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
@@ -358,6 +358,33 @@ declare class StaticBody3D extends PhysicsBody3D {
 /** Sensor volume emitting `triggerEnter(other)` / `triggerExit(other)`. */
 declare class Area3D extends PhysicsBody3D {
   static override readonly typeName: string;
+  /**
+  * Who is inside RIGHT NOW — the standing answer behind the enter/exit pair.
+  *
+  * Enter and exit tell you about crossings; a pressure plate, a capture point,
+  * a "how many enemies are in the blast" count and a shop trigger all want
+  * OCCUPANCY. Without this every one of them kept a private `Set` fed by the
+  * two signals, and had to guard it, because a body that is teleported or
+  * freed inside a sensor does not reliably announce its exit. Physics already
+  * knows; now it says.
+  *
+  * ```ts
+  * const load = this.area.overlapping()
+  *   .reduce((kg, b) => kg + ((b as RigidBody3D).mass ?? 0), 0);
+  * door.open = load >= 60;
+  * ```
+  *
+  * It reports everything the solver says is inside, STATIC WORLD INCLUDED — a
+  * plate laid into the floor genuinely contains the floor. Pass a group to ask
+  * the question you usually mean:
+  *
+  * ```ts
+  * area.overlapping('crate')   // only things tagged `crate`
+  * ```
+  *
+  * Empty in a scene with no physics world.
+  */
+  overlapping(group?: string): PhysicsBody3D[];
 }
 /** Dynamic simulated body. */
 declare class RigidBody3D extends PhysicsBody3D {
@@ -370,6 +397,14 @@ declare class RigidBody3D extends PhysicsBody3D {
   restitution: number;
   /** m/s, y-up. Read back every step; write to launch. */
   linearVelocity: number[];
+  /**
+  * rad/s about each world axis. Read back every step; write to spin.
+  *
+  * A puzzle builder could neither launch a spinning body nor read how fast a
+  * lever was swinging — only its angle, differenced by hand — because this had
+  * no counterpart to `linearVelocity`. `fixedRotation` pins it at zero.
+  */
+  angularVelocity: number[];
   /** @internal set by Physics3D */
   _physics3d: Physics3D | null;
   /** World-space impulse (kg·m/s) — the floating-capsule controller's verb. */
@@ -539,6 +574,17 @@ declare class Physics3D {
   velocityOf(node: PhysicsBody3D): [number, number, number];
   /** Create newly-arrived joints; tear down departed ones. */
   private syncJoints;
+  /** Who is currently inside each sensor/body, maintained from the event drain. */
+  private readonly overlaps;
+  private trackOverlap;
+  /**
+  * The bodies currently overlapping `node` — the standing answer behind
+  * `triggerEnter`/`triggerExit`.
+  *
+  * Freed nodes are dropped on read rather than tracked, so a hazard that
+  * despawns inside a plate cannot leave a ghost holding a door open.
+  */
+  overlapping(node: PhysicsBody3D): PhysicsBody3D[];
   /**
   * World-space raycast (meters). `exclude` skips that body's collider —
   * ground probes from inside a capsule need it. `opts.staticOnly` hits ONLY the
@@ -1264,6 +1310,25 @@ declare class CharacterController3D extends Node3D {
   airControl: number;
   fallGravity: number;
   floatHeight: number;
+  /**
+  * How high a step the PLAYER walks up without jumping (0 = off).
+  *
+  * The hover spring holds the capsule a fixed distance above whatever is
+  * DIRECTLY below it, so a vertical face stopped the player dead at about
+  * 0.2 m — while `CharacterBody3D.stepHeight` let every enemy climb 0.35 m.
+  * The docs said the player did not need this ("it floats over small ledges
+  * already"); it floats over 18 cm ones.
+  *
+  * This probes just AHEAD of the capsule in the direction of travel: if the
+  * ground there is higher, but by no more than `stepHeight`, the spring aims
+  * at THAT surface and lifts the character onto it. A wall taller than the
+  * step is not a step and still stops you.
+  *
+  * Do not reach for `floatHeight` instead. It does raise the character over
+  * ledges, and it silently makes it WEIGHTLESS: at `floatHeight: 0.28` a
+  * 200 kg character does not move a seesaw a 70 kg crate tips.
+  */
+  stepHeight: number;
   mouseLook: boolean;
   zoomMin: number;
   zoomMax: number;
@@ -1836,6 +1901,31 @@ declare class Joint3D extends Node3D {
   length: number;
   stiffness: number;
   damping: number;
+  /**
+  * Do the two linked bodies still collide with EACH OTHER?
+  *
+  * `null` (default) decides from the joint type, because the two families want
+  * opposite answers:
+  *
+  * - **pivots** (`fixed`, `spherical`, `revolute`) → **off**. A hinge's bodies
+  *   overlap at the pivot by construction, so the contact solver fights the
+  *   joint and flings them. A puzzle builder's first hinge produced a bar that
+  *   spun chaotically forever and threw a 40 kg box thirty metres, and they
+  *   nearly filed "spherical joints inject energy":
+  *
+  *   ```
+  *   t=   0  Plank r=[0,0,0]      Box [ 0.00, 5.50,  2.40]
+  *   t=3000  Plank r=[-66,24,64]  Box [-29.70, 0.40, -4.91]
+  *   ```
+  *
+  * - **tethers** (`rope`, `spring`) → **on**. These anchor a thing to the world,
+  *   and the thing has to rest on what it is tethered to. Defaulting these off
+  *   drops a barrel roped to the floor straight through it — measured, in this
+  *   repo's own conformance room.
+  *
+  * Set `true`/`false` to say it outright.
+  */
+  collide: boolean | null;
   override onEnterTree(): void;
   /** @internal The two bodies, resolved (throws on a bad target at step time). */
   _resolveBodies(): {
@@ -3719,6 +3809,43 @@ declare class Renderer3D {
     behind: boolean;
   };
   /**
+  * The WORLD POINT under canvas pixel (sx, sy) — the other half of
+  * `screenFromWorld`, and the call `incanto-web-integration.md` has always
+  * offered "for taps and clicks".
+  *
+  * It did not exist in 3D. `Renderer2D` has had it since the beginning, the
+  * doc covers both runtimes, and an agent building a tower defense went looking
+  * for it and measured `typeof game.renderer.worldFromScreen === "undefined"`.
+  * `pick()` gives you the NODE under a pixel but never the POINT, so "put the
+  * thing where the player clicked on the ground" was not expressible and that
+  * game discretised its whole map into clickable pads instead.
+  *
+  * A pixel in 3D is a RAY, not a point, so this needs a surface to land on and
+  * takes the horizontal plane at `planeY` (default 0 — the ground). Returns
+  * null when the ray runs parallel to that plane or would only meet it behind
+  * the camera, which is what "the sky" looks like from here.
+  *
+  * For anything not flat — terrain, a hillside, a stack of crates — raycast
+  * physics instead: `rayFromScreen` gives you the origin and direction to feed
+  * `physics.castRay`.
+  */
+  worldFromScreen(sx: number, sy: number, planeY?: number): {
+    x: number;
+    y: number;
+    z: number;
+  } | null;
+  /**
+  * The camera ray through canvas pixel (sx, sy) — origin and unit direction,
+  * ready for `physics.castRay(origin, dir, maxLen)`.
+  *
+  * This is the honest 3D answer to "where did the player click": on uneven
+  * ground the only thing that knows is the collision world.
+  */
+  rayFromScreen(sx: number, sy: number): {
+    origin: [number, number, number];
+    dir: [number, number, number];
+  } | null;
+  /**
   * The node rendered under canvas pixel (sx, sy), or null — raycasts the last
   * rendered camera into the scene and resolves the hit up to its `incantoNode`
   * (every Node3D stamps that in `_ensureObject3D`). 3D depth-sorts, so the

package/dist/3d.js

@@ -1,10 +1,10 @@
-import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-zDynoew_.js";
+import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-lQDCwNag.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-BSMny7oe.js";
-import { B as CharacterBody3D, F as Water3D, H as RigidBody3D, I as WATER_CUTOUT_MAX, L as WaterCutout3D, U as StaticBody3D, V as PhysicsBody3D, W as Node3D, q as WATER_MAX_RIPPLES, z as Area3D } from "./gameplay-CLgFdkh5.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-D2vzw583.js";
-import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-B746rYbr.js";
+import { G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, R as WATER_CUTOUT_MAX, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, Y as WATER_MAX_RIPPLES, z as WaterCutout3D } from "./gameplay-D1RADWu3.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-BlPsEmq6.js";
+import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-DYJCIzO0.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-BOO58xzw.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-BkHjwJgI.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;

package/dist/{audio-player-D5GJgb_x.d.ts → audio-player-_UAcHxnC.d.ts}

@@ -1,4 +1,4 @@
-import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-DsgayMsH.js";
+import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-BXNLfIJk.js";
 import { a as Rng } from "./schema-CFeioQRE.js";
 
 //#region src/core/particle-sim.d.ts

package/dist/{behavior-DsgayMsH.d.ts → behavior-BXNLfIJk.d.ts}

@@ -1104,6 +1104,51 @@ declare function resolveOrderGroups(declared?: Record<string, number>): OrderGro
 */
 declare function effectiveOrder(group: string, renderOrder: number, table?: OrderGroupTable): number;
 //#endregion
+//#region src/core/physics-query.d.ts
+/** What a ray found: how far, the surface normal, and the body it belongs to. */
+interface RayHit {
+  distance: number;
+  normal: number[];
+  node: Node | null;
+}
+/**
+* The physics world, as core knows it — the QUERIES a behavior asks, with no
+* mention of Rapier or three, so `Engine` can hold one without core learning
+* about either runtime. `Physics2D` and `Physics3D` satisfy it structurally
+* (2D in PIXELS y-down with 2-vectors, 3D in METERS y-up with 3-vectors).
+*
+* This exists because `incanto-physics-and-input.md` has always taught
+* `physics.castRay(origin, dir, maxLen, exclude?)` without ever saying where
+* that `physics` comes from. It lived only on the object `createGame2D/3D()`
+* returns — the BOOT site — so a `Behavior`, which is where AI lives and where
+* line of sight is decided, could not reach it. A stealth game's guard had to
+* cast the private `node._physics` to call a documented API.
+*/
+interface PhysicsQuery {
+  /**
+  * Fire a ray and report the first thing it hits, or `null`.
+  *
+  * Sensors never block a ray. Pass `exclude` for the body you are casting from
+  * — a ray starting inside its own collider hits itself at distance 0.
+  */
+  castRay(origin: readonly number[], dir: readonly number[], maxLen: number, exclude?: Node, opts?: {
+    staticOnly?: boolean;
+  }): RayHit | null;
+  /**
+  * A THICK ray (sphere sweep) — 3D only, hence optional. Use it where skimming
+  * matters: a thin ray that passes 10 cm over a wall reports "clear" while the
+  * wall still fills the frame.
+  */
+  castSphere?(origin: readonly number[], dir: readonly number[], radius: number, maxLen: number, exclude?: Node, opts?: {
+    staticOnly?: boolean;
+  }): {
+    distance: number;
+    node: Node | null;
+  } | null;
+  /** Tear the world down and detach from the engine. */
+  dispose(): void;
+}
+//#endregion
 //#region src/core/save.d.ts
 /**
 * Namespaced game persistence — high scores, unlocks, settings. localStorage
@@ -1576,6 +1621,20 @@ declare class Engine {
   readonly sceneChanged: Signal<[Scene | null]>;
   /** Declarative input — scene `input{}` declarations load on setScene. */
   readonly input: InputMap;
+  /**
+  * The physics world, once something enabled it — `null` in a game that has
+  * none, which is most 2D puzzle games and every menu scene.
+  *
+  * `enablePhysics2D/3D` set this, and `dispose()` clears it. It is the handle
+  * `incanto-physics-and-input.md` has always assumed you had: the skill teaches
+  * `physics.castRay(...)` but the object lived only where the game BOOTED, so
+  * a `Behavior` — where AI lives, and where line of sight is decided — had no
+  * way to reach it short of casting the private `node._physics`.
+  *
+  * Typed as the query surface rather than the concrete class so core never
+  * learns about Rapier or three. From a behavior, prefer `this.physics`.
+  */
+  physics: PhysicsQuery | null;
   /** Seeded randomness for game logic (deterministic when `seed` is set). */
   readonly rng: Rng;
   /** The engine log channel (debug overlay + headless harness tail this). */
@@ -1590,6 +1649,25 @@ declare class Engine {
   * and cleared on dispose; null when nothing renders (headless).
   */
   picker: ((x: number, y: number) => Node | null) | null;
+  /** Frames the engine has stepped — monotonic, and the pick cache's key. */
+  frameNumber: number;
+  /** @internal frame number + answer, so N Clickables cost ONE raycast. */
+  private pickCacheFrame;
+  private pickCacheKey;
+  private pickCacheHit;
+  /**
+  * The node under (x, y), answered at most ONCE per frame per cursor position.
+  *
+  * `Clickable` asks every frame, and a board game has one per cell: 42 pads
+  * measured **420 picker calls over ten frames** — one GPU raycast per pad per
+  * frame, all answering the same question about the same pixel. At 60 fps that
+  * is ~2500 raycasts a second to find out what the cursor is on, and a 200-tile
+  * board was unusable.
+  *
+  * Cached on (frame, x, y), so a game that picks at two different points in one
+  * frame still gets two real answers.
+  */
+  pickAt(x: number, y: number): Node | null;
   /** Global volume buses — `master` × `sfx`/`music` gain + `muted`. AudioPlayer
   *  routes its volume through this; games set it for global volume/mute. */
   readonly audio: AudioBuses;
@@ -1942,8 +2020,44 @@ interface BehaviorCtor {
 * schema/defaults/delta model as node props.
 */
 declare abstract class Behavior {
+  /**
+  * Every behavior accepts `enabled`, inherited down the static chain — see
+  * `enabled` below for why it is a universal prop rather than one each AI
+  * behavior declares for itself.
+  */
   static props?: PropSchema;
   /**
+  * Whether this behavior's `update`/`fixedUpdate` run. `false` stops it
+  * without removing it — and this is what makes ENEMY AI expressible in JSON.
+  *
+  * A node holds ONE behavior, so `Patrol` and `Chase` cannot share one. Both
+  * can ride child nodes with `moveParent`, but then both run at once, and
+  * before this nothing could stop either — so "patrols until it spots you,
+  * then chases", the most ordinary AI there is, had to be hand-written in
+  * TypeScript, which is exactly what the gameplay library exists to prevent.
+  * With this the whole state machine is two wires:
+  *
+  * ```jsonc
+  * { "signal": "spotted", "from": "Eyes", "to": "Walk", "handler": "disable" },
+  * { "signal": "spotted", "from": "Eyes", "to": "Hunt", "handler": "enable"  }
+  * ```
+  *
+  * `Clickable` had already hand-rolled this exact prop for itself. One
+  * behavior needed it and solved it locally; nothing generalized it.
+  *
+  * Asleep is NOT detached: the behavior keeps its props and its accumulated
+  * state, stays reachable as `node.behavior`, keeps its signal connections,
+  * and still saves through `serialize()`. Only the per-frame hooks pause. The
+  * lifecycle hooks (`onEnterTree`/`onReady`/`onExitTree`) are not gated — they
+  * are structural, they fire once, and a behavior that skipped its own
+  * `onReady` would wake up uninitialized.
+  */
+  enabled: boolean;
+  /** Start running again — a connection handler, so a wire can do it. */
+  enable(): void;
+  /** Stop running without being removed — a connection handler. */
+  disable(): void;
+  /**
   * Custom signals this behavior emits via `this.emit(...)` — declared onto
   * its node at load. Undeclared emits are hard errors (typo safety).
   */
@@ -1958,6 +2072,20 @@ declare abstract class Behavior {
   get rng(): Rng;
   /** The engine log channel (visible in the debug overlay and test harness). */
   get log(): LogManager;
+  /**
+  * The physics world, for the queries AI asks — `castRay` for line of sight,
+  * `castSphere` for a probe that must not skim past a wall.
+  *
+  * ```ts
+  * const hit = this.physics?.castRay(eye, dir, range, this.node);
+  * const blocked = hit !== null && hit.node !== player;
+  * ```
+  *
+  * `null` in a game with no physics, so a behavior that only sometimes needs
+  * a ray degrades instead of throwing. Pass the caster as `exclude` — a ray
+  * that starts inside its own collider hits itself at distance 0.
+  */
+  get physics(): PhysicsQuery | null;
   getNode(path: string): Node;
   emit(signal: string, ...args: unknown[]): void;
   on(signal: string, fn: SignalListener<unknown[]>, opts?: {

package/dist/{create-game-B746rYbr.js → create-game-DYJCIzO0.js}

@@ -1,14 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { c as parseEnvironment3D, k as diagnose, n as loadScene, s as horizonColorFromSky, u as sunDirectionFromSky, z as registerBehavior } from "./loader-zDynoew_.js";
-import { C as qualityRendering, _ as AudioPlayer, v as Engine, x as qualityCaps } from "./register-Btm7_Emq.js";
+import { c as parseEnvironment3D, k as diagnose, n as loadScene, s as horizonColorFromSky, u as sunDirectionFromSky, z as registerBehavior } from "./loader-lQDCwNag.js";
+import { C as qualityRendering, _ as AudioPlayer, v as Engine, x as qualityCaps } from "./register-BmuqYTiY.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
-import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-BwhkcNt8.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-byR9USax.js";
 import { o as frameStats } from "./frame-report-BSMny7oe.js";
-import { K as createCausticsQuad, V as PhysicsBody3D, W as Node3D, n as registerGameplayBehaviors } from "./gameplay-CLgFdkh5.js";
+import { J as createCausticsQuad, K as Node3D, U as PhysicsBody3D, n as registerGameplayBehaviors } from "./gameplay-D1RADWu3.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-D2vzw583.js";
-import { n as enablePhysics3D } from "./physics-3d-BOO58xzw.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-BlPsEmq6.js";
+import { n as enablePhysics3D } from "./physics-3d-BkHjwJgI.js";
 import { ACESFilmicToneMapping, AmbientLight, Box3, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, HalfFloatType, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
@@ -1967,6 +1967,67 @@ var Renderer3D = class {
 		};
 	}
 	/**
+	* The WORLD POINT under canvas pixel (sx, sy) — the other half of
+	* `screenFromWorld`, and the call `incanto-web-integration.md` has always
+	* offered "for taps and clicks".
+	*
+	* It did not exist in 3D. `Renderer2D` has had it since the beginning, the
+	* doc covers both runtimes, and an agent building a tower defense went looking
+	* for it and measured `typeof game.renderer.worldFromScreen === "undefined"`.
+	* `pick()` gives you the NODE under a pixel but never the POINT, so "put the
+	* thing where the player clicked on the ground" was not expressible and that
+	* game discretised its whole map into clickable pads instead.
+	*
+	* A pixel in 3D is a RAY, not a point, so this needs a surface to land on and
+	* takes the horizontal plane at `planeY` (default 0 — the ground). Returns
+	* null when the ray runs parallel to that plane or would only meet it behind
+	* the camera, which is what "the sky" looks like from here.
+	*
+	* For anything not flat — terrain, a hillside, a stack of crates — raycast
+	* physics instead: `rayFromScreen` gives you the origin and direction to feed
+	* `physics.castRay`.
+	*/
+	worldFromScreen(sx, sy, planeY = 0) {
+		const ray = this.rayFromScreen(sx, sy);
+		if (!ray) return null;
+		const dy = ray.dir[1];
+		if (Math.abs(dy) < 1e-6) return null;
+		const t = (planeY - ray.origin[1]) / dy;
+		if (t < 0) return null;
+		return {
+			x: ray.origin[0] + ray.dir[0] * t,
+			y: planeY,
+			z: ray.origin[2] + ray.dir[2] * t
+		};
+	}
+	/**
+	* The camera ray through canvas pixel (sx, sy) — origin and unit direction,
+	* ready for `physics.castRay(origin, dir, maxLen)`.
+	*
+	* This is the honest 3D answer to "where did the player click": on uneven
+	* ground the only thing that knows is the collision world.
+	*/
+	rayFromScreen(sx, sy) {
+		const cam = this.lastCamera;
+		if (!cam) return null;
+		pickNdc.set(sx / this.lastSize.w * 2 - 1, -(sy / this.lastSize.h * 2 - 1));
+		pickRaycaster.setFromCamera(pickNdc, cam);
+		const o = pickRaycaster.ray.origin;
+		const d = pickRaycaster.ray.direction;
+		return {
+			origin: [
+				o.x,
+				o.y,
+				o.z
+			],
+			dir: [
+				d.x,
+				d.y,
+				d.z
+			]
+		};
+	}
+	/**
 	* The node rendered under canvas pixel (sx, sy), or null — raycasts the last
 	* rendered camera into the scene and resolves the hit up to its `incantoNode`
 	* (every Node3D stamps that in `_ensureObject3D`). 3D depth-sorts, so the

package/dist/{create-game-B1KM6dA6.js → create-game-Dd7H4bJV.js}

@@ -1,14 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { d as computeViewport, f as resolveViewport, k as diagnose, n as loadScene, z as registerBehavior } from "./loader-zDynoew_.js";
-import { _ as AudioPlayer, v as Engine } from "./register-Btm7_Emq.js";
+import { d as computeViewport, f as resolveViewport, k as diagnose, n as loadScene, z as registerBehavior } from "./loader-lQDCwNag.js";
+import { _ as AudioPlayer, v as Engine } from "./register-BmuqYTiY.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
-import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-BwhkcNt8.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-byR9USax.js";
 import { o as frameStats } from "./frame-report-BSMny7oe.js";
-import { n as registerGameplayBehaviors } from "./gameplay-CLgFdkh5.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-dGsbnJ87.js";
+import { n as registerGameplayBehaviors } from "./gameplay-D1RADWu3.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-D0CxCveZ.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-BPJcJRRP.js";
+import { n as enablePhysics2D } from "./physics-2d-Cji5A6sX.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**

package/dist/debug.d.ts

@@ -1,4 +1,4 @@
-import { Ft as LogLevel, T as RendererStats, b as Engine } from "./behavior-DsgayMsH.js";
+import { Ft as LogLevel, T as RendererStats, b as Engine } from "./behavior-BXNLfIJk.js";
 
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */

package/dist/{duplicate-BOOKmkQ7.js → duplicate-CqSAtdrh.js}

@@ -1,4 +1,4 @@
-import { a as serializeNode, t as buildNodeJson } from "./loader-zDynoew_.js";
+import { a as serializeNode, t as buildNodeJson } from "./loader-lQDCwNag.js";
 //#region src/core/scene/duplicate.ts
 function stripUids(json) {
 	const { uid: _uid, ...rest } = json;