incanto 0.47.0 → 0.49.0

package/dist/3d.js

@@ -1,9 +1,9 @@
-import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-BQOeAid6.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-D1b0ydTS.js";
-import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-D16MVIPO.js";
+import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-02Btmmjn.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-CZOH5TY5.js";
+import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-DFBjMetZ.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-njybhZon.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CSoGjM8P.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DpRqw8Mz.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;
@@ -25,6 +25,115 @@ function rigOf(facts) {
 	if (facts.nodes.some((n) => MIXAMO.test(n.name))) return "mixamorig";
 	return facts.skins > 0 ? "other" : "none";
 }
+/**
+* The locomotion clips every mixamorig character can play as they are.
+*
+* They are not art you go looking for — they are the rig's vocabulary, they
+* retarget onto anything mixamo-shaped (and through the humanoid map onto a
+* VRM), and this repo's own examples reference them 29 times. Nothing shipped
+* ever told an agent where they live, so a character found through an asset MCP
+* arrived with no way to walk.
+*
+* Keyed by the states `CharacterController3D` emits, so the map below IS the
+* controller's `animations` prop.
+*/
+const CLIP_BASE = "https://agent8-games.verse8.io/assets/3d/animations/mixamorig";
+const LOCOMOTION_CLIPS = {
+	idle: `${CLIP_BASE}/idle-00.glb`,
+	walk: `${CLIP_BASE}/walk.glb`,
+	run: `${CLIP_BASE}/run-medium.glb`,
+	fastRun: `${CLIP_BASE}/run-fast.glb`,
+	airborne: `${CLIP_BASE}/jump.glb`
+};
+/** The capsule the shipped templates use, and the skin fitted to it. */
+const BODY = {
+	radius: .34,
+	height: 1
+};
+/**
+* A found character, as a thing that walks.
+*
+* The model alone draws a statue: `CharacterController3D` must sit under a
+* dynamic body, the skin has to be sized to the capsule and dropped to its
+* feet, the clips have to be declared, and the input actions have to exist or
+* nothing reads the keyboard. Every one of those is a documented step and all
+* of them are needed at once, which is exactly the shape of thing worth
+* printing rather than describing.
+*/
+function characterJson(target) {
+	const assets = { [target.key]: {
+		type: "model",
+		url: target.url
+	} };
+	const animations = {};
+	for (const [state, url] of Object.entries(LOCOMOTION_CLIPS)) {
+		const key = `anims/${state}`;
+		assets[key] = {
+			type: "animation",
+			url
+		};
+		animations[state] = `$${key}`;
+	}
+	return {
+		assets,
+		input: {
+			move: {
+				type: "vector2",
+				keys: {
+					up: ["KeyW"],
+					down: ["KeyS"],
+					left: ["KeyA"],
+					right: ["KeyD"]
+				}
+			},
+			jump: {
+				type: "button",
+				keys: ["Space"]
+			},
+			sprint: {
+				type: "button",
+				keys: ["ShiftLeft"]
+			}
+		},
+		node: {
+			name: "Player",
+			type: "RigidBody3D",
+			groups: ["player"],
+			props: {
+				fixedRotation: true,
+				friction: 0,
+				collider: {
+					shape: "capsule",
+					radius: BODY.radius,
+					height: BODY.height
+				}
+			},
+			children: [{
+				name: "Controller",
+				type: "CharacterController3D",
+				props: {
+					view: "free",
+					coyoteSeconds: .12,
+					jumpBufferSeconds: .15,
+					animations
+				}
+			}, {
+				name: "Skin",
+				type: "ModelInstance3D",
+				props: {
+					model: `$${target.key}`,
+					targetHeight: BODY.height + 2 * BODY.radius,
+					position: [
+						0,
+						-(BODY.height / 2 + BODY.radius),
+						0
+					],
+					castShadow: true
+				}
+			}]
+		}
+	};
+}
 function modelVerdict(facts, target) {
 	const rig = rigOf(facts);
 	const kind = facts.meshes === 0 && facts.animations.length > 0 ? "animation" : "model";
@@ -51,6 +160,7 @@ function modelVerdict(facts, target) {
 		originOffset: offset,
 		groundedAtOrigin: grounded,
 		embeddedClips: facts.animations.map((a) => a.name),
+		characterJson: target && kind === "model" && (rig === "mixamorig" || rig === "vrm-humanoid") ? characterJson(target) : null,
 		sceneJson: target ? {
 			assets: { [target.key]: {
 				type: kind,

package/dist/{create-game-CniOiWzN.js → create-game-BgV6UbVA.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { n as loadScene, o as computeViewport, s as resolveViewport, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
-import { h as Engine, m as AudioPlayer } from "./register-BSXV8T9F.js";
+import { n as loadScene, o as computeViewport, s as resolveViewport, v as diagnose, w as registerBehavior } from "./loader-DwazzlQb.js";
+import { h as Engine, m as AudioPlayer } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, r as crossFade, t as teardown } from "./teardown-BKTCzLek.js";
-import { n as registerGameplayBehaviors } from "./gameplay-BQOeAid6.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-R2JTnIMw.js";
+import { n as registerGameplayBehaviors } from "./gameplay-02Btmmjn.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-BNPZYJmd.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-BmgXBNDB.js";
+import { n as enablePhysics2D } from "./physics-2d-vyCBfACH.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/{create-game-D16MVIPO.js → create-game-DFBjMetZ.js}

@@ -1,14 +1,15 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { n as loadScene, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
-import { _ as qualityCaps, h as Engine, m as AudioPlayer, y as qualityRendering } from "./register-BSXV8T9F.js";
+import { n as loadScene, v as diagnose, w as registerBehavior } from "./loader-DwazzlQb.js";
+import { _ as qualityCaps, h as Engine, m as AudioPlayer, y as qualityRendering } from "./register-uvaZj1KX.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { r as parseDrive, t as logReport } from "./log-report-lxrQY9cH.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, t as teardown } from "./teardown-BKTCzLek.js";
-import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-BQOeAid6.js";
+import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-02Btmmjn.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-D1b0ydTS.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-CZOH5TY5.js";
 import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-njybhZon.js";
-import { n as enablePhysics3D } from "./physics-3d-CSoGjM8P.js";
+import { n as enablePhysics3D } from "./physics-3d-DpRqw8Mz.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";
@@ -2455,17 +2456,69 @@ async function createGame3D(opts) {
 		if (!capture) throw new IncantoError("TREE_VIOLATION", "this renderer cannot capture frames");
 		return capture.call(renderer);
 	};
+	/**
+	* Run a drive script against the LIVE game, in real time.
+	*
+	* `step` waits on the wall clock rather than advancing a fixed timestep: this
+	* is the running game, with its own loop, its own physics and its own
+	* animation. Stepping it by hand would fight all three.
+	*/
+	const applyDrive = async (steps) => {
+		let frames = 0;
+		let watching = true;
+		const tick = () => {
+			if (!watching) return;
+			frames += 1;
+			requestAnimationFrame(tick);
+		};
+		requestAnimationFrame(tick);
+		for (const s of steps) switch (s.kind) {
+			case "press":
+				engine.input.pressAction(s.action);
+				break;
+			case "release":
+				engine.input.releaseAction(s.action);
+				break;
+			case "vector":
+				engine.input.setActionVector(s.action, s.x, s.y);
+				break;
+			case "key":
+				engine.input.handleKey(s.code, s.down);
+				break;
+			case "pointer":
+				engine.input.handlePointerMove(s.dx, s.dy);
+				break;
+			case "step":
+				await new Promise((r) => setTimeout(r, s.ms));
+				break;
+		}
+		watching = false;
+		return frames;
+	};
 	const hot = import.meta.hot;
 	if (hot) {
 		const onFrameRequest = (data) => {
 			const request = data;
 			const id = request?.id;
 			hot.send("incanto:frame-ack", { id });
-			captureFramePixels().then((shot) => hot.send("incanto:frame-report", {
+			const drive = request?.drive ? parseDrive(request.drive) : null;
+			if (drive?.error) {
+				hot.send("incanto:frame-report", {
+					id,
+					report: { error: drive.error }
+				});
+				return;
+			}
+			let droveFrames = null;
+			(drive ? applyDrive(drive.steps) : Promise.resolve(null)).then((frames) => {
+				droveFrames = frames;
+				return captureFramePixels();
+			}).then((shot) => hot.send("incanto:frame-report", {
 				id,
 				report: {
 					...frameStats(shot.pixels, shot.width, shot.height, { grid: request?.grid }),
 					signature: frameSignature(shot.pixels, shot.width, shot.height),
+					...droveFrames === null ? {} : { droveFrames },
 					...request?.image ? { image: frameImage(shot.pixels, shot.width, shot.height, (w, h) => Object.assign(document.createElement("canvas"), {
 						width: w,
 						height: h
@@ -2478,6 +2531,30 @@ async function createGame3D(opts) {
 		};
 		hot.on("incanto:frame-request", onFrameRequest);
 		cleanups.push(() => hot.off?.("incanto:frame-request", onFrameRequest));
+		const onLogsRequest = (data) => {
+			const id = data?.id;
+			try {
+				hot.send("incanto:logs-report", {
+					id,
+					report: logReport({
+						entries: engine.log.entries(),
+						stats: {
+							...engine.stats(),
+							...renderer.stats?.() ?? {}
+						},
+						assetErrors: renderer.assets?.errors() ?? [],
+						hidden: typeof document !== "undefined" && document.hidden
+					})
+				});
+			} catch (error) {
+				hot.send("incanto:logs-report", {
+					id,
+					report: { error: error instanceof Error ? error.message : String(error) }
+				});
+			}
+		};
+		hot.on("incanto:logs-request", onLogsRequest);
+		cleanups.push(() => hot.off?.("incanto:logs-request", onLogsRequest));
 	}
 	cleanups.push(pauseWhenHidden(engine));
 	await report(1, "ready");

package/dist/{duplicate-CRtihGmC.js → duplicate-CI9WF_bg.js}

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

package/dist/{environment-presets-D1b0ydTS.js → environment-presets-CZOH5TY5.js}

@@ -1,10 +1,10 @@
-import { t as registerCoreNodes } from "./register-BSXV8T9F.js";
+import { t as registerCoreNodes } from "./register-uvaZj1KX.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-IyWCGe4q.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
-import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-Bw7hB93B.js";
-import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-BQOeAid6.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-D_p28jwU.js";
+import { A as Water3D, F as PhysicsBody3D, H as colliderFootDrop, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D } from "./gameplay-02Btmmjn.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";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
@@ -2112,13 +2112,19 @@ var AnimatedSprite3D = class extends Sprite3D {
 	frameList = [];
 	frameIndex = 0;
 	frameTime = 0;
+	currentDef = null;
 	sheetTexture = null;
 	loadedSheetRef = "";
+	/**
+	* `currentAnimation` reports the clip that is RUNNING, not the name asked
+	* for: an alias is a rename, and a state machine that reads back `fall` while
+	* the idle frames play is describing something that is not happening.
+	*/
 	play(name) {
-		const def = this.animations[name];
-		if (!def) throw new IncantoError("UNKNOWN_ANIMATION", `No animation '${name}' on '${this.name}'. Available: [${Object.keys(this.animations).join(", ")}].`);
-		this.currentAnimation = name;
-		this.frameList = resolveFrames(def.frames, name);
+		const { name: resolved, def } = resolveAnimation(this.animations, name, this.name);
+		this.currentAnimation = resolved;
+		this.currentDef = def;
+		this.frameList = resolveFrames(def.frames, resolved);
 		this.frameIndex = 0;
 		this.currentFrame = this.frameList[0] ?? 0;
 		this.frameTime = 0;
@@ -2128,11 +2134,12 @@ var AnimatedSprite3D = class extends Sprite3D {
 		this.playing = false;
 	}
 	onReady() {
+		validateAnimationAliases(this.animations, this.name);
 		if (this.autoplay) this.play(this.autoplay);
 	}
 	update(dt) {
 		if (!this.playing || this.currentAnimation === "") return;
-		const def = this.animations[this.currentAnimation];
+		const def = this.currentDef;
 		if (!def || !Number.isFinite(def.fps) || def.fps <= 0) return;
 		const perFrame = 1 / def.fps;
 		this.frameTime += dt;
@@ -2173,18 +2180,6 @@ var AnimatedSprite3D = class extends Sprite3D {
 		super.free();
 	}
 };
-function resolveFrames(frames, name) {
-	if (!Array.isArray(frames) || frames.length === 0) throw new IncantoError("BAD_FORMAT", `Animation '${name}': "frames" must be a non-empty array.`);
-	if (frames.length === 2) {
-		const [start, end] = frames;
-		if (end >= start) {
-			const out = [];
-			for (let f = start; f <= end; f++) out.push(f);
-			return out;
-		}
-	}
-	return [...frames];
-}
 //#endregion
 //#region src/3d/nodes/billboard-3d.ts
 const _parentQ = new Quaternion();

package/dist/{gameplay-BQOeAid6.js → gameplay-02Btmmjn.js}

@@ -1,7 +1,7 @@
-import { f as Node, h as effectiveOrder, n as loadScene, w as registerBehavior, y as Behavior } from "./loader-r49nDwB4.js";
+import { f as Node, h as effectiveOrder, n as loadScene, w as registerBehavior, y as Behavior } from "./loader-DwazzlQb.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as jsonClone } from "./json-BLk7H2Qa.js";
-import { t as duplicateNode } from "./duplicate-CRtihGmC.js";
+import { t as duplicateNode } from "./duplicate-CI9WF_bg.js";
 import { Color, CubeCamera, DepthTexture, DoubleSide, Euler, FloatType, Frustum, HalfFloatType, LinearMipmapLinearFilter, MathUtils, Matrix4, Mesh, MeshDepthMaterial, Object3D, PerspectiveCamera, Plane, PlaneGeometry, Quaternion, ShaderMaterial, Sphere, Vector2, Vector3, Vector4, WebGLCubeRenderTarget, WebGLRenderTarget } from "three";
 //#region src/3d/frustum.ts
 const scratchFrustum = new Frustum();
@@ -2553,7 +2553,7 @@ var CharacterBody3D = class extends PhysicsBody3D {
 			0,
 			0
 		] },
-		snapToGround: { default: true },
+		stickToGround: { default: true },
 		slopeLimitDeg: { default: 45 }
 	};
 	/** m/s, y-up (up = +y). */
@@ -2562,9 +2562,30 @@ var CharacterBody3D = class extends PhysicsBody3D {
 		0,
 		0
 	];
-	snapToGround = true;
+	/**
+	* Hold the capsule against the surface while it moves, so walking down a
+	* slope does not become a series of small falls.
+	*
+	* Named apart from `Node3D.snapToGround` (which PLACES a node on the ground
+	* at load) because sharing the name silently broke both: the boolean shadowed
+	* the placement prop, its `true` default made the placement pass teleport
+	* every character body in a terrain scene, and a lift value was rejected
+	* outright — so the only escape from the teleport also turned this off.
+	*/
+	stickToGround = true;
 	/** Max climbable slope angle. */
 	slopeLimitDeg = 45;
+	/**
+	* `snapToGround` on a character body is ambiguous, so it is refused.
+	*
+	* A boolean here used to mean the ground-stick, and as placement it means
+	* "leave y alone" — which is already the default. Rather than pick one and
+	* silently do the other thing to an existing scene, say which prop was meant.
+	*/
+	onReady() {
+		if (typeof this.snapToGround === "boolean") throw new IncantoError("PROP_TYPE_MISMATCH", `'${this.getPath()}' sets snapToGround to a boolean. On a character body that is ambiguous: 'stickToGround' holds the capsule against the surface while it moves (default true), while 'snapToGround' PLACES the node on the ground at load and takes a lift in metres (e.g. 0.8) — omit it to leave y exactly as authored.`, { prop: "snapToGround" });
+		super.onReady();
+	}
 	/** @internal Updated by Physics3D.moveAndSlide. */
 	_grounded = false;
 	moveAndSlide() {
@@ -4553,7 +4574,8 @@ var Health = class extends Behavior {
 	static signals = [
 		"damaged",
 		"healed",
-		"died"
+		"died",
+		"healthChanged"
 	];
 	max = 100;
 	regenPerSec = 0;
@@ -4602,13 +4624,29 @@ var Health = class extends Behavior {
 		this.setCurrent(0);
 		this.die();
 	}
+	/**
+	* The one funnel every change goes through — and therefore the one place a
+	* HUD can be told about.
+	*
+	* `damaged`/`healed` both lead with the DELTA, which is the number a bar must
+	* not show; wire either to `UiBar.setValue` and the bar paints the damage as
+	* the health and looks like it works. Regeneration is worse: it moves
+	* `current` through here and emits NEITHER, so a regen bar sat still while
+	* the character healed. `healthChanged(current, max)` carries the max too, so
+	* a raised ceiling needs no second wire.
+	*
+	* Silent when nothing moved: a bar that repaints on nothing is noise.
+	*/
 	setCurrent(value) {
-		this.current = Math.max(0, Math.min(this.max, value));
+		const next = Math.max(0, Math.min(this.max, value));
+		if (next === this.current) return;
+		this.current = next;
+		this.emit("healthChanged", this.current, this.max);
 	}
 	die() {
 		if (this.dead) return;
 		this.dead = true;
-		this.current = 0;
+		this.setCurrent(0);
 		this.emit("died");
 		if (this.freeOnDeath) this.node.queueFree();
 	}
@@ -5675,6 +5713,10 @@ var Patrol = class extends Behavior {
 * On overlap with a node in `collectorGroup`, emits `collected(value, other)`
 * then `queueFree()`s itself. Wire `collected → ScoreKeeper.addScore` (the
 * value is the first arg) or `collected → Collector.collect`.
+*
+* `other` is the ENTITY, not whichever of its parts touched — see
+* {@link findCollector}. A player is a body with children (a reach sensor, a
+* hitbox), and the part that enters first is rarely the part carrying the group.
 */
 var Pickup = class extends Behavior {
 	static props = {
@@ -5695,12 +5737,41 @@ var Pickup = class extends Behavior {
 	}
 	tryCollect(other) {
 		if (this.collectedAlready) return;
-		if (!other.isInGroup(this.collectorGroup)) return;
+		const collector = findCollector(other, this.collectorGroup);
+		if (!collector) return;
 		this.collectedAlready = true;
-		this.emit("collected", this.value, other);
+		this.emit("collected", this.value, collector);
 		this.node.queueFree();
 	}
 };
+/**
+* The entity in `group` that this contact belongs to, or null.
+*
+* The same search `DamageOnContact` has always used for `Health` — the
+* contacted node, its descendants, then the ancestor CHAIN — and for the same
+* reason. An entity is a body with children (a reach sensor, a hitbox, a skin),
+* the group sits on one node of it, and whichever part happens to touch first
+* is rarely that node.
+*
+* Matching the literal entering node was a silent failure in exactly the shape
+* the gameplay skill recommends: a player with a `Grab` area collected almost
+* nothing, because the sensor is wider than the body and entered first. Five
+* pickups fired `triggerEnter`; one fired `collected`.
+*
+* The ancestor climb deliberately does NOT descend into siblings: past a shared
+* parent every other entity hangs off it too, and a coin would be collected by
+* a crate standing next to the player.
+*/
+function findCollector(node, group) {
+	const queue = [node];
+	while (queue.length > 0) {
+		const n = queue.shift();
+		if (n.isInGroup(group)) return n;
+		queue.push(...n.children);
+	}
+	for (let n = node.parent; n; n = n.parent) if (n.isInGroup(group)) return n;
+	return null;
+}
 //#endregion
 //#region src/gameplay/projectile.ts
 /**

package/dist/gameplay.d.ts

@@ -97,6 +97,19 @@ declare class Health extends Behavior {
   heal(n: number): void;
   /** Drop to 0 and die immediately (ignores i-frames). */
   kill(): void;
+  /**
+  * The one funnel every change goes through — and therefore the one place a
+  * HUD can be told about.
+  *
+  * `damaged`/`healed` both lead with the DELTA, which is the number a bar must
+  * not show; wire either to `UiBar.setValue` and the bar paints the damage as
+  * the health and looks like it works. Regeneration is worse: it moves
+  * `current` through here and emits NEITHER, so a regen bar sat still while
+  * the character healed. `healthChanged(current, max)` carries the max too, so
+  * a raised ceiling needs no second wire.
+  *
+  * Silent when nothing moved: a bar that repaints on nothing is noise.
+  */
   private setCurrent;
   private die;
   /** Current HP and whether death already fired — `max` comes back from JSON. */
@@ -318,6 +331,10 @@ declare class Patrol extends Behavior {
 * On overlap with a node in `collectorGroup`, emits `collected(value, other)`
 * then `queueFree()`s itself. Wire `collected → ScoreKeeper.addScore` (the
 * value is the first arg) or `collected → Collector.collect`.
+*
+* `other` is the ENTITY, not whichever of its parts touched — see
+* {@link findCollector}. A player is a body with children (a reach sensor, a
+* hitbox), and the part that enters first is rarely the part carrying the group.
 */
 declare class Pickup extends Behavior {
   static readonly props: PropSchema;

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, k as Chase, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DayNight, x as goToScene, y as Interactable } from "./gameplay-BQOeAid6.js";
+import { C as FollowCamera, D as Health, E as DamageOnContact, O as Collector, S as restartScene, T as phaseOf, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, k as Chase, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DayNight, x as goToScene, y as Interactable } from "./gameplay-02Btmmjn.js";
 export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, DayNight, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, phaseOf, registerGameplayBehaviors, restartScene, screenFlash };