incanto 0.65.0 → 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-CmMuQ6CL.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-CTB441z4.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-BrEHwbK1.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-DIyh5Zy9.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-DO5_Qp0Q.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CmnunaR2.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-CmMuQ6CL.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-CTB441z4.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-BrEHwbK1.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-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-D-H986A4.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-BvHs6HEk.js";
-import { a as Environment3D, i as syncTree, o as setEnvironment3D, r as Renderer3D, s as AssetStore3D, t as createGame3D } from "./create-game-W2xzTJhs.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-DULB1lD1.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-BrEHwbK1.d.ts → audio-player-_UAcHxnC.d.ts}

@@ -1,4 +1,4 @@
-import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-CmMuQ6CL.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-CmMuQ6CL.d.ts → behavior-BXNLfIJk.d.ts}

@@ -1649,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;

package/dist/{create-game-W2xzTJhs.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-lQDCwNag.js";
-import { C as qualityRendering, _ as AudioPlayer, v as Engine, x as qualityCaps } from "./register-CgeR4ckF.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-BordHL9o.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-D-H986A4.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-BvHs6HEk.js";
-import { n as enablePhysics3D } from "./physics-3d-DULB1lD1.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-DIyh5Zy9.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-lQDCwNag.js";
-import { _ as AudioPlayer, v as Engine } from "./register-CgeR4ckF.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-BordHL9o.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-D-H986A4.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DO5_Qp0Q.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-CmnunaR2.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-CmMuQ6CL.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/{environment-presets-BvHs6HEk.js → environment-presets-BlPsEmq6.js}

@@ -1,11 +1,11 @@
 import { k as diagnose } from "./loader-lQDCwNag.js";
-import { L as translateOn, t as registerCoreNodes } from "./register-CgeR4ckF.js";
+import { L as translateOn, t as registerCoreNodes } from "./register-BmuqYTiY.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-CF70EArN.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-CY-mrr1L.js";
-import { B as CharacterBody3D, F as Water3D, H as RigidBody3D, J as colliderFootDrop, L as WaterCutout3D, R as rejectScale, U as StaticBody3D, V as PhysicsBody3D, W as Node3D, w as tolerateUnknownAction, z as Area3D } from "./gameplay-D-H986A4.js";
+import { B as rejectScale, G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, X as colliderFootDrop, w as tolerateUnknownAction, z as WaterCutout3D } from "./gameplay-D1RADWu3.js";
 import { t as checkSheetGrid } from "./sheet-grid-BT6N_Bjs.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
@@ -742,7 +742,8 @@ var Joint3D = class extends Node3D {
 		] },
 		length: { default: 0 },
 		stiffness: { default: 50 },
-		damping: { default: 5 }
+		damping: { default: 5 },
+		collide: { default: null }
 	};
 	type = "spherical";
 	target = "";
@@ -760,6 +761,31 @@ var Joint3D = class extends Node3D {
 	length = 0;
 	stiffness = 50;
 	damping = 5;
+	/**
+	* 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 = null;
 	onEnterTree() {
 		if (!(this.parent instanceof PhysicsBody3D)) throw new IncantoError("TREE_VIOLATION", `Joint3D '${this.name}' must be a child of a physics body (its body A); parent is '${this.parent?.name ?? "none"}'.`);
 		if (this.target === "") throw new IncantoError("BAD_FORMAT", `Joint3D '${this.name}' needs a "target" node path to the body it links to.`);
@@ -2641,6 +2667,7 @@ var CharacterController3D = class extends Node3D {
 		/** Gravity multiplier while falling — >1 is the "snappy" arc. */
 		fallGravity: { default: 2.5 },
 		floatHeight: { default: .01 },
+		stepHeight: { default: .35 },
 		mouseLook: { default: true },
 		zoomMin: { default: 0 },
 		zoomMax: { default: 0 },
@@ -2673,6 +2700,25 @@ var CharacterController3D = class extends Node3D {
 	airControl = .2;
 	fallGravity = 2.5;
 	floatHeight = .01;
+	/**
+	* 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 = .35;
 	mouseLook = true;
 	zoomMin = 0;
 	zoomMax = 0;
@@ -2803,8 +2849,26 @@ var CharacterController3D = class extends Node3D {
 			0,
 			-vel[2] * DRAG_DAMPING * mass
 		]);
-		if (toi !== null && toi < floatingDis * 2 && !this.jumping) {
-			const spring = SPRING_K * (floatingDis - toi) - vel[1] * SPRING_DAMPING;
+		let springToi = toi;
+		if (this.stepHeight > 0 && moving && toi !== null && !this.jumping && (vel[1] ?? 0) <= .5) {
+			const ahead = radius + .12;
+			const probeTop = originY + this.stepHeight + .05;
+			const stepHit = physics.castRay([
+				pos[0] + mx * ahead,
+				probeTop,
+				pos[2] + mz * ahead
+			], [
+				0,
+				-1,
+				0
+			], this.stepHeight + .05 + rayLen, body);
+			if (stepHit) {
+				const rise = probeTop - stepHit.distance - (originY - toi);
+				if (rise > .02 && rise <= this.stepHeight + .02) springToi = toi - rise;
+			}
+		}
+		if (springToi !== null && springToi < floatingDis * 2 && !this.jumping) {
+			const spring = SPRING_K * (floatingDis - springToi) - vel[1] * SPRING_DAMPING;
 			body.applyImpulse([
 				0,
 				spring * mass,