lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/core/time.ts

@@ -0,0 +1,81 @@
+// The game clock: one place that owns "how fast does the game run" — `Time.scale` (slow-motion, 0.5),
+// `Time.paused` (a menu over a frozen world) — and what a frame is worth (`Time.dt`).
+//
+// The aspect dispatcher (core/Aspect.ts) calls `_beginFrame(rawDt)` once per frame with the host's
+// wall-clock delta; `update*(dt)` callbacks then receive the SCALED delta (0 while paused). The same
+// scale is pushed to every engine that registered a sink (creator-gl / creator-2d `setTimeScale`),
+// so physics, animators and particles slow down and freeze together with the game code — a paused
+// aspect and a paused rigid body agree. `Time.unscaledDt` is the wall-clock delta for things that
+// must keep moving while the game is paused (a HUD fade, a pause-menu animation): those aspects set
+// `updateWhilePaused = true` and read it themselves, exactly like Unity's unscaledDeltaTime.
+
+type ScaleSink = (scale: number) => void
+const sinks: ScaleSink[] = []
+
+class TimeClock {
+  private _scale = 1
+  private _paused = false
+  /** Seconds of GAME time since the app started (scaled; stops while paused). */
+  now = 0
+  /** Seconds of wall-clock time since the app started (never stops). */
+  unscaledNow = 0
+  /** This frame's delta in game seconds — what `update(dt)` receives. 0 while paused. */
+  dt = 0
+  /** This frame's wall-clock delta in seconds (the host's frame time, clamped by the engine). */
+  unscaledDt = 0
+  /** Frames dispatched since the app started (counts paused frames too). */
+  frame = 0
+
+  /** Speed of the game relative to wall-clock: 1 normal, 0.5 half speed, 2 double. Applied to
+   *  `dt`, `now` AND the engines' physics / animation / particle clocks. Negative or NaN → 0. */
+  get scale(): number { return this._scale }
+  set scale(v: number) {
+    const s = Number.isFinite(v) && v > 0 ? v : 0
+    if (s === this._scale) return
+    this._scale = s
+    this._push()
+  }
+
+  /** Freeze the game: `dt` reads 0, aspects without `updateWhilePaused` are skipped, the engines'
+   *  simulations stop. `scale` is remembered and restored on resume. */
+  get paused(): boolean { return this._paused }
+  set paused(v: boolean) {
+    if (v === this._paused) return
+    this._paused = v
+    this._push()
+  }
+
+  /** The scale the engines currently run at (0 while paused). */
+  get effectiveScale(): number { return this._paused ? 0 : this._scale }
+
+  private _push(): void {
+    const s = this.effectiveScale
+    for (const sink of sinks) sink(s)
+  }
+
+  /** @internal Called by the aspect dispatcher at the top of every frame with the host's raw delta. */
+  _beginFrame(rawDt: number): void {
+    const raw = Number.isFinite(rawDt) && rawDt > 0 ? rawDt : 0
+    this.frame++
+    this.unscaledNow += raw
+    this.now += this._phaseDt(raw)
+  }
+  /** @internal A phase's scaled delta from its raw one; records both as this frame's `dt`. */
+  _phaseDt(rawDt: number): number {
+    const raw = Number.isFinite(rawDt) && rawDt > 0 ? rawDt : 0
+    this.unscaledDt = raw
+    this.dt = raw * this.effectiveScale
+    return this.dt
+  }
+}
+
+/** The game clock — scale / pause the whole game, read `dt` / `now` anywhere. */
+export const Time = new TimeClock()
+
+/** @internal Engine layers (Scene / Scene2D) register the bridge call that forwards the effective
+ *  scale to their native clocks. Pushed immediately with the current value so a scene created after
+ *  `Time.paused = true` starts frozen. */
+export const _registerTimeScaleSink = (sink: ScaleSink): void => {
+  sinks.push(sink)
+  sink(Time.effectiveScale)
+}

package/runtime/sdk/g2/Camera2D.ts

