lecodes-sdk 0.19.0

package/src/g2/Camera2D.ts

@@ -0,0 +1,40 @@
+// Orthographic camera for a Scene2D. Position / zoom / rotation live natively. To make the camera
+// track a node, attach a small update(dt) aspect that eases camera.position toward the node — there's
+// 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 implements CompWriter {
+  private _x = 0
+  private _y = 0
+  private _zoom = 1
+  private _rotation = 0
+
+  private readonly sceneId: number
+  constructor(sceneId: number) { this.sceneId = sceneId }
+
+  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) }
+
+  get rotation(): number { return this._rotation }
+  set rotation(deg: number) { this._rotation = deg; _creator2d.cameraSetRotation(this.sceneId, deg) }
+
+  screenToWorld(screenX: number, screenY: number): Vec2 {
+    const o = _creator2d.cameraScreenToWorld(this.sceneId, screenX, screenY)
+    return new Vec2(o[0], o[1])
+  }
+  worldToScreen(worldX: number, worldY: number): Vec2 {
+    const o = _creator2d.cameraWorldToScreen(this.sceneId, worldX, worldY)
+    return new Vec2(o[0], o[1])
+  }
+}

package/src/g2/CharacterController2D.ts

@@ -0,0 +1,276 @@
+// 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, 8], to: [0, 26], radius: 8 } })
+//     .aspect(CharacterController2D)
+//
+//   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 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 { node2dRegistry, type Node2D } from "./Node2D"
+
+/** 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" ]
+
+/** One surface the mover pushed out of this step. `normal` points back at the character. */
+export type Collision2D = { node: Node2D | null, normal: Vec2 }
+
+const MAX_COLLISIONS = 8
+const state = new Float32Array(8)
+let warnedFreeMove = false
+
+export class CharacterController2D extends Aspect<"controller", Node2D> implements CompWriter {
+  static readonly aspect = "controller"
+
+  // 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 {
+    if (!_creator2d.physicsHasSupport || !_creator2d.physicsHasSupport()) return
+    if (!this.node.has(Shape2D)) this.node.aspect(Shape2D, {})
+    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)
+  }
+
+  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
+  }
+
+  /** Native character id (0 until attached / no physics support). */
+  get id(): number { return this._id }
+
+  /**
+   * 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))
+  }
+
+  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.")
+  }
+
+  /** 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/src/g2/Node2D.ts

@@ -0,0 +1,267 @@
+// Base 2D scene node — an empty transform. Sprite and Tilemap extend it, so every node operation
+// (position, layer, visibility, events) works on them. Native (creator-2d) owns the authoritative
+// transform. JS caches it for free reads (JS is normally the sole writer); the exception is a node
+// driven by a dynamic/kinematic Physics2D body — there the native physics step also writes the
+// transform, so such nodes are flagged `_physicsDriven` and their transform getters sync the cache
+// from native first (lazy: only on read, only for moving bodies). So node.position stays correct
+// under physics without any per-frame bookkeeping.
+//
+// Empty Node2Ds are useful as: grouping parents, world-space markers/spawn points, and physics /
+// 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 }
+
+export type Node2DEvents = {
+  /** A looping animation clip wrapped around (fires each loop). */
+  loopReached: (clip: string) => void
+  /** A non-looping animation clip finished. */
+  completed: (clip: string) => 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> implements CompWriter {
+  /** Native entity handle. */
+  readonly id: number
+
+  /** Optional debug/editor name (plain JS data — scene2d files stamp their node names here). */
+  name?: string
+
+  protected _x = 0
+  protected _y = 0
+  protected _rotation = 0
+  protected _sx = 1
+  protected _sy = 1
+  protected _layer = 0
+  protected _z = 0
+  protected _visible = true
+
+  /** @internal — set by Physics2D for a dynamic/kinematic body: the native step owns this node's
+   *  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[] = []
+
+  constructor(internalId?: number) {
+    super()
+    this.id = internalId ?? _creator2d.createEntity()
+    node2dRegistry.set(this.id, this)
+  }
+
+  // --- transform (Y-up, LOCAL to the parent; at zoom 1, units == logical pixels) ---
+  // Pull the native transform into the cache iff physics owns it. No-op for the common case (plain
+  // nodes keep free reads); one native read for a moving body, and only when actually read.
+  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); 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); 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)
+    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)
+    if (this._xf) this._pushXf()
+  }
+
+  get scale(): Vec2 { return new Vec2(this._sx, this._sy) }
+  set scale(v: Vec2Like | number) {
+    const sx = typeof v === "number" ? v : cx(v)
+    const sy = typeof v === "number" ? v : cy(v)
+    this._sx = sx; this._sy = sy
+    _creator2d.setScale(this.id, sx, sy)
+  }
+
+  /** Draw layer (int). Higher layers render on top. */
+  get layer(): number { return this._layer }
+  set layer(v: number) { this._layer = v; _creator2d.setLayer(this.id, v) }
+
+  /** Intra-layer depth for non-Y-sorted layers (higher z = on top). */
+  get z(): number { return this._z }
+  set z(v: number) { this._z = v; _creator2d.setZ(this.id, v) }
+
+  get visible(): boolean { return this._visible }
+  set visible(v: boolean) { this._visible = v; _creator2d.setVisible(this.id, v) }
+
+  // --- hierarchy (parent/child; transforms above are LOCAL to the parent) ---
+  get parent(): Node2D | null { return this._parent }
+  set parent(p: Node2D | null) { this.setParent(p) }
+
+  get children(): readonly Node2D[] { return this._children }
+
+  /** Attach children to this node (each keeps its current world transform). Returns this. */
+  add(...children: Node2D[]): this {
+    for (const c of children) c.setParent(this)
+    return this
+  }
+
+  /** Detach a direct child (reparents it to root, keeping its world transform). Returns this. */
+  remove(child: Node2D): this {
+    if (child._parent === this) child.setParent(null)
+    return this
+  }
+
+  /**
+   * Reparent this node. `keepWorld` (default true) recomputes the local transform so the on-screen
+   * position/rotation/scale is unchanged; pass false to keep the local transform and move with the
+   * new parent. Self/descendant parents are rejected natively (no cycles).
+   */
+  setParent(parent: Node2D | null, keepWorld = true): this {
+    if (parent === this) return this
+    if (this._parent) {
+      const arr = this._parent._children
+      const i = arr.indexOf(this)
+      if (i >= 0) arr.splice(i, 1)
+    }
+    this._parent = parent
+    if (parent) parent._children.push(this)
+    _creator2d.setParent(this.id, parent?.id ?? 0, keepWorld)
+    if (keepWorld) this._syncLocalFromNative()   // native recomputed our local transform
+    return this
+  }
+
+  /** World-space position (composes all ancestors). */
+  get worldPosition(): Vec2 {
+    const o = _creator2d.getWorldPosition(this.id)
+    return new Vec2(o[0], o[1])
+  }
+
+  /** Convert a world-space point into this node's local space (and back). */
+  worldToLocal(p: Vec2Like): Vec2 {
+    const o = _creator2d.worldToLocal(this.id, cx(p), cy(p))
+    return new Vec2(o[0], o[1])
+  }
+  localToWorld(p: Vec2Like): Vec2 {
+    const o = _creator2d.localToWorld(this.id, cx(p), cy(p))
+    return new Vec2(o[0], o[1])
+  }
+
+  private _syncLocalFromNative(): void {
+    const t = _creator2d.getLocalTransform(this.id)   // [x, y, rotDeg, sx, sy]
+    this._x = t[0]; this._y = t[1]; this._rotation = t[2]; this._sx = t[3]; this._sy = t[4]
+  }
+
+  /** @internal — host animation events route here by id; the SpriteAnimation aspect installs an
+   *  instance override that translates clip ids to names and emits 'loopReached' / 'completed'. */
+  _dispatchAnimEvent(_clipId: number, _type: number): void {}
+
+  /** @internal — emit a translated animation event (the SpriteAnimation aspect can't reach the
+   *  protected dispatch directly). */
+  _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, contact: Contact2D): void {
+    this.dispatch(channel, other, contact)
+  }
+
+  /** @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)
+  }
+
+  /** @internal — the pointer system (g2/touch.ts) fires click/touchstart here. */
+  _dispatchEvent<K extends keyof Node2DEvents>(channel: K, ...args: Parameters<Node2DEvents[K]>): void {
+    this.dispatch(channel, ...args)
+  }
+
+  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
+      const i = arr.indexOf(this)
+      if (i >= 0) arr.splice(i, 1)
+      this._parent = null
+    }
+    const orphans = this._children.slice()
+    this._children.length = 0
+    node2dRegistry.delete(this.id)
+    _creator2d.destroyEntity(this.id)
+    for (const c of orphans) { c._parent = null; c._syncLocalFromNative() }
+  }
+}

