lecodes-sdk 2.4.10 → 2.5.0

package/src/g2/Particles2D.ts

@@ -0,0 +1,337 @@
+// A 2D particle system, as a Node2D: fire, sparks, smoke, dust, magic, rain — drawn in the sprite batch,
+// so it sorts by renderPriority / z like any node.
+//
+//   new Particles2D({ rate: 60, lifetime: { min: 0.6, max: 1 }, size: curve(24).to(4),
+//                     startVelocity: { dir: [0, 1], speed: { min: 80, max: 140 }, spread: 0.3 },
+//                     color: colorCurve('#ffd27a').to('#ff3a00'), opacity: curve().fade(0.1, 0.5),
+//                     material: Material2D.additive(), position: [0, -120] })
+//   new Particles2D({ texture: smoke, sheet: [4, 4], rate: 12, gravity: -40, size: curve(40).to(90) })
+//   sparks.spawn(30)   // a burst
+//
+// One simulation and one vocabulary with 3D: the engine hosts creator-particles (the same sim the 3D
+// `Particles` node runs, one system per entity), and the config is the same [tag, payloadLen, ...]
+// records written by the same writers (core/particlesConfig.ts) — the same `curve()` / `colorCurve()`
+// builders, the same param names (`size`, `rotation`, `opacity`, `frame`, `color`), the same units.
+// What differs in 2D:
+//   - the plane: the sim runs PLANAR for a 2D system (the engine sets CPART_TAG_PLANAR at creation):
+//     shapes, launch directions, the velocity jitter and the noise field stay in XY, so a `circle` is a
+//     true disc (a `thickness` 0 one a ring) and a speed with no direction is spent in the plane. Every
+//     vector here is a Vec2 and its z is written 0. Gravity pulls toward -y (the 2D world is Y-up).
+//   - no camera sort: within a system the spawn order is the draw order; `z` / `renderPriority` order
+//     systems.
+//   - the look is a sheet TEXTURE (+ its flipbook grid), not a material: omit it for solid squares of
+//     the particle colour. The blend is the node's Material2D — `Material2D.additive()` for fire and
+//     sparks. No `Particles2D.additive`-style sugar: Material2D IS the blend.
+//   - no mesh mode, no baked light (`lit`), no `order` (z does it), no `stretch`.
+//
+// The node's own `rotation` (degrees, Node2D) is the emitter's; the PARTICLE rotation is the `rotation`
+// option (radians, the 3D convention) — live, through `custom[1]`.
+
+import { Vec2, cx, cy, type Vec2Like, type Vec3Like } from "../math/vec"
+import {
+  MODE_POINTS, MODE_QUADS, MODE_RIBBON, SLOT_FRAME, SLOT_OPACITY, SLOT_ROTATION, SLOT_SIZE,
+  TAG_ACCELERATION, TAG_DRAG, TAG_INHERIT_VELOCITY, TAG_RATE, TAG_RATE_DISTANCE, TAG_RENDER_MODE,
+  TAG_SEED, TAG_SMOOTH_PATH, TAG_SPACE,
+  pushColor, pushDefaultFrames, pushGround, pushLifetime, pushNoise, pushParam, pushShape,
+  pushVelocity, pushVelocityLife,
+  type ParticleColor, type ParticleGround, type ParticleNoise, type ParticleShape, type ParticleValue,
+  type Range, type VelocityValue,
+} from "../core/particlesConfig"
+import { Node2D } from "./Node2D"
+import type { Material2D } from "./Material2D"
+import type { Texture2D } from "./Texture2D"
+
+export type ParticleMode2D = "quads" | "points" | "trail"
+
+/** Where particles are born, in the node's local frame.
+ *  - `point` at `v` (default the origin);
+ *  - `box` between `min` and `max` (a spawn line: give it no height);
+ *  - `circle` of `radius` around `center` — a disc, evenly filled; `thickness` 0 = the outline only (a
+ *    ring). Gives the launch direction (outward) when `startVelocity` has a speed and no direction;
+ *  - `cone` opening along +y from its base of half-width `radius` at `center`: `angle` (half-angle,
+ *    radians) flares it, `length` emits that far up the axis too; launches away from the apex.
+ *  `thickness` 0 = the outline only, 1 (default) = the whole area. */
+export type ParticleShape2D =
+  | { type: "point", v?: Vec2Like }
+  | { type: "box", min: Vec2Like, max: Vec2Like }
+  | { type: "circle", center?: Vec2Like, radius: number, thickness?: number }
+  | { type: "cone", center?: Vec2Like, radius: number, angle?: number, length?: number, thickness?: number }
+
+/** A start velocity by direction + speed. `dir` launches along a vector, `from` away from a point,
+ *  `to` toward one; with none, a sphere / cone `shape` gives the direction, else a random one.
+ *  `spread` jitters the direction by up to ± that angle (radians, in the plane). */
+export type VelocityValue2D = {
+  speed?: Range<number>
+  spread?: number
+} & ({ from: Vec2Like } | { to: Vec2Like } | { dir: Vec2Like } | {})
+
+/** Extra velocity over each particle's life, ADDED as a displacement: `radial` along its birth
+ *  direction (a burst that decays: `curve(200).to(0)`), `x` / `y` a drift (rising smoke:
+ *  `y: curve(60).from(0).to(1)`). See `VelocityOverLife` (3D). */
+export type VelocityOverLife2D = { radial?: ParticleValue, x?: ParticleValue, y?: ParticleValue }
+
+export type Particles2DOptions = {
+  /** The particle image — one picture or a flipbook sheet (`sheet`). Omit = solid squares of `color`. */
+  texture?: Texture2D
+  /** The texture's flipbook grid: `N` = N×N, `[cols, rows]`; frames run left-to-right, top-to-bottom.
+   *  Default 1. With more than one frame and no `frame`, each particle plays the sheet once over its
+   *  life, from `startFrame`. */
+  sheet?: number | [cols: number, rows: number]
+  /** Blend (+ sampling) — `Material2D.additive()` for fire, sparks, glow. Default alpha. */
+  material?: Material2D
+  /** Pool capacity (default 1000). */
+  maxParticles?: number
+  /** `'quads'` (default) a rotated square each; `'points'` the same look from a cheaper stream;
+   *  `'trail'` one ribbon strip through the particles in spawn order — `size` is its width (pair it
+   *  with `space: 'world'` and `rateOverDistance` for a trail behind a moving node). */
+  mode?: ParticleMode2D
+  /** Particles emitted per second. */
+  rate?: number
+  /** Particles emitted per world unit the emitter MOVES, on top of `rate` (trails; meant for
+   *  `space: 'world'`). */
+  rateOverDistance?: number
+  /** Lay a frame's distance spawns along a curve through the emitter's path, not the straight chord. */
+  smooth?: boolean
+  /** `'local'` (default) — particles ride the node; `'world'` — each stays where it was born as the
+   *  emitter moves on. Switching at runtime resets live particles. */
+  space?: "local" | "world"
+  /** Fraction of the emitter's own velocity given to each particle at spawn (`space: 'world'`). */
+  inheritVelocity?: number
+  shape?: ParticleShape2D
+  /** A vector (its length is the speed) or a direction + speed. World units / s. */
+  startVelocity?: Vec2Like | VelocityValue2D
+  velocityOverLife?: VelocityOverLife2D
+  /** Downward acceleration, world units/s² — positive pulls toward -y (sugar for
+   *  `acceleration: [0, -g]`); negative makes smoke rise. */
+  gravity?: number
+  /** Constant acceleration (gravity, wind). Wins over `gravity` when both are set. */
+  acceleration?: Vec2Like
+  drag?: number
+  /** Seconds each particle lives. */
+  lifetime?: Range<number>
+  color?: ParticleColor
+  /** Diameter in WORLD units (custom[0]). Default 1 — a 2D world is usually pixel-scaled, so set it. */
+  size?: ParticleValue
+  /** The particle's spin, radians (custom[1]) — a curve with mode `add` turns it over its life. */
+  rotation?: ParticleValue
+  /** 0..1 (custom[2]). Default 1. */
+  opacity?: ParticleValue
+  /** Flipbook frame index (custom[3]). */
+  frame?: ParticleValue
+  /** Where the default flipbook cycle begins: `'random'` (default) or a frame index. */
+  startFrame?: number | "random"
+  /** A floor at `height` on the y axis the particles bounce on and rest on; `null` disables it. */
+  ground?: ParticleGround | null
+  /** Turbulence; `null` turns it off. */
+  noise?: ParticleNoise | null
+  /** Fixed random seed for deterministic tests. */
+  seed?: number
+  position?: Vec2Like
+  /** Draw order within a renderPriority — see {@link Node2D.z}. */
+  z?: number
+  /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+  renderPriority?: number
+}
+
+const MODES: Record<ParticleMode2D, number> = { quads: MODE_QUADS, points: MODE_POINTS, trail: MODE_RIBBON }
+
+const v3 = (v: Vec2Like): Vec3Like => [ cx(v), cy(v), 0 ]
+
+const sheetColsRows = (sheet: number | [number, number] | undefined): [number, number] => {
+  const [ c, r ] = typeof sheet === "number" ? [ sheet, sheet ] : sheet ?? [ 1, 1 ]
+  return [ Math.max(1, Math.floor(c) || 1), Math.max(1, Math.floor(r) || 1) ]
+}
+
+// The 2D shapes as the sim's (z = 0): circle = the sim's sphere, which the planar sim samples as a disc.
+const shape3 = (s: ParticleShape2D): ParticleShape => {
+  if (s.type === "point") return { type: "point", v: s.v ? v3(s.v) : [ 0, 0, 0 ] }
+  if (s.type === "box") return { type: "box", min: v3(s.min), max: v3(s.max) }
+  const center = s.center ? v3(s.center) : [ 0, 0, 0 ]
+  if (s.type === "circle") return { type: "sphere", center, radius: s.radius, thickness: s.thickness }
+  return { type: "cone", center, radius: s.radius, angle: s.angle, length: s.length, thickness: s.thickness }
+}
+
+// The 2D velocity as the sim's: z = 0; `spread` jitters only the in-plane angle (the sim's u axis is
+// in the plane for an in-plane direction, v points out of it).
+const velocity3 = (val: Vec2Like | VelocityValue2D): Vec3Like | VelocityValue => {
+  if (Array.isArray(val) || val instanceof Float32Array || val instanceof Vec2) return v3(val as Vec2Like)
+  const v = val as VelocityValue2D & { dir?: Vec2Like, from?: Vec2Like, to?: Vec2Like }
+  const out: VelocityValue & Record<string, unknown> = { speed: v.speed }
+  if (v.dir !== undefined) out.dir = v3(v.dir)
+  else if (v.from !== undefined) out.from = v3(v.from)
+  else if (v.to !== undefined) out.to = v3(v.to)
+  if (v.spread !== undefined) out.randomizeAngle = { min: [ -v.spread, 0, 0 ], max: [ v.spread, 0, 0 ] }
+  return out
+}
+
+export class Particles2D extends Node2D {
+  private _texture?: Texture2D
+  private _sheet: [number, number]
+  private _material?: Material2D
+  private _mode: ParticleMode2D
+  private _startFrame: number | "random"
+  private _frameSet: boolean
+  readonly maxParticles: number
+
+  /** Curve-param slots 0..3, live: size / rotation / opacity / frame alias 0..3. The particle
+   *  rotation is `custom[1] = …` (the node's own `rotation` is the emitter's). */
+  readonly custom: ParticleValue[]
+
+  constructor(options: Particles2DOptions = {}) {
+    super()
+    this._texture = options.texture
+    this._sheet = sheetColsRows(options.sheet)
+    this._mode = options.mode ?? "quads"
+    this._startFrame = options.startFrame ?? "random"
+    this._frameSet = options.frame !== undefined
+    this.maxParticles = options.maxParticles ?? 0
+    // setParticles first: it is what makes the entity a particle system natively (quads by default).
+    this._sendParticles()
+
+    const id = this.id
+    const self = this
+    this.custom = new Proxy([] as ParticleValue[], {
+      set(target, prop: string, value: ParticleValue) {
+        const i = parseInt(prop)
+        if (Number.isNaN(i)) { (target as any)[prop] = value; return true }
+        target[i] = value
+        if (i === SLOT_FRAME) self._frameSet = true
+        const out: number[] = []
+        pushParam(out, i, value)
+        _creator2d.particlesConfig(id, Float32Array.from(out))
+        return true
+      },
+    })
+
+    // every option in ONE config buffer
+    const out: number[] = []
+    if (this._mode !== "quads") out.push(TAG_RENDER_MODE, 1, MODES[this._mode])
+    if (options.ground !== undefined) pushGround(out, options.ground)
+    if (options.space !== undefined) out.push(TAG_SPACE, 1, options.space === "world" ? 1 : 0)
+    if (options.inheritVelocity !== undefined) out.push(TAG_INHERIT_VELOCITY, 1, options.inheritVelocity)
+    if (options.rateOverDistance !== undefined) out.push(TAG_RATE_DISTANCE, 1, options.rateOverDistance)
+    if (options.smooth !== undefined) out.push(TAG_SMOOTH_PATH, 1, options.smooth ? 1 : 0)
+    if (options.rate !== undefined) out.push(TAG_RATE, 1, options.rate)
+    if (options.shape !== undefined) pushShape(out, shape3(options.shape))
+    if (options.velocityOverLife !== undefined) pushVelocityLife(out, options.velocityOverLife)
+    if (options.startVelocity !== undefined) pushVelocity(out, velocity3(options.startVelocity))
+    if (options.acceleration !== undefined) {
+      out.push(TAG_ACCELERATION, 3, cx(options.acceleration), cy(options.acceleration), 0)
+    } else if (options.gravity !== undefined) {
+      out.push(TAG_ACCELERATION, 3, 0, -options.gravity, 0)
+    }
+    if (options.drag !== undefined) out.push(TAG_DRAG, 1, options.drag)
+    if (options.lifetime !== undefined) pushLifetime(out, options.lifetime)
+    if (options.color !== undefined) pushColor(out, options.color)
+    if (options.size !== undefined) pushParam(out, SLOT_SIZE, options.size)
+    if (options.rotation !== undefined) pushParam(out, SLOT_ROTATION, options.rotation)
+    if (options.opacity !== undefined) pushParam(out, SLOT_OPACITY, options.opacity)
+    if (options.frame !== undefined) pushParam(out, SLOT_FRAME, options.frame)
+    else pushDefaultFrames(out, this._sheet[0], this._sheet[1], this._startFrame)
+    if (options.noise !== undefined) pushNoise(out, options.noise)
+    if (options.seed !== undefined) out.push(TAG_SEED, 1, options.seed)
+    if (out.length > 0) this._send(out)
+
+    if (options.material) this.material = options.material
+    if (options.position) this.position = options.position
+    if (options.z !== undefined) this.z = options.z
+    if (options.renderPriority !== undefined) this.renderPriority = options.renderPriority
+  }
+
+  private _sendParticles(): void {
+    _creator2d.setParticles(this.id, this._texture?.id ?? 0, this._sheet[0], this._sheet[1], this.maxParticles)
+  }
+
+  private _send(out: number[]): void {
+    _creator2d.particlesConfig(this.id, Float32Array.from(out))
+  }
+
+  /** Emit `count` particles now, where the emitter is (a burst). */
+  spawn(count: number): this { _creator2d.particlesSpawn(this.id, count); return this }
+
+  /** Live particles right now. */
+  get alive(): number { return _creator2d.particlesAlive(this.id) }
+
+  /** The particle image; undefined = solid squares of the colour. */
+  get texture(): Texture2D | undefined { return this._texture }
+  set texture(t: Texture2D | undefined) { this._texture = t; this._sendParticles() }
+
+  /** The texture's flipbook grid [cols, rows]. Without an explicit `frame` the default cycle follows. */
+  get sheet(): [number, number] { return [ this._sheet[0], this._sheet[1] ] }
+  set sheet(s: number | [number, number]) {
+    this._sheet = sheetColsRows(s)
+    this._sendParticles()
+    if (this._frameSet) return
+    const out: number[] = []
+    if (this._sheet[0] * this._sheet[1] > 1) pushDefaultFrames(out, this._sheet[0], this._sheet[1], this._startFrame)
+    else pushParam(out, SLOT_FRAME, 0)
+    this._send(out)
+  }
+
+  /** Blend ({@link Material2D}). Undefined = the default (alpha). */
+  get material(): Material2D | undefined { return this._material }
+  set material(m: Material2D) { this._material = m; m._apply(this.id) }
+
+  /** How particles are drawn — see `Particles2DOptions.mode`. */
+  get mode(): ParticleMode2D { return this._mode }
+  set mode(m: ParticleMode2D) { this._mode = m; this._send([ TAG_RENDER_MODE, 1, MODES[m] ]) }
+
+  set rate(val: number) { this._send([ TAG_RATE, 1, val ]) }
+  /** `'world'` leaves particles behind where they were born (trails). Switching resets live ones. */
+  set space(val: "local" | "world") { this._send([ TAG_SPACE, 1, val === "world" ? 1 : 0 ]) }
+  set inheritVelocity(val: number) { this._send([ TAG_INHERIT_VELOCITY, 1, val ]) }
+  set rateOverDistance(val: number) { this._send([ TAG_RATE_DISTANCE, 1, val ]) }
+  set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
+
+  set shape(shape: ParticleShape2D) {
+    const out: number[] = []
+    pushShape(out, shape3(shape))
+    this._send(out)
+  }
+
+  set startVelocity(val: Vec2Like | VelocityValue2D) {
+    const out: number[] = []
+    pushVelocity(out, velocity3(val))
+    this._send(out)
+  }
+
+  set velocityOverLife(v: VelocityOverLife2D) {
+    const out: number[] = []
+    pushVelocityLife(out, v)
+    this._send(out)
+  }
+
+  /** Positive pulls toward -y — sugar for `acceleration = [0, -g]`. */
+  set gravity(val: number) { this._send([ TAG_ACCELERATION, 3, 0, -val, 0 ]) }
+  set acceleration(a: Vec2Like) { this._send([ TAG_ACCELERATION, 3, cx(a), cy(a), 0 ]) }
+  set drag(val: number) { this._send([ TAG_DRAG, 1, val ]) }
+  set seed(val: number) { this._send([ TAG_SEED, 1, val ]) }
+
+  set lifetime(val: Range<number>) {
+    const out: number[] = []
+    pushLifetime(out, val)
+    this._send(out)
+  }
+
+  set size(val: ParticleValue) { this.custom[SLOT_SIZE] = val }
+  set opacity(val: ParticleValue) { this.custom[SLOT_OPACITY] = val }
+  set frame(val: ParticleValue) { this.custom[SLOT_FRAME] = val }
+
+  set color(value: ParticleColor) {
+    const out: number[] = []
+    pushColor(out, value)
+    this._send(out)
+  }
+
+  set ground(g: ParticleGround | null) {
+    const out: number[] = []
+    pushGround(out, g)
+    this._send(out)
+  }
+
+  set noise(n: ParticleNoise | null) {
+    const out: number[] = []
+    pushNoise(out, n)
+    this._send(out)
+  }
+}

