incanto 0.69.0 → 0.70.0

package/dist/{register-DbVArsns.js → register-Bkk0wSDB.js}

@@ -1,10 +1,9 @@
-import { O as Node, k as diagnose, w as effectiveOrder } from "./loader-DZE7B07H.js";
-import { L as translateOn, t as registerCoreNodes } from "./register-mmfugpaQ.js";
+import { K as Node, M as effectiveOrder, q as diagnose } from "./save-slots-BXVg148r.js";
+import { M as translateOn, t as registerCoreNodes } from "./register-6DYnKZcy.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 { 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 { F as localFromWorld, I as worldPosition } from "./gameplay-D1KixWK8.js";
+import { c as getNodeSchema, h as didYouMean, p as registerNode } from "./touch-BnCyPA0G.js";
+import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimations, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-CqR2o3SA.js";
+import { E as effectRng, X as localFromWorld, Z as worldPosition, w as tolerateUnknownAction } from "./gameplay-BfHkuzVb.js";
 import { t as checkSheetGrid } from "./sheet-grid-Cea343VO.js";
 import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, MathUtils, Matrix4, Mesh, MeshBasicMaterial, NearestFilter, NormalBlending, Object3D, PlaneGeometry, SRGBColorSpace } from "three";
 //#region src/2d/physics/collider-validate.ts
@@ -14,8 +13,31 @@ import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color
 * not minutes later when physics starts. An EMPTY collider is fine: a body
 * without a collider is a work-in-progress node, not an error.
 */