@@ -3,8 +3,9 @@
 // no built-in follow() (and so nothing to dispose).
 
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { CompAxis, CompWriter } from "../core/compWrite"
 
-export class Camera2D {
+export class Camera2D implements CompWriter {
   private _x = 0
   private _y = 0
   private _zoom = 1
@@ -15,6 +16,12 @@ export class Camera2D {
 
   get position(): Vec2 { return new Vec2(this._x, this._y) }
   set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.cameraSetPosition(this.sceneId, this._x, this._y) }
+  /** @internal chisel `comp_write` (see core/compWrite.ts): `camera.position.<axis> = v` compiles to a call here. */
+  static _comps = [ "position" ]
+  _writeComp(_prop: string, axis: CompAxis, v: number): void {
+    if (axis === "x") this.position = [ v, this._y ]
+    else if (axis === "y") this.position = [ this._x, v ]
+  }
 
   get zoom(): number { return this._zoom }
   set zoom(z: number) { this._zoom = z; _creator2d.cameraSetZoom(this.sceneId, z) }

package/runtime/sdk/g2/CharacterController2D.ts

@@ -1,76 +1,276 @@
-// A platformer-friendly character controller, as an aspect on a Node2D. Built on a fixed-rotation
-// dynamic Physics2D body: you drive horizontal intent + jump, and Box2D handles gravity, falling, and
-// wall/floor collision response; a short downward ray reports `grounded`.
+// A character controller, as an aspect on a Node2D, backed by Box2D's kinematic MOVER — collide and
+// slide, not a rigid body. Requires a capsule Shape2D (one is derived from the sprite if absent) and
+// does NOT use Physics2D.
 //
 //   const hero = new Sprite({ texture, anchor: [0.5, 1] })
-//     .aspect(Shape2D, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } })
-//     .aspect(Physics2D, { motion: 'dynamic', fixedRotation: true })
-//     .aspect(CharacterController2D, { speed: 200, jumpSpeed: 520 })
-//   Input.on('left',  d => hero.controller.move(d ? -1 : 0))
-//   Input.on('jump',  () => hero.controller.jump())
+//     .aspect(Shape2D, { capsule: { from: [0, 8], to: [0, 26], radius: 8 } })
+//     .aspect(CharacterController2D)
 //
-// Velocity-control (set velocity each frame) is the standard, robust approach for platformers and
-// reuses the physics solver. For pixel-tight movement without any solver bounce/seam quirks, a
-// kinematic move-and-slide controller can be added later (see creator-2d PLAN.md, Phase G).
+//   setLoop(() => hero.controller.move(((Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0)) * SPEED))
+//   Input.on('keydown', e => { if (e.code === 'Space' && hero.controller.grounded) hero.controller.velocityY = 700 })
+//
+// The two halves of the velocity have different NATURES, so they have different channels:
+//
+//   • HORIZONTAL — `move(x)`, world units/s, a PER-FRAME COMMAND. A walking character's horizontal
+//     velocity is muscle-driven and not conserved: stop pushing, stop moving. So the command expires
+//     each frame — no call this frame means standing still, and releasing the keys needs no explicit
+//     zero. It is latched for the whole frame, so every physics sub-step of that frame sees it.
+//   • VERTICAL — `velocityY`, LATCHED ballistic state. Gravity integrates into it in the engine; you
+//     seed it for a jump / bounce pad / explosion. There is deliberately no ground check: coyote
+//     time, double jumps and wall jumps all need the caller's own condition.
+//
+// FREE MODE — `gravityScale = 0` turns the character into a swimmer / flyer / ladder climber / the
+// hero of a TOP-DOWN game: no gravity, no ground, no stick-to-floor. There the vertical is
+// muscle-driven too, so `move()` takes BOTH components and the whole velocity becomes a per-frame
+// command. Top-down vs platformer is this one number, not two controllers.
+//
+// `velocity` reads back what the solver ENDED UP with after the last step (post-collision) — walk into
+// a wall and it reads ~0 even though you commanded 300. Everything runs on the engine's fixed clock,
+// so the aspect has no per-frame update: a character costs zero JS work per frame.
+//
+// ROTATION AND SCALE stay the node's: the engine writes only the position (a capsule is symmetric
+// about its axis, so its angle is physically meaningless).
+//
+// The character IS visible to raycasts, overlaps and triggers — it carries a hidden kinematic body for
+// exactly that, so pickups and hazard zones need no special code. Solid contacts do not arrive as
+// 'enter' events (the mover is not a body); read `collisions` for those.
 
 import { Aspect } from "../core/Aspect"
-import { Vec2 } from "../math/vec"
-import { Physics2D } from "./Physics2D"
+import type { FieldMeta } from "../core/fields"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { CompAxis, CompWriter } from "../core/compWrite"
+import { PhysicsGroup2D, _watchGroupChanges, _unwatchGroupChanges, categoryOf, solidMask } from "./groups2d"
 import { Shape2D } from "./Shape2D"
-import type { Node2D } from "./Node2D"
+import { node2dRegistry, type Node2D } from "./Node2D"
 
-export class CharacterController2D extends Aspect<"controller", Node2D> {
-  static readonly aspect = "controller"
+/** Where the character's feet are, as reported by the solver after the last step. */
+export type GroundState2D = "ground" | "slope" | "air"
+const GROUND_STATES: readonly GroundState2D[] = [ "ground", "slope", "air" ]
 
-  /** Horizontal move speed (world units/s). */
-  speed = 200
-  /** Jump take-off speed (world units/s). */
-  jumpSpeed = 500
-  /** Extra probe distance below the body's feet used for the grounded check (world units). */
-  groundProbe = 6
-  /** Distance from the node origin down to the feet. Defaults to half the sprite height. */
-  footOffset?: number
+/** One surface the mover pushed out of this step. `normal` points back at the character. */
+export type Collision2D = { node: Node2D | null, normal: Vec2 }
 
-  private _moveX = 0
-  private _jumpQueued = false
-  private _grounded = false
+const MAX_COLLISIONS = 8
+const state = new Float32Array(8)
+let warnedFreeMove = false
 
-  /** Horizontal intent in [-1, 1] (e.g. from input). Sticky — set 0 to stop. Applied next frame. */
-  move(dir: number): void { this._moveX = dir < -1 ? -1 : dir > 1 ? 1 : dir }
-  /** Queue a jump; consumed on the next frame if grounded. */
-  jump(): void { this._jumpQueued = true }
-  /** True while standing on something (updated each frame). */
-  get grounded(): boolean { return this._grounded }
+export class CharacterController2D extends Aspect<"controller", Node2D> implements CompWriter {
+  static readonly aspect = "controller"
 
-  private get phys(): Physics2D | undefined { return this.node.get(Physics2D) }
+  // Accessor-backed tunables are invisible to describeFields (it enumerates own enumerable fields),
+  // so the inspector is told about them explicitly. Defaults still come from the getters.
+  static fields: FieldMeta<CharacterController2D> = {
+    gravityScale: { editor: "number", min: 0, step: 0.1, label: "Gravity scale" },
+    maxSlope: { editor: "number", min: 0, max: 89, step: 1, label: "Max slope°" },
+  }
+
+  private _id = 0
+  private _gravityScale = 1
+  private _maxSlope = 45
+  private _group: PhysicsGroup2D | undefined
+  private _dropThrough: Node2D | null = null
+  private _repush = (): void => {
+    if (this._id) _creator2d.characterSetFilter(this._id, categoryOf(this._group), solidMask(this._group))
+  }
 
   onAttach(): void {
-    // Ensure a Shape2D (auto box from the sprite) + a dynamic, fixed-rotation body if not already set up.
+    if (!_creator2d.physicsHasSupport || !_creator2d.physicsHasSupport()) return
     if (!this.node.has(Shape2D)) this.node.aspect(Shape2D, {})
-    if (!this.node.has(Physics2D)) this.node.aspect(Physics2D, { motion: "dynamic", fixedRotation: true })
+    const shape = this.node.get(Shape2D)!
+    const cap = shape._capsule()
+    // Read the options through their PUBLIC accessors — chisel drops an accessor pair whose name is
+    // only ever an object-literal key, and the option would silently do nothing (see Physics2D).
+    this._id = _creator2d.characterCreate(this.node.id, cap.x1, cap.y1, cap.x2, cap.y2, cap.radius,
+                                          this.maxSlope, categoryOf(this.group), solidMask(this.group))
+    if (!this._id) return
+    shape._claimedByCharacter()
+    _creator2d.characterSetGravityScale(this._id, this.gravityScale)
+    this.node._xf = this._id      // routes node.position writes to the character
+    this.node._xfKind = 1
+    // The engine moves this node every step, so its JS transform cache must re-sync on READ — without
+    // this the character simulates correctly and node.position never changes.
+    this.node._physicsDriven = true
+    if (this._group) _watchGroupChanges(this._repush)
   }
 
-  update(_dt: number): void {
-    const phys = this.phys
-    if (!phys) return
+  onDetach(): void {
+    _unwatchGroupChanges(this._repush)
+    if (this._id) { _creator2d.characterDestroy(this._id); this._id = 0 }
+    this.node._xf = 0
+    this.node._xfKind = 0
+    this.node._physicsDriven = false
+  }
 
-    // Grounded probe: a short ray straight down from the feet. The ray originates inside the body,
-    // so Box2D won't report the body's own shape; we exclude self defensively too.
-    const pos = this.node.worldPosition
-    const foot = this.footOffset ?? this._spriteHalfHeight()
-    const hit = Physics2D.raycast([pos.x, pos.y - foot * 0.5], [pos.x, pos.y - foot - this.groundProbe])
-    this._grounded = !!hit && hit.node !== this.node
+  /** Native character id (0 until attached / no physics support). */
+  get id(): number { return this._id }
 
-    let vy = phys.velocity.y
-    if (this._jumpQueued && this._grounded) { vy = this.jumpSpeed; this._grounded = false }
-    this._jumpQueued = false
+  /**
+   * This frame's movement command, in world units/s — NOT normalized, NOT a per-frame displacement
+   * (that is what Unity's `Move` takes; passing `v * dt` here gives a character 60× too slow).
+   *
+   * ONE component = horizontal, the everyday platformer call. TWO = the whole velocity, for free mode
+   * (`gravityScale = 0`); with gravity on, a two-component call fights the ballistic vertical and the
+   * character hangs in the air, so that combination warns once.
+   *
+   * Sticky only within the frame: the command expires once the engine consumes it. It also **takes the
+   * axis back from a latched `velocity`** — commanding is claiming ownership, which is what keeps the
+   * two horizontal sources from ever fighting.
+   */
+  move(x: number): void
+  move(x: number, y: number): void
+  move(v: Vec2Like): void
+  move(x: number | Vec2Like, y?: number): void {
+    if (!this._id) return
+    if (typeof x === "number") {
+      if (y === undefined) { _creator2d.characterMove(this._id, x); return }
+      this._warnFree()
+      _creator2d.characterMoveFree(this._id, x, y)
+      return
+    }
+    this._warnFree()
+    _creator2d.characterMoveFree(this._id, cx(x), cy(x))
+  }
 
-    // Drive horizontal velocity directly; let the sim own vertical (gravity / jump / landing).
-    phys.velocity = new Vec2(this._moveX * this.speed, vy)
+  private _warnFree(): void {
+    if (this._gravityScale === 0 || warnedFreeMove) return
+    warnedFreeMove = true
+    console.warn("CharacterController2D.move(): the two-component form is the FREE-mode command (top-down / swimming / flying) and expects gravityScale = 0. With gravity on it overwrites the falling speed every frame, so the character will hang in the air. Use move(x) and velocityY for a platformer.")
   }
 
-  private _spriteHalfHeight(): number {
-    const size = (this.node as { size?: Vec2 }).size
-    return size ? size.y * 0.5 : 8
+  /** Vertical velocity (world units/s) — LATCHED: gravity works on it, you seed it. `= 700` to jump,
+   *  `+= 300` to stack an explosion on top of the current motion. No ground check: guard it yourself
+   *  with `grounded` (or don't, for a double jump). Does nothing in free mode. `velocity.y = 700` is
+   *  the same channel — pick whichever reads better. */
+  get velocityY(): number { return this._state()[1] }
+  set velocityY(v: number) { if (this._id) _creator2d.characterSetVerticalVelocity(this._id, v) }
+
+  /**
+   * READ — the velocity the solver ended up with after the most recent step (world units/s, fresh
+   * Vec2): what HAPPENED, not what you asked for. Walking into a wall reads ~0, sliding along one
+   * reads the tangent.
+   *
+   * WRITE — LATCH the whole velocity: a knockback, a wall jump, a launch pad. Unlike `move()` it does
+   * not expire, so the character keeps flying, and gravity still pulls the vertical down into a real
+   * ballistic arc. It stays until `move()` takes the axis back — so a game simply doesn't call
+   * `move()` while the throw lasts, and ends it on its own terms:
+   *
+   *     hero.controller.velocity = [dir.x * 600, 400]          // hit by the blast
+   *     if (thrown) { if (hero.controller.grounded) thrown = false }   // landing ends it
+   *     else hero.controller.move(ix * SPEED)                          // …and this reclaims the axis
+   *
+   * Nothing clears the latch by itself, landing included — a kinematic controller has no friction.
+   * Reading is not the inverse of writing: against a wall the read is ~0 and would cancel the throw.
+   *
+   * `c.velocity.y = 700` (the direct spelling) is a jump — the compiler routes it to the exact
+   * `velocityY` channel via `_writeComp` below — and `c.velocity.x = 300` latches the whole vector
+   * with the measured vertical filling in. A STORED copy is still a copy (`const v = c.velocity`).
+   */
+  get velocity(): Vec2 { const s = this._state(); return new Vec2(s[0], s[1]) }
+  set velocity(v: Vec2Like) { if (this._id) _creator2d.characterSetVelocity(this._id, cx(v), cy(v)) }
+
+  /** Compile-time list (chisel reads it, then strips it) — see CharacterController / core/compWrite.ts. */
+  static _comps = [ "velocity" ]
+
+  /** @internal `c.velocity.<axis> = v` compiles to this; see CharacterController. */
+  _writeComp(_prop: string, axis: CompAxis, v: number): void {
+    if (!this._id) return
+    if (axis === "y") { _creator2d.characterSetVerticalVelocity(this._id, v); return }
+    const s = this._state()
+    _creator2d.characterSetVelocity(this._id, axis === "x" ? v : s[0], s[1])
+  }
+
+  /** True while standing on walkable ground. */
+  get grounded(): boolean { return this._state()[2] === 0 }
+
+  /** Where the feet are after the last step: walkable ground, too-steep ground, or the air. */
+  get groundState(): GroundState2D { return GROUND_STATES[this._state()[2]] ?? "air" }
+
+  /** The surface normal under the feet — for orienting a sprite to a slope, or deciding a slide. */
+  get groundNormal(): Vec2 { const s = this._state(); return new Vec2(s[3], s[4]) }
+
+  /** What the character is standing on: a moving platform, a hazard, an ice patch whose `friction`
+   *  the game can read. The engine already carries the character along a kinematic platform. */
+  get groundNode(): Node2D | null {
+    const id = this._state()[5]
+    return id ? node2dRegistry.get(id) ?? null : null
+  }
+
+  /**
+   * Every surface the mover pushed out of during the last step, with the normal pointing back at the
+   * character. This is what wall jumps and box pushing are written against — a kinematic mover is not
+   * a body, so those contacts do not arrive as 'enter' events.
+   *
+   *     const wall = c.collisions.find(h => Math.abs(h.normal.x) > 0.7)
+   *     if (wall && jumpPressed) c.velocity = [-wall.normal.x * KICK, JUMP]
+   *
+   *     for (const h of c.collisions) h.node?.physics?.applyImpulse([-h.normal.x * PUSH, 0])
+   */
+  get collisions(): Collision2D[] {
+    if (!this._id) return []
+    const o = _creator2d.characterGetCollisions(this._id, MAX_COLLISIONS)
+    const out: Collision2D[] = []
+    for (let i = 0; i + 2 < o.length; i += 3) {
+      out.push({ node: o[i] ? node2dRegistry.get(o[i]) ?? null : null, normal: new Vec2(o[i + 1], o[i + 2]) })
+    }
+    return out
+  }
+
+  /** Multiplier over the world gravity; default 1. **0 = free mode**: no gravity, no ground, no
+   *  stick-to-floor — a swimmer, a drone, a ladder climber, or a top-down hero, driven by the
+   *  two-component `move()`. */
+  get gravityScale(): number { return this._gravityScale }
+  set gravityScale(v: number) {
+    this._gravityScale = v
+    if (this._id) _creator2d.characterSetGravityScale(this._id, v)
+  }
+
+  /** Max ground slope (degrees) the character treats as walkable; default 45. Live. */
+  get maxSlope(): number { return this._maxSlope }
+  set maxSlope(v: number) {
+    this._maxSlope = v
+    if (this._id) _creator2d.characterSetMaxSlope(this._id, v)
+  }
+
+  /** Which collision group the character belongs to. Live. */
+  get group(): PhysicsGroup2D | undefined { return this._group }
+  set group(g: PhysicsGroup2D | undefined) { this._group = g; this._repush() }
+
+  /**
+   * While this names a node, that node's `OneWay2D` surfaces are not solid for this character — how
+   * you drop off a semisolid platform. A plain latch: whoever sets it clears it.
+   *
+   *     if (downPressed && jumpPressed && c.grounded) {
+   *       const platform = c.groundNode
+   *       c.dropThrough = platform
+   *       setTimeout(() => { if (c.dropThrough === platform) c.dropThrough = null }, 200)
+   *     }
+   *
+   * Because it names ONE node, the timeout is not delicate: too long merely means you could have
+   * re-landed on that platform for a moment, and the platform below stays solid either way.
+   */
+  get dropThrough(): Node2D | null { return this._dropThrough }
+  set dropThrough(n: Node2D | null) {
+    this._dropThrough = n
+    if (this._id) _creator2d.characterSetDropThrough(this._id, n ? n.id : 0)
+  }
+
+  /**
+   * True while a requested collider resize hasn't taken — you asked to stand up and there is something
+   * overhead. Resizing goes through the `Shape2D` aspect itself:
+   *
+   *     hero.aspect(Shape2D, { capsule: CROUCHED })   // always fits — you are shrinking
+   *     hero.aspect(Shape2D, { capsule: STANDING })   // may be refused under a low ceiling
+   *     if (hero.controller.resizing) …               // still crouched; call it again next frame
+   *
+   * A refusal changes nothing, so the retry is just the same call again — and it is an exact headroom
+   * test against the real capsule, unlike a hand-rolled raycast (a ray is a line; a capsule has
+   * girth). The FEET stay planted across a resize, so the character neither hovers nor sinks.
+   */
+  get resizing(): boolean { return this.node.get(Shape2D)?._resizeRefused ?? false }
+
+  private _state(): Float32Array {
+    if (!this._id) { state.fill(0); state[2] = 2; state[4] = 1; return state }
+    _creator2d.characterGetState(this._id, state)
+    return state
   }
 }

package/runtime/sdk/g2/Node2D.ts

@@ -10,10 +10,12 @@
 // trigger objects — attach a Shape2D (geometry) plus a Physics2D (rigid body) or Trigger2D (sensor).
 
 import { AspectHost } from "../core/Aspect"
+import type { CompAxis, CompWriter } from "../core/compWrite"
 import { Registry } from "../core/registry"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { ensurePointerEvents } from "./touch"
+import { ensurePhysicsEvents } from "./loop"
 
 // re-exported so existing `import { Vec2 } from "./Node2D"` sites keep working; the canonical home is math/.
 export { Vec2, type Vec2Like }
@@ -23,19 +25,26 @@ export type Node2DEvents = {
   loopReached: (clip: string) => void
   /** A non-looping animation clip finished. */
   completed: (clip: string) => void
-  /** A physics contact / sensor overlap began / ended (the other node). */
-  enter: (other: Node2D) => void
-  exit: (other: Node2D) => void
+  /** A physics contact / sensor overlap began (the other node, plus where and how hard). The
+   *  contact's `normal` points AWAY from the other node, so `normal.y > 0.7` reads as "I landed on
+   *  top of it". Sensor overlaps and `exit` carry zeros. */
+  enter: (other: Node2D, contact: Contact2D) => void
+  exit: (other: Node2D, contact: Contact2D) => void
   /** Pointer up over this node's Physics2D shape (a tap/click). */
   click: (ev: ClickEvent<Node2D | null>) => void
   /** Pointer down on this node's Physics2D shape. Call ev.track(...) to capture the drag. */
   touchstart: (ev: TouchStartEvent<Node2D | null>) => void
 }
 
+/** Where a contact happened, delivered as the second argument of 'enter'. `speed` is the approach
+ *  speed at impact (world units/s) — scale an impact sound with it. Zeros on sensor and 'exit'
+ *  events, which have no manifold. */
+export type Contact2D = { point: Vec2, normal: Vec2, speed: number }
+
 /** id → Node2D, so host callbacks (animation events) route back to the owning JS object. */
 export const node2dRegistry = new Registry<Node2D>()
 
-export class Node2D extends AspectHost<Node2DEvents> {
+export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
   /** Native entity handle. */
   readonly id: number
 
@@ -55,6 +64,27 @@ export class Node2D extends AspectHost<Node2DEvents> {
    *  transform, so the transform getters re-sync the cache from native before returning. */
   _physicsDriven = false
 
+  /** @internal The engine object that mirrors this node's transform, if any — a physics body or a
+   *  character (0 = none). WRITES to position / x / y / rotation are routed to it as well, because
+   *  the engine is the authority: on a moving body a plain setPosition is overwritten by the next
+   *  sync, and on a static / sensor body it would leave the COLLIDER behind while the node moved.
+   *  Set by Physics2D, Trigger2D and CharacterController2D. This is what replaced `physics.moveTo`
+   *  and `trigger.moveTo`. */
+  _xf = 0
+  /** @internal What `_xf` is: 1 = character, 2 = physics body. */
+  _xfKind = 0
+
+  // Push this node's (already written) transform into the engine object that owns it. The world math
+  // lives NATIVE — physicsSetFromEntity reads the entity's world matrix — so a parented body converts
+  // through its parent chain without this file re-deriving it.
+  //
+  // NOTE: this fires on a DIRECT write only. A body parented to a node that moves does not follow;
+  // keep bodies and sensors at the root and write their position (see docs/2d-physics-plan.md §6).
+  private _pushXf(): void {
+    if (this._xfKind === 2) _creator2d.physicsSetFromEntity(this._xf)
+    else if (this._xfKind === 1) _creator2d.characterSetFromEntity(this._xf)
+  }
+
   private _parent: Node2D | null = null
   private _children: Node2D[] = []
 
@@ -70,16 +100,32 @@ export class Node2D extends AspectHost<Node2DEvents> {
   private _pull(): void { if (this._physicsDriven) this._syncLocalFromNative() }
 
   get x(): number { this._pull(); return this._x }
-  set x(v: number) { this._pull(); this._x = v; _creator2d.setPosition(this.id, v, this._y) }
+  set x(v: number) { this._pull(); this._x = v; _creator2d.setPosition(this.id, v, this._y); if (this._xf) this._pushXf() }
   get y(): number { this._pull(); return this._y }
-  set y(v: number) { this._pull(); this._y = v; _creator2d.setPosition(this.id, this._x, v) }
+  set y(v: number) { this._pull(); this._y = v; _creator2d.setPosition(this.id, this._x, v); if (this._xf) this._pushXf() }
+
+  /** @internal chisel `comp_write` (see core/compWrite.ts): `node.position.<axis> = v` compiles to a call
+   *  here; the scalar setters carry the physics routing. The list is compile-time data. */
+  static _comps = [ "position" ]
+  _writeComp(_prop: string, axis: CompAxis, v: number): void {
+    if (axis === "x") this.x = v
+    else if (axis === "y") this.y = v
+  }
 
   get position(): Vec2 { this._pull(); return new Vec2(this._x, this._y) }
-  set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.setPosition(this.id, this._x, this._y) }
+  set position(v: Vec2Like) {
+    this._x = cx(v); this._y = cy(v)
+    _creator2d.setPosition(this.id, this._x, this._y)
+    if (this._xf) this._pushXf()
+  }
 
   /** Rotation in degrees (CCW). */
   get rotation(): number { this._pull(); return this._rotation }
-  set rotation(deg: number) { this._rotation = deg; _creator2d.setRotation(this.id, deg) }
+  set rotation(deg: number) {
+    this._rotation = deg
+    _creator2d.setRotation(this.id, deg)
+    if (this._xf) this._pushXf()
+  }
 
   get scale(): Vec2 { return new Vec2(this._sx, this._sy) }
   set scale(v: Vec2Like | number) {
@@ -167,11 +213,25 @@ export class Node2D extends AspectHost<Node2DEvents> {
   _emitAnim(channel: "loopReached" | "completed", clip: string): void { this.dispatch(channel, clip) }
 
   /** @internal — physics contact/sensor events route here (loop.ts) → the node's 'enter'/'exit'. */
-  _emitCollision(channel: "enter" | "exit", other: Node2D): void { this.dispatch(channel, other) }
+  _emitCollision(channel: "enter" | "exit", other: Node2D, contact: Contact2D): void {
+    this.dispatch(channel, other, contact)
+  }
 
-  // Lazily register the host pointer callback when the first click/touchstart listener is added.
+  /** @internal — this node wants contact events. Set by the first 'enter'/'exit' listener; read by
+   *  Physics2D.onAttach for the case where the listener was added BEFORE the body existed. */
+  _wantsContacts = false
+
+  // Lazily wire the host callbacks the listener needs. Contact/sensor events used to be registered
+  // only by Trigger2D.onAttach, so solid-vs-solid 'enter' never fired in a project with no triggers —
+  // and, separately, every solid shape had contact events forced on. Both are fixed here: the channel
+  // is registered by the listener, and the body opts in.
   override addEventListener<K extends keyof Node2DEvents>(channel: K, callback: Node2DEvents[K]): void {
     if (channel === "click" || channel === "touchstart") ensurePointerEvents()
+    else if (channel === "enter" || channel === "exit") {
+      ensurePhysicsEvents()
+      this._wantsContacts = true
+      if (this._xfKind === 2) _creator2d.physicsSetContactEvents(this._xf, true)
+    }
     super.addEventListener(channel, callback)
   }
 
@@ -181,6 +241,16 @@ export class Node2D extends AspectHost<Node2DEvents> {
   }
 
   destroy(): void {
+    // Aspects go first: onDetach runs (a body-owning aspect releases its handle), updaters are
+    // unregistered so a destroyed node never ticks again, listeners are dropped. Children survive
+    // (native reparents them to the root), so only this node's aspects detach.
+    this._detachAll()
+    // Native frees this entity's physics bodies inside destroyEntity (they used to leak — an invisible
+    // collider stayed in the world, and recycled entity ids then delivered its contacts to whoever
+    // inherited the id). Clear the routing so a stale aspect can't push a dead handle.
+    this._xf = 0
+    this._xfKind = 0
+    this._physicsDriven = false
     // Detach from parent; native reparents our children to root (keepWorld), so resync their caches.
     if (this._parent) {
       const arr = this._parent._children