lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/g2/Shape2D.ts

@@ -7,12 +7,31 @@
 //   goal.aspect(Shape2D, { circle: 20 }).aspect(Trigger2D)
 //   hero.aspect(Shape2D, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
 //
-// With no geometry set, Shape2D derives a box from the node's sprite size ("auto").
+// With no geometry set, Shape2D derives a box from WHAT THE NODE DRAWS — the sprite's size scaled by
+// the node, positioned by its anchor. So `aspect(Shape2D, {})` on a sprite anchored at its feet gives
+// a collider that wraps the art instead of one centred on the pivot (half of it underground), which
+// is why every character used to carry a hand-computed offset.
+//
+// RE-CONFIGURING REBUILDS IT IN PLACE: `node.aspect(Shape2D, { capsule: … })` on a live node swaps the
+// fixture while the body keeps its id, its velocity and its place in the world. That is what makes a
+// crouch (and a live editor edit) possible.
 
 import { Aspect } from "../core/Aspect"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import { ALL_GROUPS } from "./groups2d"
 import type { Node2D } from "./Node2D"
 
+/** @internal How an owner (Physics2D / Trigger2D) wants the geometry realised. */
+export type ShapeFixture2D = {
+  sensor: boolean
+  friction: number
+  bounce: number
+  category?: number
+  mask?: number
+  /** Chains carry no mass, so Box2D only accepts them on a static body. */
+  staticBody?: boolean
+}
+
 export class Shape2D extends Aspect<"shape", Node2D> {
   static readonly aspect = "shape"
 
@@ -22,42 +41,219 @@ export class Shape2D extends Aspect<"shape", Node2D> {
   circle?: number
   /** Capsule between two local points, with a radius. */
   capsule?: { from: Vec2Like, to: Vec2Like, radius: number }
-  /** Thin segment (an edge — for static ground/walls/slopes) between two local points. */
+  /** Thin segment (an edge) between two local points. */
   segment?: { from: Vec2Like, to: Vec2Like }
-  /** Convex polygon, up to 8 local points (a convex hull is computed). */
+  /** Convex polygon, up to 8 local points (a convex hull is computed — a CONCAVE outline silently
+   *  becomes its hull; use `chain` for those). */
   polygon?: Vec2Like[]
-  /** Local offset of the shape from the node origin. */
-  offset?: Vec2Like
+  /**
+   * A polyline of connected segments — the one shape that expresses a long CONCAVE surface (rolling
+   * terrain, a cave wall) in one piece, seam-free. Pass only the points that should be solid; the
+   * tangent points Box2D needs at the ends are synthesised here.
+   *
+   * STATIC bodies only (a polyline has no area, so no mass), at least 2 points (4 with `loop`), and it
+   * must not self-intersect. It is ONE-SIDED: solid on the right of the point order — walk the points
+   * so that the solid material is on your right, or set `flip`.
+   */
+  chain?: Vec2Like[]
+  /** `chain`: close the contour (an island / a room boundary). Needs at least 4 points. */
+  loop?: boolean
+  /** `chain`: put the solid side on the other side of the line. */
+  flip?: boolean
+  /** The collider's centre relative to the node, in world units. Applies to EVERY kind — it
+   *  translates a capsule's / segment's / polygon's / chain's points too, unlike the old `offset`. */
+  origin?: Vec2Like
+
+  /** @internal Geometry as of the last build — an unchanged signature means nothing to rebuild. */
+  private _sig = ""
+  /** @internal The last resize the CHARACTER refused (backs `controller.resizing`). */
+  _resizeRefused = false
+  /** @internal How the owner asked for it, so a rebuild can replay the same fixture. */
+  private _fx: ShapeFixture2D | null = null
+  private _handle = 0
+
+  /** @internal — the character claimed this shape; record the geometry so a later re-configure is
+   *  compared against it. */
+  _claimedByCharacter(): void { this._sig = this._signature(); this._resizeRefused = false }
+
+  /** @internal — realise this geometry as a fixture on `handle` (a body from Physics2D/Trigger2D). */
+  _addTo(handle: number, fx: ShapeFixture2D): void {
+    this._handle = handle
+    this._fx = fx
+    this._sig = this._signature()
+    this._create()
+  }
+
+  /** @internal — the owner's material changed live; keep it for the next rebuild. */
+  _setMaterial(friction: number, bounce: number): void {
+    if (this._fx) { this._fx.friction = friction; this._fx.bounce = bounce }
+  }
+
+  /** @internal — the owner's filter changed live. */
+  _setFilter(category: number, mask: number): void {
+    if (this._fx) { this._fx.category = category; this._fx.mask = mask }
+  }
+
+  onDetach(): void { this._handle = 0; this._fx = null; this._sig = ""; this._resizeRefused = false }
 
   /**
-   * @internal — add this geometry as a fixture to `handle` (a body created by Physics2D/Trigger2D).
-   * `sensor` selects a sensor (trigger) vs solid fixture; density/friction/restitution are the
-   * material (ignored for sensors / segments only use friction+restitution).
+   * Re-configuring the aspect swaps the fixture in place — same body, same id, same velocity, same
+   * position. Nothing happens when the geometry is unchanged, so re-applying the same options in a
+   * loop is free.
    */
-  _addTo(handle: number, sensor: boolean, density: number, friction: number, restitution: number): void {
-    const ox = this.offset ? cx(this.offset) : 0
-    const oy = this.offset ? cy(this.offset) : 0
-    if (this.circle !== undefined) {
-      _creator2d.physicsAddCircle(handle, this.circle, ox, oy, density, friction, restitution, sensor)
+  onReconfigure(): void {
+    const sig = this._signature()
+    if (sig === this._sig) return
+
+    // A CharacterController2D owns this shape instead of a body: resizing goes to the mover, which
+    // VALIDATES it (you cannot stand up under a low pipe) and can refuse.
+    if (this.node._xfKind === 1) {
+      const cap = this._capsule()
+      const ok = _creator2d.characterSetCapsule(this.node._xf, cap.x1, cap.y1, cap.x2, cap.y2, cap.radius)
+      // On refusal NOTHING changed — so DON'T commit the signature. The next identical
+      // `aspect(Shape2D, …)` then still sees a difference and retries; committing here would swallow
+      // every retry for good, which is the whole trap in this design.
+      this._resizeRefused = !ok
+      if (ok) this._sig = sig
+      return
+    }
+
+    if (!this._handle || !this._fx) return
+    this._sig = sig
+    _creator2d.physicsClearShapes(this._handle)
+    this._create()
+  }
+
+  /**
+   * @internal — this geometry as a CAPSULE, for CharacterController2D (the mover takes nothing else).
+   * An explicit capsule is used as given; anything else is derived from the drawn rect, so
+   * `aspect(Shape2D, {})` on a sprite gives a capsule that wraps the art.
+   */
+  _capsule(): { x1: number, y1: number, x2: number, y2: number, radius: number } {
+    const ox = this.origin ? cx(this.origin) : 0
+    const oy = this.origin ? cy(this.origin) : 0
+    if (this.capsule) {
+      const { from, to, radius } = this.capsule
+      return { x1: cx(from) + ox, y1: cy(from) + oy, x2: cx(to) + ox, y2: cy(to) + oy, radius }
+    }
+    if (this.circle !== undefined) return { x1: ox, y1: oy, x2: ox, y2: oy, radius: this.circle }
+    let hw = 8, hh = 8, bx = ox, by = oy
+    if (this.box) { hw = cx(this.box); hh = cy(this.box) }
+    else {
+      const a = this._autoBox()
+      hw = a.hw; hh = a.hh
+      if (!this.origin) { bx = a.x; by = a.y }
+    }
+    const radius = Math.min(hw, hh)
+    const half = Math.max(0, hh - radius)
+    return { x1: bx, y1: by - half, x2: bx, y2: by + half, radius }
+  }
+
+  // ---- internals ---------------------------------------------------------------------------------
+
+  private _create(): void {
+    const fx = this._fx!
+    const handle = this._handle
+    const category = fx.category ?? ALL_GROUPS
+    const mask = fx.mask ?? ALL_GROUPS
+    const ox = this.origin ? cx(this.origin) : 0
+    const oy = this.origin ? cy(this.origin) : 0
+
+    if (this.chain) {
+      this._createChain(handle, fx, category, mask, ox, oy)
+    } else if (this.circle !== undefined) {
+      _creator2d.physicsAddCircle(handle, this.circle, ox, oy, fx.friction, fx.bounce, fx.sensor, category, mask)
     } else if (this.capsule) {
       const { from, to, radius } = this.capsule
-      _creator2d.physicsAddCapsule(handle, cx(from), cy(from), cx(to), cy(to), radius, density, friction, restitution, sensor)
+      _creator2d.physicsAddCapsule(handle, cx(from) + ox, cy(from) + oy, cx(to) + ox, cy(to) + oy, radius,
+                                   fx.friction, fx.bounce, fx.sensor, category, mask)
     } else if (this.segment) {
-      _creator2d.physicsAddSegment(handle, cx(this.segment.from), cy(this.segment.from), cx(this.segment.to), cy(this.segment.to), friction, restitution)
+      const { from, to } = this.segment
+      _creator2d.physicsAddSegment(handle, cx(from) + ox, cy(from) + oy, cx(to) + ox, cy(to) + oy,
+                                   fx.friction, fx.bounce, category, mask)
     } else if (this.polygon) {
       const pts = new Float32Array(this.polygon.length * 2)
-      this.polygon.forEach((p, i) => { pts[i * 2] = cx(p); pts[i * 2 + 1] = cy(p) })
-      _creator2d.physicsAddPolygon(handle, pts, this.polygon.length, density, friction, restitution, sensor)
+      this.polygon.forEach((p, i) => { pts[i * 2] = cx(p) + ox; pts[i * 2 + 1] = cy(p) + oy })
+      _creator2d.physicsAddPolygon(handle, pts, this.polygon.length, fx.friction, fx.bounce, fx.sensor, category, mask)
     } else {
-      // box: explicit half-extents, or "auto" from the node's sprite size (fallback 8×8).
-      let hw = 8, hh = 8
+      // box: explicit half-extents, or "auto" — the rect the node actually draws.
+      let hw = 8, hh = 8, bx = ox, by = oy
       if (this.box) {
         hw = cx(this.box); hh = cy(this.box)
       } else {
-        const size = (this.node as { size?: Vec2 }).size
-        if (size) { hw = size.x * 0.5; hh = size.y * 0.5 }
+        const auto = this._autoBox()
+        hw = auto.hw; hh = auto.hh
+        if (!this.origin) { bx = auto.x; by = auto.y }   // an explicit origin still wins
       }
-      _creator2d.physicsAddBox(handle, hw, hh, ox, oy, density, friction, restitution, sensor)
+      _creator2d.physicsAddBox(handle, hw, hh, bx, by, fx.friction, fx.bounce, fx.sensor, category, mask)
+    }
+  }
+
+  /**
+   * Box2D's chain wants the two TANGENT points as extra entries and does not collide on its first or
+   * last edge — pass it your outline verbatim and you lose both end segments (four points give ONE).
+   * So the caller passes only the solid points and the ends are extrapolated here: `p0 + (p0 - p1)`.
+   * A loop needs none of that (every point is interior) but does need 4 of them.
+   */
+  private _createChain(handle: number, fx: ShapeFixture2D, category: number, mask: number, ox: number, oy: number): void {
+    const src = this.chain!
+    const loop = this.loop === true
+    if (src.length < (loop ? 4 : 2)) {
+      throw new Error(`Shape2D chain needs at least ${loop ? 4 : 2} points (got ${src.length})${loop ? " — a closed contour of 3 is a polygon" : ""}`)
+    }
+    if (fx.staticBody === false) {
+      throw new Error("Shape2D { chain } works on a STATIC body only — a polyline has no area, so no mass. Use polygon/box for a dynamic body.")
     }
+    const order = this.flip === true ? [ ...src ].reverse() : src
+    const p: number[] = []
+    if (!loop) {
+      // leading ghost: mirror the first point across the second
+      p.push(2 * cx(order[0]) - cx(order[1]) + ox, 2 * cy(order[0]) - cy(order[1]) + oy)
+    }
+    for (const v of order) p.push(cx(v) + ox, cy(v) + oy)
+    if (!loop) {
+      const n = order.length
+      p.push(2 * cx(order[n - 1]) - cx(order[n - 2]) + ox, 2 * cy(order[n - 1]) - cy(order[n - 2]) + oy)
+    }
+    _creator2d.physicsAddChain(handle, new Float32Array(p), p.length / 2, loop, fx.friction, fx.bounce, category, mask)
+  }
+
+  // Everything that changes the GEOMETRY, so a re-configure that only touches the material is free.
+  private _signature(): string {
+    const o = this.origin ? `${cx(this.origin)},${cy(this.origin)}` : ""
+    if (this.chain) return `chain:${this.chain.map(v => `${cx(v)},${cy(v)}`).join(";")}|${this.loop}|${this.flip}|${o}`
+    if (this.circle !== undefined) return `circle:${this.circle}|${o}`
+    if (this.capsule) {
+      const { from, to, radius } = this.capsule
+      return `cap:${cx(from)},${cy(from)},${cx(to)},${cy(to)},${radius}|${o}`
+    }
+    if (this.segment) {
+      const { from, to } = this.segment
+      return `seg:${cx(from)},${cy(from)},${cx(to)},${cy(to)}|${o}`
+    }
+    if (this.polygon) return `poly:${this.polygon.map(v => `${cx(v)},${cy(v)}`).join(";")}|${o}`
+    if (this.box) return `box:${cx(this.box)},${cy(this.box)}|${o}`
+    const a = this._autoBox()
+    return `auto:${a.hw},${a.hh},${a.x},${a.y}|${o}`
+  }
+
+  /**
+   * @internal — half-extents and centre of the rect this node DRAWS, in the node's own frame.
+   *
+   * Sprite anchor space is Y-DOWN while the world is Y-up (see docs/conventions.md), so `anchor: [.5, 1]`
+   * ("feet") puts the art ABOVE the origin: its centre sits at +h/2. A node with no sprite falls back
+   * to 8x8 at the origin. This is a SNAPSHOT taken when the fixture is built — growing the sprite later
+   * does not resize the collider; re-configure the aspect to re-measure.
+   */
+  private _autoBox(): { hw: number, hh: number, x: number, y: number } {
+    const n = this.node as { size?: Vec2, anchor?: Vec2, scale?: Vec2 }
+    const size = n.size
+    if (!size || !(size.x > 0) || !(size.y > 0)) return { hw: 8, hh: 8, x: 0, y: 0 }
+    const sx = n.scale ? Math.abs(n.scale.x) : 1
+    const sy = n.scale ? Math.abs(n.scale.y) : 1
+    const w = size.x * sx, h = size.y * sy
+    const ax = n.anchor ? n.anchor.x : 0.5
+    const ay = n.anchor ? n.anchor.y : 0.5
+    return { hw: w * 0.5, hh: h * 0.5, x: (0.5 - ax) * w, y: (ay - 0.5) * h }
   }
 }

package/runtime/sdk/g2/Trigger2D.ts

@@ -1,25 +1,43 @@
-// A trigger zone, as an aspect on a Node2D. Requires a Shape2D (its geometry); creates a static SENSOR
-// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
-// instead of colliding. A trigger does not block movement.
+// A trigger zone, as an aspect on a Node2D. Requires a Shape2D (its geometry); creates a SENSOR body
+// from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events instead of
+// colliding. A trigger does not block movement.
 //
-//   const goal = new Node2D({ ... })
+//   const goal = new Node2D()
 //     .aspect(Shape2D, { box: [32, 64] })
 //     .aspect(Trigger2D)
 //   goal.addEventListener('enter', other => win(other))
-//   goal.addEventListener('exit',  other => ...)
+//   goal.position = [x, y]        // the zone follows — it is kinematic, not static
+//   goal.trigger.enabled = false  // switch it off instead of parking it off-screen
 //
 // (A trigger is still pointer-pickable — clicks hit sensor shapes too.)
+//
+// Keep triggers on ROOT nodes: a sensor parented to a moving node does not follow it (see
+// docs/2d-physics-plan.md §6).
 
 import { Aspect } from "../core/Aspect"
-import { cx, cy, type Vec2Like } from "../math/vec"
 import { ensurePhysicsEvents } from "./loop"
 import { Shape2D } from "./Shape2D"
+import { PhysicsGroup2D, _watchGroupChanges, _unwatchGroupChanges, categoryOf, sensorMask } from "./groups2d"
 import type { Node2D } from "./Node2D"
 
 export class Trigger2D extends Aspect<"trigger", Node2D> {
   static readonly aspect = "trigger"
 
   private _h = 0
+  private _enabled = true
+  private _group: PhysicsGroup2D | undefined
+  private _repush = (): void => {
+    if (this._h) _creator2d.physicsSetFilter(this._h, categoryOf(this._group), sensorMask(this._group))
+  }
+
+  /** Which collision group this zone belongs to. Live. */
+  get group(): PhysicsGroup2D | undefined { return this._group }
+  set group(g: PhysicsGroup2D | undefined) {
+    this._group = g
+    this.node.get(Shape2D)?._setFilter(categoryOf(g), sensorMask(g))
+    this._repush()
+  }
+
   /** Native physics body id (0 if no physics support). Mirrors 3D `Trigger.id`. */
   get id(): number { return this._h }
 
@@ -29,19 +47,31 @@ export class Trigger2D extends Aspect<"trigger", Node2D> {
     if (!shape) {
       throw new Error("Trigger2D requires a Shape2D aspect — add it first: node.aspect(Shape2D, {…}).aspect(Trigger2D)")
     }
-    this._h = _creator2d.physicsCreateBody(this.node.id, 0 /* static */)
+    // KINEMATIC, not static: a zone has to be able to ride an elevator, a patrolling enemy or a
+    // fighter's fist. It used to be static, which is why games parked spent triggers at [-9999,-9999].
+    this._h = _creator2d.physicsCreateBody(this.node.id, 1 /* kinematic */)
     if (!this._h) return
-    shape._addTo(this._h, true /* sensor */, 1, 0, 0)
+    // sensorMask always keeps the character bit: a kinematic mover is not a Box2D body, so its shadow
+    // body is what triggers actually see, and no game should have to know that.
+    shape._addTo(this._h, { sensor: true, friction: 0, bounce: 0, category: categoryOf(this.group), mask: sensorMask(this.group) })
+    if (this._group) _watchGroupChanges(this._repush)
+    this.node._xf = this._h        // node.position moves the zone
+    this.node._xfKind = 2
+    if (!this.enabled) _creator2d.physicsSetEnabled(this._h, false)   // via the accessor on purpose — see Physics2D.onAttach
     ensurePhysicsEvents()   // routes contact/sensor events → the node's 'enter' / 'exit'
   }
 
   onDetach(): void {
+    _unwatchGroupChanges(this._repush)
     if (this._h) { _creator2d.physicsRemoveBody(this._h); this._h = 0 }
+    this.node._xf = 0
+    this.node._xfKind = 0
   }
 
-  /** Reposition the trigger zone to a world point. */
-  moveTo(p: Vec2Like): this {
-    if (this._h) _creator2d.physicsSetTransform(this._h, cx(p), cy(p), 0)
-    return this
+  /** Switch the zone off and on — a spent pickup, a hitbox that is only live during a swing. */
+  get enabled(): boolean { return this._enabled }
+  set enabled(v: boolean) {
+    this._enabled = v
+    if (this._h) _creator2d.physicsSetEnabled(this._h, v)
   }
 }

package/runtime/sdk/g2/groups2d.ts

@@ -0,0 +1,106 @@
+// Collision groups — which bodies are allowed to touch which. Called groups, not layers, because
+// `layer` already means DRAW order in 2D (`node.layer`, `scene2d.layer(n).ySort()`).
+//
+//   // game/groups.ts
+//   export const player  = Physics2D.addGroup()
+//   export const bullets = Physics2D.addGroup().ignoreSelf().ignore(player)
+//
+//   bullet.aspect(Physics2D, { motion: 'dynamic', group: bullets })
+//
+// Two decisions worth knowing, both deliberate:
+//
+// SUBTRACTIVE, not enumerative. A group collides with everything EXCEPT what it ignores, so adding a
+// new group later cannot silently stop existing pairs from colliding. The enumerative form —
+// "collides only with [ground, enemy]" — decays: introduce `crate` a month later and the bullets
+// start flying through it, with nothing to notice.
+//
+// SYMMETRIC. Box2D's filter is an AND of two masks, so declaring the relation on one side only is the
+// classic trap ("A allowed B but B didn't allow A" → they silently pass through). Both sides are set
+// from one undirected edge here, so naming it once is enough.
+//
+// Budget: 32 bits, because a category/mask must cross the bridge as a plain JS number and only 2^32 is
+// exactly representable there. One bit is the implicit default group, one is reserved for the
+// character's shadow body — 30 user groups.
+
+/** Collides with everything. */
+export const ALL_GROUPS = 0xffffffff
+
+/** @internal Bit 0 — every body that never names a group. */
+export const DEFAULT_BIT = 1 << 0
+/** @internal Bit 1 — the character's shadow body: solid shapes never see it, sensors always do. */
+export const CHARACTER_BIT = 1 << 1
+
+const MAX_USER_GROUPS = 30
+let nextBit = 2
+const all: PhysicsGroup2D[] = []
+
+// Bodies whose filter has to be re-pushed when the topology changes. Only bodies that actually named
+// a group register, so a project that never touches groups keeps an empty set.
+const listeners = new Set<() => void>()
+/** @internal */
+export const _watchGroupChanges = (fn: () => void): void => { listeners.add(fn) }
+/** @internal */
+export const _unwatchGroupChanges = (fn: () => void): void => { listeners.delete(fn) }
+
+export class PhysicsGroup2D {
+  /** The single category bit this group owns. */
+  readonly bit: number
+  /** Optional debug label, so an inspector says "bullets" rather than "group #3". */
+  readonly label: string
+
+  private _ignored = 0
+
+  /** @internal — use `Physics2D.addGroup()`. */
+  constructor(bit: number, label: string) {
+    this.bit = bit
+    this.label = label
+  }
+
+  /** @internal The Box2D pair for a shape in this group. */
+  get category(): number { return this.bit }
+  /** @internal */
+  get mask(): number { return (ALL_GROUPS & ~this._ignored) >>> 0 }
+
+  /**
+   * Stop colliding with these groups — symmetric, so naming it on one side is enough. Safe to call
+   * after bodies exist: their filters are re-pushed.
+   */
+  ignore(...groups: PhysicsGroup2D[]): this {
+    for (const g of groups) {
+      this._ignored |= g.bit
+      g._ignored |= this.bit
+    }
+    for (const fn of listeners) fn()
+    return this
+  }
+
+  /** Members of this group don't collide with EACH OTHER — bullets, debris, a ragdoll's own bones. */
+  ignoreSelf(): this {
+    this._ignored |= this.bit
+    for (const fn of listeners) fn()
+    return this
+  }
+}
+
+/** @internal The implicit group of every body that never names one. */
+export const defaultGroup = new PhysicsGroup2D(DEFAULT_BIT, "default")
+
+/** @internal Register a new group (see `Physics2D.addGroup`). */
+export const _addGroup = (label = ""): PhysicsGroup2D => {
+  if (nextBit >= 2 + MAX_USER_GROUPS) {
+    throw new Error(`Physics2D.addGroup: out of collision groups (${MAX_USER_GROUPS} max — a category has to cross the bridge as a 32-bit number, and two bits are reserved).`)
+  }
+  const g = new PhysicsGroup2D((1 << nextBit) >>> 0, label || `group${nextBit - 1}`)
+  nextBit++
+  all.push(g)
+  return g
+}
+
+/** @internal Sensors must always be visible to the character's shadow body, solids never. */
+export const sensorMask = (g: PhysicsGroup2D | undefined): number =>
+  (((g ?? defaultGroup).mask | CHARACTER_BIT) & ALL_GROUPS) >>> 0
+/** @internal */
+export const solidMask = (g: PhysicsGroup2D | undefined): number =>
+  (((g ?? defaultGroup).mask & ~CHARACTER_BIT) & ALL_GROUPS) >>> 0
+/** @internal */
+export const categoryOf = (g: PhysicsGroup2D | undefined): number => (g ?? defaultGroup).category

package/runtime/sdk/g2/loop.ts

@@ -5,6 +5,7 @@
 // The animation-event registration is lazy (first use) so a 2D project that never animates a sprite
 // pulls none of this in.
 
+import { Vec2 } from "../math/vec"
 import { node2dRegistry } from "./Node2D"
 
 export const onUpdate = (callback: (dt: number) => void): void => _creator2d.onUpdate(callback)
@@ -23,17 +24,27 @@ export const ensureAnimEvents = (): void => {
 
 // Route native physics contact/sensor events to the owning nodes' 'enter'/'exit' events. Each event
 // is delivered to BOTH nodes with the other as the argument. type: 0 contactBegin, 1 contactEnd,
-// 2 sensorBegin, 3 sensorEnd. Registered lazily on the first physics body.
+// 2 sensorBegin, 3 sensorEnd. Registered lazily by the first 'enter'/'exit' listener (Node2D) or the
+// first Trigger2D — it used to hang off Trigger2D alone, so solid-vs-solid contacts silently never
+// fired in a project without a single trigger.
+//
+// A contact BEGIN also carries the manifold, which the listener gets as a second argument: the world
+// point, the surface normal, and the approach speed. The normal points from A to B, so it is FLIPPED
+// for the second delivery — each side gets the normal pointing away from the thing it hit, which is
+// what "did I land on top or hit a wall" needs.
 let physicsEventsRegistered = false
 export const ensurePhysicsEvents = (): void => {
   if (physicsEventsRegistered) return
   physicsEventsRegistered = true
-  _creator2d.setOnPhysicsEvent((a, b, type) => {
+  _creator2d.setOnPhysicsEvent((a, b, type, px, py, nx, ny, speed) => {
     const na = node2dRegistry.get(a)
     const nb = node2dRegistry.get(b)
     if (!na || !nb) return
     const channel = type === 1 || type === 3 ? "exit" : "enter"
-    na._emitCollision(channel, nb)
-    nb._emitCollision(channel, na)
+    // Box2D's manifold normal points from A TOWARD B. Each listener wants the normal of the surface
+    // it hit, pointing back at itself — so A gets it negated and B gets it as-is. Landing on a floor
+    // then reads normal.y ≈ +1 for the falling body, which is the test a game actually writes.
+    na._emitCollision(channel, nb, { point: new Vec2(px, py), normal: new Vec2(-nx, -ny), speed })
+    nb._emitCollision(channel, na, { point: new Vec2(px, py), normal: new Vec2(nx, ny), speed })
   })
 }

package/runtime/sdk/gl/Camera.ts

@@ -2,9 +2,23 @@
 // screen↔world ray helpers. Created and attached by Scene. Ported from worker/src/components/Camera.ts.
 
 import { Vec3 } from "../math/vec"
+import { Aspect } from "../core/Aspect"
 import { Node } from "./Node"
 import { Ray } from "./Ray"
 
+/** @internal `camera.follow(node)`: copies the node's world pose onto the camera every LATE frame
+ *  (order 1000 — after every other aspect has moved things). One per camera; lives on the target. */
+export class CameraFollowRig extends Aspect<"__cameraFollow"> {
+  static readonly aspect = "__cameraFollow"
+  /** @internal */ _camera!: Camera
+  constructor() { super(); this.updateOrder = 1000 }
+  update(): void {
+    const cam = this._camera
+    cam.position = this.node.worldPosition
+    cam.quaternion = this.node.worldQuaternion
+  }
+}
+
 /** Projection every host starts a scene with (creator-gl scene.cpp / the lite core agree on these). */
 export const CAMERA_DEFAULTS = { fov: 60, near: 0.01, far: 1000 }
 
@@ -60,6 +74,33 @@ export class Camera extends Node {
     if (this._sceneId < 0 || typeof _creator.setCameraProjection !== "function") return
     _creator.setCameraProjection(this._sceneId, this._fov, this._near, this._far)
   }
+  private _following: Node | null = null
+  /** The node the camera currently follows (`follow()`), or null. */
+  get following(): Node | null { return this._following }
+
+  /**
+   * Make the camera ride a node: every late frame the camera takes the node's WORLD pose (−Z =
+   * view direction), so movement aspects / animation on that node are camera moves — dolly shots,
+   * a cutscene path, a `CameraPlace` in a scene file. A node carrying a `CameraPlace` also hands
+   * over its projection (fov / near / far). `follow(null)` releases the camera where it is.
+   * One camera per scene: following a new node stops following the previous one.
+   */
+  follow(target: Node | { node: Node, applyTo(camera: Camera): void } | null): this {
+    const node = target === null ? null : target instanceof Node ? target : target.node
+    if (this._following && this._following !== node) this._following.removeAspect(CameraFollowRig)
+    this._following = node
+    if (!node) return this
+    // a CameraPlace on the node (or passed directly) sets the lens too
+    const place = target instanceof Node
+      ? (node as unknown as { cameraPlace?: { applyTo(camera: Camera): void } }).cameraPlace
+      : target as { applyTo(camera: Camera): void }
+    place?.applyTo(this)
+    node.aspect(CameraFollowRig, { _camera: this })
+    this.position = node.worldPosition
+    this.quaternion = node.worldQuaternion
+    return this
+  }
+
   get displaySize(): [number, number] {
     const s = _creator.getDisplaySize()
     return [ s[0], s[1] ]

package/runtime/sdk/gl/CameraPlace.ts

@@ -0,0 +1,52 @@
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}