package/src/g2/Path2D.ts

@@ -0,0 +1,215 @@
+// A vector 2D node: lines and polygons drawn in the sprite batch (through the engine's white texture,
+// so they batch with sprites and sort by renderPriority / z like any node). What it is for: debug draw,
+// trails and outlines, map roads and areas, UI-ish shapes inside a 2D scene.
+//
+//   Path2D.line([[0, 0], [120, 40], [200, 0]], { width: 2, units: 'px', color: '#fc4' })   // a map road
+//   Path2D.polygon(area, { fill: '#3a74', stroke: { width: 1, units: 'px' } })              // a map area
+//   Path2D.circle(20, { fill: '#e33', position: [100, 50] })
+//
+// The points are in the node's LOCAL frame. Stroke `units: 'px'` is a width in logical screen pixels
+// that stays constant while the camera zooms — what a map wants; the default 'world' scales with the
+// zoom like the rest of the scene. Fills always close the ring; `closed` is about the stroke.
+//
+// The geometry is tessellated natively once per `points` / `closed` / `holes` write (the width and the
+// anti-alias fringe are applied per frame, so zooming costs no rebuild). So when a shape MOVES, animate
+// the node's transform (position / rotation / scale), not its points.
+//
+// A path has no pointer picking and no collider of its own: put a Shape2D (+ Physics2D / Trigger2D) on
+// the same node for that.
+
+import { Color, type ColorInput } from "../core/color"
+import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import { Node2D } from "./Node2D"
+import type { Material2D } from "./Material2D"
+
+export type StrokeJoin2D = "miter" | "round" | "bevel"
+export type StrokeCap2D = "butt" | "round" | "square"
+
+export type Stroke2D = {
+  /** Line width. In `units: 'world'` (default) world units; in `'px'` logical screen pixels — constant
+   *  on screen while the camera zooms (map roads, debug lines). */
+  width: number
+  /** Default white. */
+  color?: ColorInput
+  units?: "world" | "px"
+  /** How segments meet; default 'miter'. */
+  join?: StrokeJoin2D
+  /** How an OPEN path's ends look; default 'butt'. */
+  cap?: StrokeCap2D
+  /** A band around the line, `width` in the stroke's units; default colour black. Drawn UNDER every
+   *  node's body at the same z, so two outlined roads merge at their junction (give a class of roads
+   *  one z; a different z isolates). */
+  outline?: { width: number, color?: ColorInput }
+}
+
+export type Path2DOptions = {
+  /** The outer ring, in the node's local frame. */
+  points: readonly Vec2Like[]
+  /** Close the ring (a polygon). Fills always close; this is about the stroke. Default false for
+   *  line() and a plain constructor, true for polygon() / rect() / circle(). */
+  closed?: boolean
+  /** A number = `{ width }`. Omit = no stroke. */
+  stroke?: Stroke2D | number
+  /** Omit = no fill. */
+  fill?: ColorInput
+  /** Hole rings — fills only. */
+  holes?: readonly (readonly Vec2Like[])[]
+  /** Edge anti-aliasing (default true). Off for crisp pixel-art lines. */
+  antialias?: boolean
+  position?: Vec2Like
+  /** Degrees, CCW. */
+  rotation?: number
+  scale?: Vec2Like | number
+  /** Draw order within a renderPriority — see {@link Node2D.z}. */
+  z?: number
+  /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+  renderPriority?: number
+  /** Only `blend` matters for a path (no texture); see Material2D. */
+  material?: Material2D
+}
+
+type ShapeOptions = Omit<Path2DOptions, "points" | "closed">
+
+const JOINS: Record<StrokeJoin2D, number> = { miter: 0, round: 1, bevel: 2 }
+const CAPS: Record<StrokeCap2D, number> = { butt: 0, round: 1, square: 2 }
+
+// x,y pairs — the engine's point format.
+const toFloats = (points: readonly Vec2Like[]): Float32Array => {
+  const out = new Float32Array(points.length * 2)
+  for (let i = 0; i < points.length; i++) { out[i * 2] = cx(points[i]!); out[i * 2 + 1] = cy(points[i]!) }
+  return out
+}
+
+export class Path2D extends Node2D {
+  private _pts: Float32Array = new Float32Array(0)
+  private _closed = false
+  private _stroke: Stroke2D | null = null
+  private _outlined = false
+  private _fill: ColorInput | null = null
+  private _holes: Float32Array[] = []
+  private _antialias = true
+  private _material?: Material2D
+
+  constructor(options: Path2DOptions) {
+    super()
+    // setPath first: it is what makes the entity a path natively; stroke / fill / holes come after.
+    this._closed = options.closed ?? false
+    this.points = options.points
+    if (options.holes) this.holes = options.holes
+    if (options.stroke !== undefined) this.stroke = options.stroke
+    if (options.fill !== undefined) this.fill = options.fill
+    if (options.antialias !== undefined) this.antialias = options.antialias
+    if (options.material) this.material = options.material
+    if (options.position) this.position = options.position
+    if (options.rotation !== undefined) this.rotation = options.rotation
+    if (options.scale !== undefined) this.scale = options.scale
+    if (options.z !== undefined) this.z = options.z
+    if (options.renderPriority !== undefined) this.renderPriority = options.renderPriority
+  }
+
+  /** An open polyline. */
+  static line(
+    points: readonly Vec2Like[], stroke: Stroke2D | number,
+    options: Omit<Path2DOptions, "points" | "stroke" | "fill" | "closed"> = {},
+  ): Path2D {
+    return new Path2D({ ...options, points, stroke, closed: false })
+  }
+
+  /** A closed polygon; give it a `fill` and / or a `stroke`. */
+  static polygon(points: readonly Vec2Like[], options: ShapeOptions = {}): Path2D {
+    return new Path2D({ ...options, points, closed: true })
+  }
+
+  /** A rectangle of `size` centred on the node's origin. */
+  static rect(size: Vec2Like, options: ShapeOptions = {}): Path2D {
+    const hw = cx(size) / 2, hh = cy(size) / 2
+    return Path2D.polygon([ [ -hw, -hh ], [ hw, -hh ], [ hw, hh ], [ -hw, hh ] ], options)
+  }
+
+  /** A circle centred on the node's origin. `segments` defaults to clamp(round(radius / 2), 12, 96) —
+   *  generous, because a fill is not re-tessellated when the camera zooms in. */
+  static circle(radius: number, options: ShapeOptions & { segments?: number } = {}): Path2D {
+    const { segments, ...rest } = options
+    const n = Math.max(3, Math.round(segments ?? Math.min(96, Math.max(12, Math.round(radius * 0.5)))))
+    const points: Vec2Like[] = []
+    for (let i = 0; i < n; i++) {
+      const a = (i / n) * Math.PI * 2
+      points.push([ Math.cos(a) * radius, Math.sin(a) * radius ])
+    }
+    return Path2D.polygon(points, rest)
+  }
+
+  /** The outer ring (local frame). A write re-tessellates natively — move the node instead when you can. */
+  get points(): Vec2[] {
+    const out: Vec2[] = []
+    for (let i = 0; i < this._pts.length; i += 2) out.push(new Vec2(this._pts[i]!, this._pts[i + 1]!))
+    return out
+  }
+  set points(points: readonly Vec2Like[]) {
+    this._pts = toFloats(points)
+    _creator2d.setPath(this.id, this._pts, this._pts.length / 2, this._closed)
+  }
+
+  /** Whether the stroke closes the ring (fills always close). */
+  get closed(): boolean { return this._closed }
+  set closed(v: boolean) {
+    this._closed = v
+    _creator2d.setPath(this.id, this._pts, this._pts.length / 2, v)
+  }
+
+  /** The stroke, or null = none. A number = `{ width }`. */
+  get stroke(): Stroke2D | null { return this._stroke ? { ...this._stroke } : null }
+  set stroke(s: Stroke2D | number | null) {
+    const st = s === null ? null : typeof s === "number" ? { width: s } : { ...s }
+    this._stroke = st
+    if (!st) {
+      _creator2d.setPathStroke(this.id, 0, false, 0, 0, 0, 0, 0, 0)
+      if (this._outlined) { this._outlined = false; _creator2d.setPathOutline(this.id, 0, 0, 0, 0, 0) }
+      return
+    }
+    const [ r, g, b, a ] = st.color !== undefined ? Color.toRgba01(st.color) : [ 1, 1, 1, 1 ]
+    _creator2d.setPathStroke(
+      this.id, st.width, st.units === "px", JOINS[st.join ?? "miter"], CAPS[st.cap ?? "butt"], r, g, b, a,
+    )
+    // the outline is sent when there is one, and once more to clear a previous one
+    if (st.outline && st.outline.width > 0) {
+      this._outlined = true
+      const [ orr, og, ob, oa ] = st.outline.color !== undefined ? Color.toRgba01(st.outline.color) : [ 0, 0, 0, 1 ]
+      _creator2d.setPathOutline(this.id, st.outline.width, orr, og, ob, oa)
+    } else if (this._outlined) {
+      this._outlined = false
+      _creator2d.setPathOutline(this.id, 0, 0, 0, 0, 0)
+    }
+  }
+
+  /** The fill colour, or null = no fill. */
+  get fill(): ColorInput | null { return this._fill }
+  set fill(c: ColorInput | null) {
+    this._fill = c
+    if (c === null) { _creator2d.setPathFill(this.id, false, 0, 0, 0, 0); return }
+    const [ r, g, b, a ] = Color.toRgba01(c)
+    _creator2d.setPathFill(this.id, true, r, g, b, a)
+  }
+
+  /** Hole rings (fills only). A write replaces them all. */
+  get holes(): Vec2[][] {
+    return this._holes.map((h) => {
+      const ring: Vec2[] = []
+      for (let i = 0; i < h.length; i += 2) ring.push(new Vec2(h[i]!, h[i + 1]!))
+      return ring
+    })
+  }
+  set holes(rings: readonly (readonly Vec2Like[])[]) {
+    this._holes = rings.map(toFloats)
+    _creator2d.pathClearHoles(this.id)
+    for (const h of this._holes) _creator2d.pathAddHole(this.id, h, h.length / 2)
+  }
+
+  /** Edge anti-aliasing (default true); off for crisp pixel-art lines. */
+  get antialias(): boolean { return this._antialias }
+  set antialias(v: boolean) { this._antialias = v; _creator2d.setPathAntialias(this.id, v) }
+
+  /** Blend ({@link Material2D}) — only `blend` matters for a path. Undefined = the default (alpha). */
+  get material(): Material2D | undefined { return this._material }
+  set material(m: Material2D) { this._material = m; m._apply(this.id) }
+}