package/src/g2/OneWay2D.ts

@@ -0,0 +1,66 @@
+// A one-way surface, as an aspect on a Node2D that already carries a Shape2D and a Physics2D body:
+// solid from one side, passable from the other. The semisolid ledge of every platformer.
+//
+//   const ledge = new Sprite({ texture: plank, size: [128, 8] })
+//     .aspect(Shape2D, {})
+//     .aspect(Physics2D, { motion: 'static' })
+//     .aspect(OneWay2D)                      // jump up through it, stand on top
+//
+// It is an ASPECT and not a flag on Shape2D on purpose: Shape2D is geometry, and which side of a
+// surface is solid is behaviour. Keeping them apart is also what lets `normal` generalise the thing —
+// a one-way WALL you can only walk through from the left is the same aspect turned sideways.
+//
+// Honoured by the character's mover AND, through a native pre-solve callback, by ordinary rigid
+// bodies (a crate falls onto the ledge from above and passes up through it from below). Neither path
+// costs any JS per frame.
+//
+// Dropping DOWN through one is the character's business, not the surface's — see
+// `CharacterController2D.dropThrough`.
+
+import { Aspect } from "../core/Aspect"
+import { cx, cy, type Vec2Like } from "../math/vec"
+import { Physics2D } from "./Physics2D"
+import type { Node2D } from "./Node2D"
+
+export class OneWay2D extends Aspect<"oneWay", Node2D> {
+  static readonly aspect = "oneWay"
+
+  private _normal: Vec2Like = [ 0, 1 ]
+  private _arc = 90
+  private _enabled = true
+
+  /** Which side is solid. Default `[0, 1]` — solid from above, i.e. a floor you pass through from
+   *  below. `[1, 0]` is a wall you can only enter from the left. */
+  get normal(): Vec2Like { return this._normal }
+  set normal(v: Vec2Like) { this._normal = v; this._push() }
+
+  /** How far off `normal` an approach still counts as coming from the solid side, in degrees.
+   *  Default 90 — the whole half-plane, which is what a platform wants. */
+  get arc(): number { return this._arc }
+  set arc(v: number) { this._arc = v; this._push() }
+
+  /** Turn the one-way behaviour off, making the surface solid from both sides again. */
+  get enabled(): boolean { return this._enabled }
+  set enabled(v: boolean) { this._enabled = v; this._push() }
+
+  onAttach(): void {
+    if (!this.node.has(Physics2D)) {
+      throw new Error("OneWay2D needs a Physics2D body on the same node — add it first: node.aspect(Shape2D, {…}).aspect(Physics2D, { motion: 'static' }).aspect(OneWay2D)")
+    }
+    this._push()
+  }
+
+  onDetach(): void {
+    const id = this.node.get(Physics2D)?.id
+    if (id) _creator2d.physicsSetOneWay(id, 0, 1, 90, false)
+  }
+
+  onReconfigure(): void { this._push() }
+
+  private _push(): void {
+    const id = this.node.get(Physics2D)?.id
+    // via the public accessors on purpose: an accessor pair that is only ever an object-literal key
+    // gets tree-shaken away, and the option would silently do nothing (see Physics2D.onAttach).
+    if (id) _creator2d.physicsSetOneWay(id, cx(this.normal), cy(this.normal), this.arc, this.enabled)
+  }
+}