@ignifx/physics-2d 0.10.0 → 0.11.0

package/dist/index.js

@@ -80,6 +80,15 @@ var Rigidbody2D = class Rigidbody2D extends Component {
 		this.rebuild();
 	}
 	/**
+	* Rebuilds the body after a tool changed fields from outside: an editor's inspector, or a hot
+	* reload's new default (`ComponentHooks.onValidate`).
+	*
+	* @param fields - The fields that changed.
+	*/
+	onValidate(fields) {
+		this.rebuild();
+	}
+	/**
 	* Rebuilds the body at the start of the next fixed step. Call it after changing `bodyType`,
 	* `mass`, `freezeRotation`, damping, or the entity's scale.
 	*/
@@ -276,6 +285,15 @@ var CharacterController2D = class CharacterController2D extends Component {
 	onDetach() {
 		this.#runtime()?.releaseController(this);
 	}
+	/**
+	* Rebuilds the body after a tool changed fields from outside: an editor's inspector, or a hot
+	* reload's new default (`ComponentHooks.onValidate`).
+	*
+	* @param fields - The fields that changed.
+	*/
+	onValidate(fields) {
+		this.rebuild();
+	}
 	/** Rebuilds the capsule or box at the start of the next fixed step. */
 	rebuild() {
 		this.#runtime()?.markControllerDirty(this);
@@ -704,6 +722,15 @@ var Collider2D = class extends Component {
 		this.rebuild();
 	}
 	/**
+	* Rebuilds the body after a tool changed fields from outside: an editor's inspector, or a hot
+	* reload's new default (`ComponentHooks.onValidate`).
+	*
+	* @param fields - The fields that changed.
+	*/
+	onValidate(fields) {
+		this.rebuild();
+	}
+	/**
 	* Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
 	* changing a size, an offset, `isTrigger`, or the entity's scale.
 	*
@@ -1102,8 +1129,9 @@ var TilemapCollider2D = class TilemapCollider2D extends Collider2D {
 	* `Tilemap` on the same entity.
 	*
 	* @remarks
-	* Reading it works in an edit-mode app too, where no body is built (ADR-0028), so an editor can
-	* draw the outlines.
+	* Reading it works in any app, before any body is built. An edit-mode app also builds the body
+	* without stepping (ADR-0028, amendment of 2026-10-20), so `app.physics2d.colliderOutlines` draws
+	* the same outlines from Rapier.
 	*
 	* @returns The data, or `null` when nothing was assigned and the entity has no `Tilemap`.
 	*/
@@ -1888,6 +1916,21 @@ function toRadians(degrees) {
 	return degrees * TAU / 360;
 }
 /**
+* The outline Rapier's debug renderer draws for some colliders, as world-space line segments
+* (`pipeline/world.d.ts`, `debugRender`; `DebugRenderBuffers.vertices`: four numbers a segment, the
+* `x, y` of its two ends). It reads where the colliders were after the last step, or after the
+* zero-length step an edit-mode app runs instead.
+*
+* @param world - The world.
+* @param handles - The handles of the colliders to draw.
+* @returns The segments; a copy, because Rapier reuses its buffer.
+*
+* @internal
+*/
+function colliderLines(world, handles) {
+	return world.debugRender(void 0, (collider) => handles.has(collider.handle)).vertices.slice();
+}
+/**
 * Turns Rapier's radians into the degrees `Transform.rotation2D` uses.
 *
 * @param radians - The angle in radians.
@@ -2163,6 +2206,12 @@ var Physics2DRuntime = class {
 	#filterFeet = 0;
 	#colliderSetChanged = true;
 	#stepped = false;
+	/** Whether the app is an editor's scene view, where bodies exist and nothing steps (ADR-0028). */
+	#isEditMode;
+	/** The last failure reported for each entity whose body could not be built, in edit mode. */
+	#failures = /* @__PURE__ */ new WeakMap();
+	/** The entities `IGX-1157` (a body on a child entity) has been logged for, once each. */
+	#warnedChildren = /* @__PURE__ */ new WeakSet();
 	#disposed = false;
 	#stepsThisFrame = 0;
 	#stepMs = 0;
@@ -2180,6 +2229,7 @@ var Physics2DRuntime = class {
 		this.#settings = options.settings;
 		this.#world = options.world;
 		this.#counters = options.counters;
+		this.#isEditMode = options.ctx.app.isEditMode;
 		this.#queue = createEventQueue();
 		this.#contacts.push(this.#contactPoint);
 		setGravity(this.#world, this.#settings.gravity);
@@ -2204,6 +2254,15 @@ var Physics2DRuntime = class {
 		return this.#stepped;
 	}
 	/**
+	* Whether this runtime belongs to an edit-mode app, where bodies are kept in sync with the world
+	* by {@link Physics2DRuntime.syncEditMode} and never stepped (ADR-0028, amendment of 2026-10-20).
+	*
+	* @returns `true` in an editor's scene view.
+	*/
+	get isEditMode() {
+		return this.#isEditMode;
+	}
+	/**
 	* Every body, in creation order.
 	*
 	* @returns The records.
@@ -2427,6 +2486,31 @@ var Physics2DRuntime = class {
 		this.#dispatchEvents();
 	}
 	/**
+	* Brings the bodies in line with the world without stepping, which is all an edit-mode app ever
+	* does with them (ADR-0028, amendment of 2026-10-20): it builds, rebuilds, and removes bodies for
+	* component, layer, and tile changes, and places every body whose transform moved where the
+	* transform now is, so a query sees what the editor shows. The world is never stepped, so nothing
+	* falls, no contact or trigger callback fires, and no pose is written back to a transform.
+	*
+	* @remarks
+	* Rapier refreshes its broadphase only inside a step, so after a change this runs the same
+	* zero-length step a game runs before its first real one (S6.2). With a zero timestep nothing
+	* moves; the events it reports are dropped. A changed scale rebuilds the body's colliders.
+	*/
+	syncEditMode() {
+		if (this.#disposed) return;
+		this.#syncLayers();
+		this.#pollTilemaps();
+		this.#followTransforms();
+		this.#reconcile();
+		if (this.#colliderSetChanged) {
+			primeWorld(this.#world, this.#queue);
+			this.#colliderSetChanged = false;
+			drainCollisions(this.#queue, ignoreEvent);
+		}
+		this.#publishCounters();
+	}
+	/**
 	* Writes the interpolated display pose of every interpolated body.
 	*
 	* @param alpha - `time.fixedStepAlpha`, in `[0, 1)`.
@@ -2522,6 +2606,34 @@ var Physics2DRuntime = class {
 			if (record !== void 0 && record.entity.layer !== record.layer) this.markDirty(record.entity);
 		}
 	}
+	/**
+	* Places every body whose transform changed since it was placed where the transform now is, for
+	* {@link Physics2DRuntime.syncEditMode}. A body whose lossy scale changed is rebuilt instead.
+	*/
+	#followTransforms() {
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			if (record === void 0 || this.#dirty.has(record.entity)) continue;
+			const transform = record.entity.transform;
+			const version = transform.worldMatrixVersion;
+			if (version === record.placedVersion) continue;
+			const scale = transform.lossyScale;
+			if (!sameVector(scale, record.placedScale)) {
+				this.markDirty(record.entity);
+				continue;
+			}
+			transform.positionToRef(this.#scratchPose);
+			const radians = toRadians(transform.rotation2D);
+			this.#scratchVector.set(this.#scratchPose.x, this.#scratchPose.y);
+			setBodyPose(record.body, this.#scratchVector, radians);
+			record.currentPosition.copyFrom(this.#scratchVector);
+			record.previousPosition.copyFrom(this.#scratchVector);
+			record.currentRotation = radians;
+			record.previousRotation = radians;
+			record.placedVersion = version;
+			this.#colliderSetChanged = true;
+		}
+	}
 	/** Marks every entity whose tilemap collision data changed since its shapes were built. */
 	#pollTilemaps() {
 		const colliders = this.#ctx.app.world.components(TilemapCollider2D);
@@ -2535,10 +2647,43 @@ var Physics2DRuntime = class {
 		if (this.#dirty.size === 0) return;
 		const pending = [...this.#dirty];
 		this.#dirty.clear();
-		for (const entity of pending) this.#rebuildEntity(entity);
+		for (const entity of pending) this.#guarded(entity, () => {
+			this.#rebuildEntity(entity);
+		});
 		this.#colliderSetChanged = true;
 	}
 	/**
+	* Runs one entity's rebuild. In an edit-mode app a failure (a collider naming an undeclared
+	* layer, say) is reported through `app.onError` once per entity and message and the other
+	* entities still build, so one broken entity never stops the editor's queries; the entity
+	* builds again when its components change. A game rethrows, as before.
+	*
+	* @param entity - The entity being rebuilt.
+	* @param rebuild - The work.
+	*/
+	#guarded(entity, rebuild) {
+		if (!this.#isEditMode) {
+			rebuild();
+			return;
+		}
+		try {
+			rebuild();
+			this.#failures.delete(entity);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			if (this.#failures.get(entity) !== message) {
+				this.#failures.set(entity, message);
+				this.#ctx.app.onError.emit({
+					error,
+					source: "extension",
+					phase: null,
+					entity,
+					component: null
+				});
+			}
+		}
+	}
+	/**
 	* Tears an entity's body down and builds a new one from its current components.
 	*
 	* @param entity - The entity to rebuild.
@@ -2559,7 +2704,10 @@ var Physics2DRuntime = class {
 		const controller = entity.getComponent(CharacterController2D);
 		const colliders = collidersOf(entity);
 		if (colliders.length === 0 && controller === null) return;
-		if (entity.parent !== null) this.#ctx.log.warn(`${Physics2DErrorCode.bodyOnChildEntity}: {entity} carries a 2D physics body but is not a root entity; Rapier writes its world pose.`, entity.name);
+		if (entity.parent !== null && !this.#warnedChildren.has(entity)) {
+			this.#warnedChildren.add(entity);
+			this.#ctx.log.warn(`${Physics2DErrorCode.bodyOnChildEntity}: {entity} carries a 2D physics body but is not a root entity; Rapier writes its world pose.`, entity.name);
+		}
 		const record = this.#build(entity, entity.getComponent(Rigidbody2D), controller, colliders);
 		if (record === null) return;
 		this.#records.push(record);
@@ -2617,11 +2765,19 @@ var Physics2DRuntime = class {
 			preStepVelocity: new Vec2(),
 			staticVersion: transform.worldMatrixVersion,
 			reportedMove: false,
+			placedVersion: transform.worldMatrixVersion,
+			placedScale: transform.lossyScale,
 			disconnects: []
 		};
 		this.#byEntity.set(entity, record);
-		this.#attachColliders(record, colliders, layer);
-		if (controller !== null) this.#attachController(record, controller, layer);
+		try {
+			this.#attachColliders(record, colliders, layer);
+			if (controller !== null) this.#attachController(record, controller, layer);
+		} catch (error) {
+			this.#teardown(record);
+			this.#byEntity.delete(entity);
+			throw error;
+		}
 		if (record.colliders.length === 0) {
 			this.#byEntity.delete(entity);
 			destroyBody(this.#world, body);
@@ -3124,11 +3280,25 @@ var Physics2DRuntime = class {
 	* @returns `true` when interpolation applies.
 	*/
 	#shouldInterpolate(rigidbody, controller, motion) {
-		if (!this.#settings.interpolation || motion === BodyMotion2D.static) return false;
+		if (this.#isEditMode || !this.#settings.interpolation || motion === BodyMotion2D.static) return false;
 		if (controller !== null) return controller.interpolation === "interpolate";
 		return rigidbody !== null && rigidbody.interpolation === "interpolate";
 	}
 };
+/** How far apart two scales may be and still count as the same, for edit mode's follow pass. */
+const SCALE_EPSILON = 1e-6;
+/**
+* Whether two vectors match to within {@link SCALE_EPSILON}.
+*
+* @param first - One vector.
+* @param second - The other.
+* @returns `true` when every component matches.
+*/
+function sameVector(first, second) {
+	return Math.abs(first.x - second.x) < SCALE_EPSILON && Math.abs(first.y - second.y) < SCALE_EPSILON && Math.abs(first.z - second.z) < SCALE_EPSILON;
+}
+/** Drops an event an edit-mode priming step reported; nothing in edit mode delivers one. */
+function ignoreEvent() {}
 /** How far below a one-way platform's top the character's feet may be and still land on it. */
 const ONE_WAY_TOLERANCE = .02;
 /**
@@ -3325,6 +3495,35 @@ var Physics2DInterpolationSystem = class {
 		this.#host.runtime?.interpolate(ctx.time.fixedStepAlpha);
 	}
 };
+/**
+* Where the edit-mode sync system runs: in `PreRender`, after every script, tween and animation of
+* the frame has moved what it moves, and before the 2D render sync.
+*/
+const PHYSICS_2D_EDIT_SYNC_ORDER = -800;
+/**
+* Keeps the bodies of an edit-mode app in line with the world, without stepping
+* (ADR-0028, amendment of 2026-10-20). It is registered only in an edit-mode app, so a game never
+* pays for it.
+*
+* @internal
+*/
+var Physics2DEditSyncSystem = class {
+	/** The name diagnostics and error reports use. */
+	name = "physics2d-edit-sync";
+	#host;
+	/**
+	* Binds the system to the runtime holder.
+	*
+	* @param host - The holder the runtime lands in.
+	*/
+	constructor(host) {
+		this.#host = host;
+	}
+	/** Builds, re-places, and removes bodies for this frame's changes. */
+	update() {
+		this.#host.runtime?.syncEditMode();
+	}
+};
 //#endregion
 //#region src/service.ts
 /**
@@ -3414,7 +3613,7 @@ var Physics2DService = class {
 	* @param maxDistance - How far to travel; defaults to 10 km.
 	* @param options - Layer mask and trigger behaviour.
 	* @returns The hit, or `null` when the ray clears everything.
-	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet, outside edit mode.
 	*/
 	raycast(origin, direction, maxDistance = DEFAULT_RAY_DISTANCE, options) {
 		this.#requireStep("raycast");
@@ -3431,7 +3630,7 @@ var Physics2DService = class {
 	* @param maxDistance - How far to travel; defaults to 10 km.
 	* @param options - Layer mask and trigger behaviour.
 	* @returns The hits, in increasing distance. The array is reused between calls.
-	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet, outside edit mode.
 	*/
 	raycastAll(origin, direction, maxDistance = DEFAULT_RAY_DISTANCE, options) {
 		this.#requireStep("raycastAll");
@@ -3460,7 +3659,7 @@ var Physics2DService = class {
 	* @param radius - Its radius in metres.
 	* @param options - Layer mask and trigger behaviour.
 	* @returns The overlapping entities, in Rapier's order. The array is reused between calls.
-	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet, outside edit mode.
 	*/
 	overlapCircle(centre, radius, options) {
 		return this.#overlap({
@@ -3476,7 +3675,7 @@ var Physics2DService = class {
 	* @param rotation - Its rotation in degrees counter-clockwise; defaults to `0`.
 	* @param options - Layer mask and trigger behaviour.
 	* @returns The overlapping entities. The array is reused between calls.
-	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet, outside edit mode.
 	*/
 	overlapBox(centre, size, rotation = 0, options) {
 		return this.#overlap({
@@ -3494,7 +3693,7 @@ var Physics2DService = class {
 	* @param maxDistance - How far to sweep.
 	* @param options - Layer mask and trigger behaviour.
 	* @returns The hit, or `null`.
-	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet, outside edit mode.
 	*/
 	shapeCast(centre, radius, direction, maxDistance, options) {
 		this.#requireStep("shapeCast");
@@ -3567,13 +3766,68 @@ var Physics2DService = class {
 		return runtime;
 	}
 	/**
-	* Refuses a query that ran before Rapier built its broadphase (spike S6.2).
+	* The outlines of an entity's 2D colliders, as world-space line segments: what an editor draws as
+	* collider gizmos (ADR-0028, amendment of 2026-10-20).
+	*
+	* @remarks
+	* The segments are Rapier's own debug drawing of the colliders the entity's body is built from,
+	* so a polygon, an edge chain, a capsule, a one-way platform, and every piece of a
+	* `TilemapCollider2D` are outlined exactly. A body exists from the first fixed step in a game,
+	* and from the first frame or query in an edit-mode app, which keeps bodies on the transforms the
+	* editor moves; an entity without one (no enabled collider yet, or before that point) has no
+	* outline. A `CharacterController2D`'s own shape is not a collider and is not outlined.
+	*
+	* @param entity - The entity whose colliders to outline.
+	* @returns One outline per collider that produced a shape, in component order; empty when none.
+	*
+	* @example
+	* ```ts
+	* for (const outline of app.physics2d.colliderOutlines(selected)) {
+	*   drawLines2D(outline.lines, outline.isTrigger ? "orange" : "green");
+	* }
+	* ```
+	*/
+	colliderOutlines(entity) {
+		const runtime = this.#host.runtime;
+		const outlines = [];
+		if (runtime === null || entity.isDestroyed) return outlines;
+		if (runtime.isEditMode) runtime.syncEditMode();
+		const record = runtime.recordOf(entity);
+		if (record === null) return outlines;
+		const byOwner = /* @__PURE__ */ new Map();
+		for (let index = 0; index < record.colliders.length; index += 1) {
+			const owner = record.owners[index] ?? null;
+			const collider = record.colliders[index];
+			if (owner === null || collider === void 0) continue;
+			let handles = byOwner.get(owner);
+			if (handles === void 0) {
+				handles = /* @__PURE__ */ new Set();
+				byOwner.set(owner, handles);
+			}
+			handles.add(colliderHandle(collider));
+		}
+		for (const [owner, handles] of byOwner) outlines.push({
+			collider: owner,
+			isTrigger: owner.isTrigger,
+			lines: colliderLines(runtime.world, handles)
+		});
+		return outlines;
+	}
+	/**
+	* Refuses a query that ran before Rapier built its broadphase (spike S6.2). In an edit-mode app,
+	* which never steps, it brings the bodies in line with the world instead, so the query sees what
+	* the editor shows (ADR-0028, amendment of 2026-10-20).
 	*
 	* @param query - The query name, for the diagnostic.
-	* @throws IgnifxError with code `IGX-1153` when no step has completed.
+	* @throws IgnifxError with code `IGX-1153` when no step has completed, outside edit mode.
 	*/
 	#requireStep(query) {
-		if (this.#rt().hasStepped) return;
+		const runtime = this.#rt();
+		if (runtime.isEditMode) {
+			runtime.syncEditMode();
+			return;
+		}
+		if (runtime.hasStepped) return;
 		throw physics2DError(Physics2DErrorCode.queryBeforeStep, `${query}() ran before the first fixed step.`, {
 			context: { query },
 			hint: "Step the app at least once (app.step(1 / 60)) before querying; Rapier builds its broadphase in the first step."
@@ -3734,6 +3988,10 @@ const physics2d = defineExtension((options = {}) => {
 				order: PHYSICS_2D_INTERPOLATE_ORDER,
 				editMode: "skip"
 			});
+			if (ctx.app.isEditMode) ctx.registerSystem(new Physics2DEditSyncSystem(host), {
+				phase: Phase.PreRender,
+				order: PHYSICS_2D_EDIT_SYNC_ORDER
+			});
 		},
 		async onStart(app) {
 			const ctx = context;