package/src/g2/Physics2D.ts

@@ -269,7 +269,7 @@ export class Physics2D extends Aspect<"physics", Node2D> {
   }
 
   /** Topmost body (solid or sensor) whose shape contains the world point, or null. "Topmost" means
-   *  by DRAW order - layer, then z - so picking agrees with what the player sees. */
+   *  by DRAW order - renderPriority, then z - so picking agrees with what the player sees. */
   static overlapPoint(p: Vec2Like, q?: Query2D): Node2D | null {
     return node2dById(_creator2d.physicsOverlapPoint(cx(p), cy(p), maskOf(q), ignoreOf(q), ignoreCount(q)))
   }

package/src/g2/Scene2D.ts

@@ -34,24 +34,15 @@ const installRenderSyncedFrames = (): void => {
 export type Scene2DOptions = {
   /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
   background?: ColorInput
-  /** Texture sampling for the 2D renderer: `'nearest'` (default — crisp pixel art) or `'linear'`
-   *  (smooth — for hi-res / non-pixel-art assets). Applied when the scene is opened, so switching
-   *  scenes restores the active scene's choice. NOTE: this is a GLOBAL renderer setting (one sampler
-   *  for ALL textures, not per-texture), so the currently-open scene's filter wins. Omit to leave the
-   *  current setting (engine default is nearest). */
+  /** The renderer's DEFAULT texture sampling: `'nearest'` (crisp pixel art — the engine default) or
+   *  `'linear'` (smooth — hi-res / non-pixel-art assets). A node's `Material2D` `filter` overrides it
+   *  per sprite / tilemap; this is what a material without one samples with. A GLOBAL renderer
+   *  setting, so it is reasserted when the scene is opened (switching scenes restores the active
+   *  scene's choice). Omit to leave the current setting. */
   filter?: 'nearest' | 'linear'
-}
-
-/** Returned by scene2d.layer(n); chain .ySort() to enable top-down depth sorting for that layer. */
-class LayerHandle {
-  private readonly sceneId: number
-  private readonly layer: number
-  constructor(sceneId: number, layer: number) { this.sceneId = sceneId; this.layer = layer }
-  /** In this layer, lower-on-screen sprites overlap higher ones (top-down feet sorting). */
-  ySort(enabled = true): this {
-    _creator2d.setLayerYSort(this.sceneId, this.layer, enabled)
-    return this
-  }
+  /** Top-down depth: among nodes of one renderPriority and one z, the one lower on screen (smaller
+   *  world Y) draws on top. See {@link Scene2D.ySort}. */
+  ySort?: boolean
 }
 
 export class Scene2D implements Presentable {
@@ -72,8 +63,9 @@ export class Scene2D implements Presentable {
   readonly _clickListeners: Array<(ev: ClickEvent<Node2D | null>) => void> = []
   readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node2D | null>) => void> = []
 
-  /** Texture filter to (re)assert on open(); the sampler is global, so each scene reclaims it. */
+  /** Default texture filter to (re)assert on open(); the setting is global, so each scene reclaims it. */
   private readonly _filter?: 'nearest' | 'linear'
+  private _ySort = false
 
   constructor(options: Scene2DOptions = {}) {
     if (!Scene2D.supported) throw new Error("Scene2D: this host has no 2D engine (Web Lite runs UI and 3D apps; a 3d / core engine variant has no 2D) — check Scene2D.supported before creating one")
@@ -82,6 +74,7 @@ export class Scene2D implements Presentable {
     this.camera = new Camera2D(this.id)
     this._filter = options.filter
     if (options.background !== undefined) this.background = options.background
+    if (options.ySort !== undefined) this.ySort = options.ySort
   }
 
   set background(color: ColorInput) {
@@ -89,10 +82,11 @@ export class Scene2D implements Presentable {
     _creator2d.sceneSetClearColor(this.id, r, g, b, a)
   }
 
-  /** Address a draw layer to configure it, e.g. scene2d.layer(1).ySort(). */
-  layer(n: number): LayerHandle {
-    return new LayerHandle(this.id, n)
-  }
+  /** Top-down depth sorting, one flag for the scene: among nodes of one `renderPriority` and one `z`,
+   *  the one lower on screen (smaller world Y) draws on top — give characters and props a feet anchor
+   *  (`[0.5, 1]`). Draw order is renderPriority, then z, then this. Default off. */
+  get ySort(): boolean { return this._ySort }
+  set ySort(v: boolean) { this._ySort = v; _creator2d.setYSort(this.id, v) }
 
   /** Topmost visible sprite whose world bounds contain the world point, or null. Body-free
    *  hit-test for tap/click picking — pair with camera.screenToWorld(). */