+/**
+* Every key a 2D collider may carry.
+*
+* The shape was checked thoroughly and everything else let through, so
+* `{"shape": "circle", "radius": 8, "offest": [0, -24]}` loaded clean with its
+* hitbox at the body's origin — the exact defect `verify:playable` was written
+* for after it found hitboxes 155 px behind their own bodies in a starter.
+*/
+const COLLIDER_KEYS_2D = [
+	"shape",
+	"size",
+	"radius",
+	"height",
+	"offset",
+	"oneWay"
+];
 function validateCollider2D(collider, nodeName) {
 	const shape = collider.shape;
+	for (const key of Object.keys(collider)) {
+		if (COLLIDER_KEYS_2D.includes(key)) continue;
+		throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}' has an unknown key "${key}".` + didYouMean(key, COLLIDER_KEYS_2D) + ` A collider is [${COLLIDER_KEYS_2D.join(", ")}] — friction, restitution and mass are props of the BODY, not of its collider.`, {
+			prop: key,
+			validOptions: [...COLLIDER_KEYS_2D]
+		});
+	}
 	if (shape === void 0) return;
 	if (collider.oneWay !== void 0 && typeof collider.oneWay !== "boolean") throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}': "oneWay" must be a boolean (platforms you jump up through), got ${JSON.stringify(collider.oneWay)}.`);
 	if (shape === "rect") {
@@ -227,7 +249,7 @@ var Area2D = class extends PhysicsBody2D {
 	* 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) {
+	overlapping(group = void 0) {
 		const all = this._physics?.overlapping(this) ?? [];
 		return group === void 0 ? all : all.filter((n) => n.isInGroup(group));
 	}
@@ -241,7 +263,8 @@ var RigidBody2D = class extends PhysicsBody2D {
 		fixedRotation: { default: false },
 		friction: { default: .5 },
 		restitution: { default: 0 },
-		linearVelocity: { default: [0, 0] }
+		linearVelocity: { default: [0, 0] },
+		angularVelocity: { default: 0 }
 	};
 	mass = 1;
 	gravityScale = 1;
@@ -250,6 +273,44 @@ var RigidBody2D = class extends PhysicsBody2D {
 	restitution = 0;
 	/** px/s, y-down. Read back every step; write to launch. */
 	linearVelocity = [0, 0];
+	/**
+	* rad/s about the z axis — the same sign as `rotation`, which is CLOCKWISE
+	* in this y-down space. Read back every step; write to spin.
+	*
+	* `RigidBody3D` got its `angularVelocity` because "a puzzle builder could
+	* neither launch a spinning body nor read how fast a lever was swinging —
+	* only its angle, differenced by hand". Same sentence, same defect, other
+	* adapter: 2D had `linearVelocity` and no counterpart. `fixedRotation` pins
+	* it at zero.
+	*/
+	angularVelocity = 0;
+	/**
+	* The other name for `linearVelocity`, because it is the name every skill,
+	* every sibling node and every other engine uses.
+	*
+	* `body.velocity = [0, -400]` is what `incanto-physics-and-input.md` taught
+	* for years. On a plain TS class that assignment SUCCEEDS — it just writes a
+	* stray field nothing reads — so a jump that never happened produced no
+	* error, no warning and nothing to search for. `CharacterBody2D.velocity`
+	* next to `RigidBody2D.linearVelocity` is the kind of near-miss a builder
+	* cannot be expected to notice.
+	*
+	* Scene JSON still names the prop `linearVelocity` and rejects `velocity`
+	* loudly, with the valid keys listed — a hard error corrects itself.
+	*/
+	get velocity() {
+		return this.linearVelocity;
+	}
+	set velocity(v) {
+		this.linearVelocity = v;
+	}
+	/**
+	* Impulse in px·kg/s (y-down) — the 3D twin has had this since it shipped,
+	* and calling it here was a TypeError.
+	*/
+	applyImpulse(impulse) {
+		this._physics?.applyImpulse(this, impulse);
+	}
 };
 /**
 * Kinematic body on Rapier's character controller. Gravity is NOT applied
@@ -261,7 +322,11 @@ var CharacterBody2D = class extends PhysicsBody2D {
 	static props = {
 		velocity: { default: [0, 0] },
 		stickToGround: { default: true },
-		slopeLimitDeg: { default: 45 }
+		slopeLimitDeg: { default: 45 },
+		stepHeight: {
+			default: 35,
+			range: { min: 0 }
+		}
 	};
 	/**
 	* Renamed to match the 3D body, where `snapToGround` had to give the name
@@ -275,6 +340,17 @@ var CharacterBody2D = class extends PhysicsBody2D {
 	stickToGround = true;
 	/** Max climbable slope angle. */
 	slopeLimitDeg = 45;
+	/**
+	* How high a step this body walks up without jumping, in PIXELS.
+	*
+	* Rapier's character controller does not autostep unless it is asked, and in
+	* 2D nothing asked: a ledge of ANY height — measured, ONE pixel — stopped a
+	* walking body dead, while the mirrored `CharacterBody3D` has cleared 0.35 m
+	* by default since 0.63. The default here is that same 0.35 m at the 2D
+	* world's own scale (100 px = 1 m, which is why gravity defaults to 980).
+	* `0` restores the old behaviour.
+	*/
+	stepHeight = 35;
 	/** @internal Updated by Physics2D.moveAndSlide. */
 	_grounded = false;
 	moveAndSlide() {
@@ -387,6 +463,10 @@ var Joint2D = class extends Node2D {
 		const a = this.parent;
 		const b = this.getNodeOrNull(this.target);
 		if (!(b instanceof PhysicsBody2D)) throw new IncantoError("NODE_NOT_FOUND", `Joint2D '${this.name}': target '${this.target}' is not a physics body.`);
+		if (a === b) throw new IncantoError("BAD_FORMAT", `Joint2D '${this.name}': target '${this.target}' is the SAME body this joint hangs off, so it constrains nothing. A joint is a child of ONE body pointing at the OTHER — name the other body (e.g. "%Crate").`, {
+			prop: "target",
+			path: this.getPath()
+		});
 		return {
 			a,
 			b
@@ -415,7 +495,13 @@ var Sprite2D = class extends Node2D {
 		flipX: { default: false },
 		flipY: { default: false },
 		tint: { default: "#ffffff" },
-		opacity: { default: 1 }
+		opacity: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		}
 	};
 	/** `'$assetKey'` texture reference. Empty = hidden. */
 	texture = "";
@@ -479,6 +565,22 @@ var Sprite2D = class extends Node2D {
 		mat.color.set(this.tint);
 		mat.opacity = this.opacity;
 	}
+	/**
+	* The material is PER NODE and nothing freed it.
+	*
+	* The geometry is shared for the process (`UNIT_PLANE`, on purpose), but
+	* every sprite makes its own `MeshBasicMaterial` — and a 2D game that spawns
+	* and frees sprites, which is every 2D game, leaked one per node forever.
+	* The TEXTURE is not touched: it belongs to the asset store and is shared by
+	* every node that names the same key.
+	*
+	* `AnimatedSprite2D` extends this, so it is covered by the same override.
+	*/
+	free() {
+		(this.quadMesh?.material)?.dispose();
+		this.quadMesh = null;
+		super.free();
+	}
 };
 //#endregion
 //#region src/2d/nodes/animated-sprite-2d.ts
@@ -534,7 +636,7 @@ var AnimatedSprite2D = class extends Sprite2D {
 		this.playing = false;
 	}
 	onReady() {
-		validateAnimationAliases(this.animations, this.name);
+		validateAnimations(this.animations, this.name);
 		if (this.autoplay) this.play(this.autoplay);
 	}
 	update(dt) {
@@ -635,10 +737,19 @@ var Camera2D = class extends Node2D {
 	get effectiveZoom() {
 		return Math.max(.01, this.zoom);
 	}
+	/** The `follow` path already reported as untrackable — cleared by a new one. */
+	warnedFollow = "";
 	update(dt) {
 		if (!this.follow) return;
 		const target = this.getNodeOrNull(this.follow);
-		if (!(target instanceof Node2D)) return;
+		if (!(target instanceof Node2D)) {
+			if (this.warnedFollow !== this.follow) {
+				this.warnedFollow = this.follow;
+				const what = target ? `a ${target.constructor.typeName ?? "Node"}` : "nothing";
+				diagnose(this.tree?.engine ?? null, "warn", `[incanto] ${this.getPath()}: follow '${this.follow}' is ${what}, which has no position for the camera to track — the view will not move. Point it at a Node2D.`);
+			}
+			return;
+		}
 		const [tx = 0, ty = 0] = worldPosition(target);
 		const [px = 0, py = 0] = worldPosition(this);
 		const s = Math.min(Math.max(this.smoothing, 0), .99);
@@ -709,6 +820,12 @@ function clampCentered(v, lo, hi) {
 * Every one defaults to OFF (0 / 1 / false), so an existing scene behaves
 * exactly as before until it asks for something.
 */
+/** What each action prop is called when nobody names it. */
+const DEFAULT_ACTIONS = {
+	moveAction: "move",
+	jumpAction: "jump",
+	dashAction: "dash"
+};
 var CharacterController2D = class extends Node {
 	static typeName = "CharacterController2D";
 	static props = {
@@ -771,7 +888,10 @@ var CharacterController2D = class extends Node {
 		const body = this.parent;
 		if (!(body instanceof CharacterBody2D)) return;
 		const input = engine.input;
-		const dir = input.getVector(this.moveAction);
+		const dir = this.readAction("moveAction", () => input.getVector(this.moveAction), {
+			x: 0,
+			y: 0
+		}, "the character will not move");
 		if (this.mode === "topDown") {
 			body.velocity = [dir.x * this.maxSpeed, dir.y * this.maxSpeed];
 			body.moveAndSlide();
@@ -788,7 +908,7 @@ var CharacterController2D = class extends Node {
 			this.setState("dash");
 			return;
 		}
-		if (this.dashSpeed > 0 && input.justPressed(this.dashAction)) {
+		if (this.dashSpeed > 0 && this.readAction("dashAction", () => input.justPressed(this.dashAction), false, "the character will never dash")) {
 			this.dashLeft = this.dashSeconds;
 			this.dashDir = dir.x !== 0 ? Math.sign(dir.x) : this.dashDir;
 			body.velocity[0] = this.dashDir * this.dashSpeed;
@@ -805,9 +925,10 @@ var CharacterController2D = class extends Node {
 			this.coyoteLeft = Math.max(0, this.coyoteLeft - dt);
 			if (this.coyoteLeft <= 0 && this.jumpsUsed === 0) this.jumpsUsed = 1;
 		}
-		if (input.justPressed(this.jumpAction)) this.bufferLeft = Math.max(this.jumpBufferSeconds, 0);
+		const jumpEdge = this.readAction("jumpAction", () => input.justPressed(this.jumpAction), false, "the character will never jump");
+		if (jumpEdge) this.bufferLeft = Math.max(this.jumpBufferSeconds, 0);
 		else this.bufferLeft = Math.max(0, this.bufferLeft - dt);
-		const wantsJump = this.bufferLeft > 0 || input.justPressed(this.jumpAction);
+		const wantsJump = this.bufferLeft > 0 || jumpEdge;
 		const onWall = this.wallSlideSpeed > 0 || this.wallJumpImpulse.some((v) => v !== 0) ? body.isOnWall() : false;
 		if (wantsJump && onWall && !grounded && this.wallJumpImpulse.some((v) => v !== 0)) {
 			const away = -body.wallSide();
@@ -827,7 +948,8 @@ var CharacterController2D = class extends Node {
 			this.rising = false;
 		} else {
 			body.velocity[1] = (body.velocity[1] ?? 0) + gravityY * dt;
-			if (this.rising && this.jumpCutMultiplier < 1 && !input.isPressed(this.jumpAction)) {
+			const jumpHeld = this.readAction("jumpAction", () => input.isPressed(this.jumpAction), false, "the character will never jump");
+			if (this.rising && this.jumpCutMultiplier < 1 && !jumpHeld) {
 				body.velocity[1] = (body.velocity[1] ?? 0) * this.jumpCutMultiplier;
 				this.rising = false;
 			}
@@ -854,6 +976,38 @@ var CharacterController2D = class extends Node {
 		this.state = next;
 		this.emit("movementStateChanged", next);
 	}
+	/** Actions already reported missing, so a per-frame read says it once. */
+	reportedActions = /* @__PURE__ */ new Set();
+	/**
+	* Read an input action this controller is allowed to be missing.
+	*
+	* The 3D controller has done this since `optional-action.ts` was written —
+	* whose own docstring says "`CharacterController3D` and `GameFlow` wrap every
+	* input read" — and the 2D one did not. So a top-down 2D game, which is the
+	* first thing anyone builds with this node and has no jump key, declared
+	* `move` and got:
+	*
+	* ```
+	* [incanto] /Game/Player/Ctl (CharacterController2D) threw in fixedUpdate —
+	* this node is now SKIPPED. IncantoError: Unknown input action 'jump'.
+	* Declared actions: [move].
+	* ```
+	*
+	* SKIPPED: the character could not move either, and every tool reported the
+	* game as `✗ error in 1/1` with the reason only in the log. Tolerated because
+	* a game with no jump key is the ordinary case; reported because otherwise a
+	* TYPO in `"jumpAction"` looks exactly like a deliberate omission.
+	*/
+	readAction(prop, read, fallback, consequence) {
+		const action = this[prop];
+		return tolerateUnknownAction({
+			engine: this.tree?.engine,
+			who: this.getPath(),
+			reported: this.reportedActions,
+			consequence,
+			authored: action !== DEFAULT_ACTIONS[prop]
+		}, action, read, fallback);
+	}
 };
 //#endregion
 //#region src/2d/nodes/color-rect-2d.ts
@@ -869,7 +1023,13 @@ var ColorRect2D = class extends Node2D {
 	static props = {
 		size: { default: [100, 100] },
 		color: { default: "#ffffff" },
-		opacity: { default: 1 },
+		opacity: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		anchor: { default: [.5, .5] }
 	};
 	/** [width, height] in world px. */
@@ -905,6 +1065,24 @@ var ColorRect2D = class extends Node2D {
 		mat.color.set(this.color);
 		mat.opacity = this.opacity;
 	}
+	/**
+	* The material is PER NODE and nothing freed it.
+	*
+	* The geometry is shared for the process (`UNIT_PLANE`, on purpose — a
+	* `THREE.Sprite` cannot be instanced and this is the discipline that replaces
+	* it), but every rect makes its own `MeshBasicMaterial`, and a 2D game that
+	* spawns and frees — bullets, coins, damage flashes, a level swap — leaks one
+	* GPU program's worth of state per node, forever.
+	*
+	* Four 3D nodes had exactly this and were fixed. These two 2D siblings make a
+	* material on the same line of the same kind of `_quad()` helper, and were
+	* not on that list.
+	*/
+	free() {
+		(this.quadMesh?.material)?.dispose();
+		this.quadMesh = null;
+		super.free();
+	}
 };
 //#endregion
 //#region src/2d/nodes/label.ts
@@ -1074,8 +1252,20 @@ var Particles2D = class Particles2D extends Node2D {
 		colorStart: { default: "#ffffff" },
 		colorEnd: { default: "#ffffff" },
 		paletteColors: { default: [] },
-		alphaStart: { default: 1 },
-		alphaEnd: { default: 0 },
+		alphaStart: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
+		alphaEnd: {
+			default: 0,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		shimmer: { default: 0 },
 		blend: {
 			default: "add",
@@ -1138,7 +1328,7 @@ var Particles2D = class Particles2D extends Node2D {
 	_ensureSim() {
 		if (!this.sim) {
 			applyParticlePreset(this, this.preset, getNodeSchema(Particles2D.typeName));
-			const rng = this.tree?.engine?.rng ?? new Rng(4660);
+			const rng = effectRng(this);
 			this.sim = new ParticleSim({
 				rate: this.emitting ? this.rate : 0,
 				lifetime: [this.lifetime[0] ?? 1, this.lifetime[1] ?? 1],
@@ -1244,6 +1434,7 @@ var Particles2D = class Particles2D extends Node2D {
 			kind,
 			name: this.preset,
 			from: this.getPath(),
+			wiredAs: this.wiringPath(),
 			amount,
 			at: engine.time
 		});
@@ -1343,6 +1534,37 @@ const colorScratchC = new Color();
 * - number rows: passed through (`-1` = empty).
 * Ragged rows are right-padded with empty.
 */
+/**
+* A legend entry is a tile INDEX, and anything else is a level with no floor.
+*
+* `legend` maps a char to a number; solidity is the SEPARATE `solid` prop, a
+* list of indices. Every other tilemap format in the world puts them together,
+* so the natural guess is
+*
+* ```jsonc
+* "legend": { "#": { "solid": true, "color": "#4a5568" } }   // WRONG, and silent
+* ```
+*
+* and it loaded clean: `legend[ch]` was not `undefined`, so the object went
+* straight into a `number[]`. `solid.includes(thatObject)` is false, so the
+* ground had no colliders — measured on a scene authored exactly that way, two
+* crates fell from y=120 to y=1859 through a map that `incanto-check` had just
+* called valid.
+*
+* An open dictionary beside a closed one: the loader validates the PROP names
+* hard and never looked inside this one.
+*/
+function tileIndex(ch, value) {
+	if (typeof value === "number" && Number.isInteger(value) && value >= -1) return value;
+	throw new IncantoError("PROP_TYPE_MISMATCH", `TileMap2D: legend entry '${ch}' must be a tile INDEX (a whole number, -1 for empty), got ${describeLegendValue(value)}. Solidity is the separate "solid" prop — a list of tile indices: "legend": { "${ch}": 0 }, "solid": [0].`, { prop: "legend" });
+}
+function describeLegendValue(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return `an array of ${value.length}`;
+	if (typeof value === "object") return `an object (keys: ${Object.keys(value).join(", ")})`;
+	if (typeof value === "number") return `${value}`;
+	return `a ${typeof value}`;
+}
 function parseCells(cells, legend) {
 	const rows = [];
 	let width = 0;
@@ -1350,7 +1572,7 @@ function parseCells(cells, legend) {
 		const out = [];
 		if (typeof row === "string") for (const ch of row) {
 			const mapped = legend[ch];
-			if (mapped !== void 0) out.push(mapped);
+			if (mapped !== void 0) out.push(tileIndex(ch, mapped));
 			else if (ch === "." || ch === " ") out.push(-1);
 			else if (ch >= "0" && ch <= "9") out.push(ch.charCodeAt(0) - 48);
 			else throw new IncantoError("BAD_FORMAT", `TileMap2D: unknown tile char '${ch}' — add it to "legend" (char → tile index), or use '.'/' ' for empty and digits 0-9.`);
@@ -1433,7 +1655,13 @@ var TileMap2D = class extends Node2D {
 		legend: { default: {} },
 		/** Tile indices that get merged static colliders. */
 		solid: { default: [] },
-		opacity: { default: 1 }
+		opacity: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		}
 	};
 	texture = "";
 	tileSize = 32;
@@ -1485,6 +1713,87 @@ var TileMap2D = class extends Node2D {
 	grid() {
 		return parseCells(this._cells, this._legend);
 	}
+	/**
+	* Which CELL is under this world point — `null` outside the grid.
+	*
+	* The one question a tile game asks constantly and this node could not
+	* answer. `VoxelGrid3D`, the 3D grid, has had `tileAt` since it was written;
+	* the 2D one shipped `grid()` and nothing else, so every mouse-driven tile
+	* game hand-rolled the same arithmetic with the same two traps in it: cell
+	* (0,0) hangs its TOP-LEFT on the origin (so a cell's CENTRE is half a tile
+	* further on), and the origin is the node's WORLD position, not its `position`
+	* prop.
+	*
+	* Composes ancestor POSITIONS, like every other world query in the engine
+	* (`Terrain3D.heightAt`, `Water3D`); `auditScene` reports an ancestor that
+	* scales or rotates one of these, because that moves the picture and not the
+	* answer.
+	*/
+	cellAt(worldX, worldY) {
+		const at = worldPosition(this);
+		const [tw, th] = this.scaledTile();
+		if (!(tw > 0) || !(th > 0)) return null;
+		const cx = Math.floor((worldX - (at[0] ?? 0)) / tw);
+		const cy = Math.floor((worldY - (at[1] ?? 0)) / th);
+		const row = this.grid()[cy];
+		if (!row || cx < 0 || cx >= row.length) return null;
+		return [cx, cy];
+	}
+	/**
+	* One cell's size in WORLD pixels — `tileSize` times this node's own scale.
+	*
+	* `scale` is an ordinary `Node2D` prop, the renderer scales the mesh by it,
+	* and `rebuildColliders` has always rebuilt when it changes — so at
+	* `scale: [2, 2]` a tile is 64 px wide on screen AND in physics. These
+	* queries divided by 32 and answered the wrong cell, in silence, which is the
+	* picture and the collider agreeing and the decider disagreeing with both.
+	*
+	* Ancestor scale is not composed here, for the same reason `worldPosition`
+	* does not: every world query in the engine reads its own props and composes
+	* ancestor POSITIONS, and `auditScene` reports an ancestor that scales one.
+	*/
+	scaledTile() {
+		const [sx = 1, sy = 1] = this.scale;
+		return [this.tileSize * Math.abs(sx), this.tileSize * Math.abs(sy)];
+	}
+	/** The atlas index at a cell — `-1` for an empty cell or one off the grid. */
+	tileAt(cx, cy) {
+		return this.grid()[cy]?.[cx] ?? -1;
+	}
+	/**
+	* The CENTRE of a cell, in world pixels — for putting a highlight, a marker
+	* or a spawned enemy on a tile.
+	*
+	* The centre rather than the corner, because that is where a thing goes and
+	* because the corner is the half-tile every hand-rolled version forgets.
+	*/
+	worldAt(cx, cy) {
+		const at = worldPosition(this);
+		const [tw, th] = this.scaledTile();
+		return [(at[0] ?? 0) + cx * tw + tw / 2, (at[1] ?? 0) + cy * th + th / 2];
+	}
+	/**
+	* Write ONE cell, by the character the row holds — dig a tile out, drop a
+	* wall in, flip a switch.
+	*
+	* `cells` are strings and a mutation is not watched, so the documented way to
+	* change a map was to rebuild the whole row by hand
+	* (`row.slice(0, x) + c + row.slice(x + 1)`) and reassign the array. This is
+	* that, once, correctly, and it rebuilds the geometry and the colliders.
+	*
+	* A CHARACTER, not an index: `legend` may map several characters to one tile,
+	* so an index cannot say which of them you meant. `'.'` empties the cell.
+	* Returns false for a cell off the grid, or a numeric row (those hold indices
+	* — assign the row).
+	*/
+	setTile(cx, cy, char) {
+		const row = this._cells[cy];
+		if (typeof row !== "string" || cx < 0 || cx >= row.length || char.length !== 1) return false;
+		const next = this._cells.slice();
+		next[cy] = `${row.slice(0, cx)}${char}${row.slice(cx + 1)}`;
+		this.cells = next;
+		return true;
+	}
 	onReady() {
 		this.rebuildColliders();
 	}