lecodes-sdk 2.4.9 → 2.5.0

package/src/core/particlesConfig.ts

@@ -0,0 +1,422 @@
+// The particle config vocabulary — the ONE language of the 3D `Particles` / `Trail` nodes
+// (gl/Particles.ts) and the 2D `Particles2D` node (g2/Particles2D.ts). Every engine runs the same
+// simulation (creator-particles), so every node speaks it the same way: this module holds the record
+// tags, the curve builders, the engine-neutral option types and the record writers; the nodes add only
+// what is theirs (a 3D material / mesh / light, a 2D sheet texture and Material2D blend).
+//
+// The format: all emitter/curve config crosses the bridge as ONE Float32Array of
+// [tag, payloadLen, ...payload] records — `_creator.setParticleSystemConfig` in 3D,
+// `_creator2d.particlesConfig` in 2D. A constructor batches every option into a single call, a live
+// setter sends a one-record buffer; unknown tags are skipped by length natively. The tag values mirror
+// CPART_TAG_* in engines/particles/include/creator-particles/creator-particles.h (guarded by
+// tests/gl/particles-tags.test.ts).
+//
+// Curves over a particle's lifetime are built with curve()/colorCurve() chains — see the builders
+// below. A builder's whole state is the flat `_data` array (the exact record payload), so the
+// chisel compiler can constant-fold literal chains into the buffer at compile time.
+
+import { Color, type ColorInput } from "./color"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+
+export type Range<T> = T | { min: T, max: T }
+
+// --- config record tags (keep in sync with CPART_TAG_* in creator-particles.h) ------------------
+
+export const TAG_SHAPE = 1
+export const TAG_LIFETIME = 2
+export const TAG_RATE = 3
+export const TAG_VELOCITY = 4
+export const TAG_VELOCITY_RND = 5
+export const TAG_ACCELERATION = 6
+export const TAG_DRAG = 7
+export const TAG_NOISE = 8
+export const TAG_SEED = 9
+export const TAG_PARAM_CURVE = 10
+export const TAG_COLOR_CURVE = 11
+export const TAG_SPACE = 12
+export const TAG_INHERIT_VELOCITY = 13
+export const TAG_RATE_DISTANCE = 14
+export const TAG_RENDER_MODE = 15
+export const TAG_MESH_GEOMETRY = 16
+export const TAG_ANGULAR_VELOCITY = 17
+export const TAG_GROUND = 18
+export const TAG_VELOCITY_LIFE = 19
+export const TAG_ORDER = 20
+export const TAG_SMOOTH_PATH = 21
+export const TAG_RIBBON_ORIENT = 22
+export const TAG_LIT = 23
+/** 0 / 1 — an XY-plane system; the 2D engine sets it itself at creation (CPART_TAG_PLANAR), the SDK never writes it. */
+export const TAG_PLANAR = 24
+
+/** RENDER_MODE payloads (CPART_MODE_* in creator-particles.h). */
+export const MODE_POINTS = 0
+export const MODE_QUADS = 1
+export const MODE_RIBBON = 2
+export const MODE_MESH = 3
+
+/** The PARAM_CURVE slots the named params alias (custom[0..3]). */
+export const SLOT_SIZE = 0
+export const SLOT_ROTATION = 1
+export const SLOT_OPACITY = 2
+export const SLOT_FRAME = 3
+
+/** @internal — exported for the tag-sync test only. */
+export const _particleTags = {
+  SHAPE: TAG_SHAPE, LIFETIME: TAG_LIFETIME, RATE: TAG_RATE, VELOCITY: TAG_VELOCITY,
+  VELOCITY_RND: TAG_VELOCITY_RND, ACCELERATION: TAG_ACCELERATION, DRAG: TAG_DRAG,
+  NOISE: TAG_NOISE, SEED: TAG_SEED, PARAM_CURVE: TAG_PARAM_CURVE, COLOR_CURVE: TAG_COLOR_CURVE,
+  SPACE: TAG_SPACE, INHERIT_VELOCITY: TAG_INHERIT_VELOCITY, RATE_DISTANCE: TAG_RATE_DISTANCE,
+  RENDER_MODE: TAG_RENDER_MODE, MESH_GEOMETRY: TAG_MESH_GEOMETRY,
+  ANGULAR_VELOCITY: TAG_ANGULAR_VELOCITY, GROUND: TAG_GROUND, VELOCITY_LIFE: TAG_VELOCITY_LIFE,
+  ORDER: TAG_ORDER, SMOOTH_PATH: TAG_SMOOTH_PATH, RIBBON_ORIENT: TAG_RIBBON_ORIENT,
+  LIT: TAG_LIT,
+  PLANAR: TAG_PLANAR,
+}
+
+// --- curve builders -----------------------------------------------------------------------------
+
+// A value curve reads as a journey over the particle's life:
+//   curve(0.3).from(0).via(0.15, 1).via(0.6, 1).to(0)   // fade in, hold, fade out — or:
+//   curve(0.3).fade(0.15, 0.4)
+// The curve multiplies the base value (or adds to it with mode 'add'); the base and any stop can be
+// a { min, max } range, randomized per particle. With no `.from` the curve starts at the identity
+// (1 for multiply, 0 for add); with no `.to` it holds its last value to end of life.
+//
+// chisel constant-folds a literal chain into its `_data` buffer at compile time and validates it
+// (bad stop order, >8 stops, unparsable color → a build diagnostic): chisel-core/src/curve.rs mirrors
+// these method bodies op-for-op, against a verbatim copy of them in chisel's fixtures/curve-sdk/. Keep
+// the two in step — a change here means a change there (chisel's scripts/curve-exact.mjs compares the
+// fused payload against the real builder, buffer for buffer).
+
+/** @internal A range as its [lo, hi] pair. */
+export const lohi = (v: Range<number>): [number, number] =>
+  typeof v === "number" ? [ v, v ] : [ v.min, v.max ]
+
+export class CurveBuilder {
+  private _kind: 0 | 1
+  private _lo: number
+  private _hi: number
+  private _stops: number[] = []   // flat (t, lo, hi)
+
+  constructor(base: Range<number>, mode: "multiply" | "add") {
+    this._kind = mode === "add" ? 1 : 0
+    ;[ this._lo, this._hi ] = lohi(base)
+  }
+
+  /** Curve value at birth (t = 0). Must come before any other stop. */
+  from(v: Range<number>): this {
+    if (this._stops.length > 0) throw new Error("curve: .from() must come first")
+    return this.via(0, v)
+  }
+
+  /** Curve value at `t` (0..1 of the particle's life). Stops must be added in ascending t order. */
+  via(t: number, v: Range<number>): this {
+    const [ lo, hi ] = lohi(v)
+    this._stops.push(t, lo, hi)
+    return this
+  }
+
+  /** Curve value at death (t = 1). */
+  to(v: Range<number>): this {
+    return this.via(1, v)
+  }
+
+  /** The classic opacity envelope: rise over the first `fadeIn`, fall over the last `fadeOut`. */
+  fade(fadeIn = 0.15, fadeOut = fadeIn): this {
+    const up = Math.min(Math.max(fadeIn, 0), 1)
+    const down = Math.min(Math.max(fadeOut, 0), 1 - up)
+    if (up > 0) this.via(0, 0).via(up, 1)
+    else this.via(0, 1)
+    if (down > 0) {
+      if (1 - down > up) this.via(1 - down, 1)
+      this.via(1, 0)
+    }
+    return this
+  }
+
+  /** The PARAM_CURVE record payload (sans slot): [kind, baseLo, baseHi, n, (t, lo, hi)×n]. */
+  get _data(): Float32Array {
+    const stops = this._stops
+    const prepend = stops.length > 0 && stops[0] > 0
+    const n = stops.length / 3 + (prepend ? 1 : 0)
+    const out = new Float32Array(4 + n * 3)
+    out[0] = this._kind
+    out[1] = this._lo
+    out[2] = this._hi
+    out[3] = n
+    let o = 4
+    if (prepend) {
+      const identity = this._kind === 1 ? 0 : 1
+      out[o + 1] = identity
+      out[o + 2] = identity
+      o += 3
+    }
+    out.set(stops, o)
+    return out
+  }
+}
+
+export class ColorCurveBuilder {
+  private _lo: [number, number, number, number]
+  private _hi: [number, number, number, number]
+  private _stops: number[] = []   // flat (t, lo rgba, hi rgba)
+
+  constructor(base: Range<ColorInput>) {
+    if (isColorRange(base)) {
+      this._lo = Color.toRgba01(base.min)
+      this._hi = Color.toRgba01(base.max)
+    } else {
+      this._lo = Color.toRgba01(base)
+      this._hi = this._lo
+    }
+  }
+
+  /** Curve color at birth (t = 0). Must come first. The curve multiplies the base color. */
+  from(c: Range<ColorInput>): this {
+    if (this._stops.length > 0) throw new Error("colorCurve: .from() must come first")
+    return this.via(0, c)
+  }
+
+  /** Curve color at `t` (0..1 of the particle's life), in ascending t order. */
+  via(t: number, c: Range<ColorInput>): this {
+    let lo: number[], hi: number[]
+    if (isColorRange(c)) {
+      lo = Color.toRgba01(c.min)
+      hi = Color.toRgba01(c.max)
+    } else {
+      lo = hi = Color.toRgba01(c)
+    }
+    this._stops.push(t, ...lo, ...hi)
+    return this
+  }
+
+  /** Curve color at death (t = 1). */
+  to(c: Range<ColorInput>): this {
+    return this.via(1, c)
+  }
+
+  /** The COLOR_CURVE record payload: [baseLo rgba, baseHi rgba, n, (t, lo rgba, hi rgba)×n]. */
+  get _data(): Float32Array {
+    const stops = this._stops
+    const prepend = stops.length > 0 && stops[0] > 0
+    const n = stops.length / 9 + (prepend ? 1 : 0)
+    const out = new Float32Array(9 + n * 9)
+    out.set(this._lo, 0)
+    out.set(this._hi, 4)
+    out[8] = n
+    let o = 9
+    if (prepend) {
+      for (let i = 1; i < 9; i++) out[o + i] = 1   // identity multiplier: white, t = 0
+      o += 9
+    }
+    out.set(stops, o)
+    return out
+  }
+}
+
+/** A value curve over each particle's lifetime. Default mode `multiply` (the curve scales the
+ *  base); `add` offsets it instead. */
+export const curve = (base: Range<number> = 1, mode: "multiply" | "add" = "multiply"): CurveBuilder =>
+  new CurveBuilder(base, mode)
+
+/** A color curve over each particle's lifetime — always multiplies the base color. */
+export const colorCurve = (base: Range<ColorInput> = "#ffffff"): ColorCurveBuilder =>
+  new ColorCurveBuilder(base)
+
+// --- option types -------------------------------------------------------------------------------
+
+export type ParticleValue = Range<number> | CurveBuilder | { _data: Float32Array }
+export type ParticleColor = ColorInput | { min: ColorInput, max: ColorInput } | ColorCurveBuilder | { _data: Float32Array }
+
+/** A start velocity by direction + speed (the object form of `startVelocity`). */
+export type VelocityValue = {
+  speed?: Range<number>
+  /** Cone half-angle in radians — jitter the launch direction uniformly within it. */
+  spread?: number
+  /** Asymmetric jitter: two angles (u, v — the x/y components) in radians. */
+  randomizeAngle?: { min: Vec3Like, max: Vec3Like }
+} & ({ from: Vec3Like } | { to: Vec3Like } | { dir: Vec3Like } | {})
+
+/** Where particles are born, in emitter space. Sphere / hemisphere / cone have an axis of +Y (the
+ *  hemisphere is the +Y half, the cone opens along +Y from its base disc at `center`) — aim the
+ *  node with `lookAt(target, 'y')`. `thickness` 0 emits from the surface only, 1 (default) from the
+ *  whole volume. A sphere or cone also sets the LAUNCH DIRECTION (outward / from the cone's apex)
+ *  when `startVelocity` gives a speed but no direction, like Unity's shapes. */
+export type ParticleShape =
+  | { type: "point", v: Vec3Like }
+  | { type: "box", min: Vec3Like, max: Vec3Like }
+  | { type: "circle", center: Vec3Like, radius: number }
+  | { type: "sphere", center?: Vec3Like, radius: number, thickness?: number }
+  | { type: "hemisphere", center?: Vec3Like, radius: number, thickness?: number }
+  | { type: "cone", center?: Vec3Like, radius: number, /** half-angle, radians */ angle?: number, /** emit this far up the axis too */ length?: number, thickness?: number }
+
+/** Extra velocity over each particle's life — evaluated from the curves every frame and ADDED as a
+ *  displacement (not accumulated like `acceleration`): `radial` pushes outward along the particle's
+ *  birth direction (a burst that decays: `curve(4).to(0)`), `x`/`y`/`z` drift in the simulation
+ *  space (rising smoke: `y: curve(2).from(0).to(1)`). Unity's velocityOverLifetime. */
+export type VelocityOverLife = { radial?: ParticleValue, x?: ParticleValue, y?: ParticleValue, z?: ParticleValue }
+
+export type ParticleNoise = {
+  strength?: number, frequency?: number, speed?: number,
+  /** How much of the displacement a particle earns with AGE (default 0 = all of it from birth).
+   *  The field is sampled by position, so at 0 every particle born at the same spot is pushed the
+   *  same way and a plume's root wanders off its emitter by up to `strength` metres; at 1 a particle
+   *  is born exactly where the emitter put it and drifts into the field over its life — what you
+   *  want whenever the source is visible (an exhaust pipe, a contact patch, a muzzle). */
+  ramp?: number,
+}
+
+/** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
+ *  world y with `space: 'world'`, emitter-local y otherwise. */
+export type ParticleGround = {
+  /** Plane height (default 0). */
+  height?: number
+  /** Contact radius — particles stop `radius` above the plane (a mesh's half-extent; default 0). */
+  radius?: number
+  /** Fraction of the vertical speed kept on impact, 0..1 (default 0.3). */
+  bounce?: number
+  /** Tangential damping while in contact, per second — like `drag` (default 8). */
+  friction?: number
+}
+
+/** The mesh a mesh-mode system draws per particle — structurally a `Geometry`. */
+export type ParticleMeshData = {
+  readonly vertices: ArrayLike<number>
+  readonly normals: ArrayLike<number>
+  readonly uv: ArrayLike<number>
+  readonly indices: ArrayLike<number>
+}
+
+// --- record writers -----------------------------------------------------------------------------
+// Each appends its record(s) to `out`; the node turns the whole array into one Float32Array.
+
+const isColorRange = (v: unknown): v is { min: ColorInput, max: ColorInput } =>
+  typeof v === "object" && v !== null && !Array.isArray(v) && "min" in v
+
+const hasData = (v: unknown): v is { _data: Float32Array } =>
+  typeof v === "object" && v !== null && "_data" in v
+
+/** A PARAM_CURVE record: `slot` 0 size / 1 rotation / 2 opacity / 3 frame. */
+export const pushParam = (out: number[], slot: number, value: ParticleValue): void => {
+  if (typeof value === "number") {
+    out.push(TAG_PARAM_CURVE, 5, slot, 0, value, value, 0)
+  } else if (hasData(value)) {
+    const d = value._data
+    out.push(TAG_PARAM_CURVE, d.length + 1, slot)
+    for (let i = 0; i < d.length; i++) out.push(d[i])
+  } else {
+    out.push(TAG_PARAM_CURVE, 5, slot, 0, value.min, value.max, 0)
+  }
+}
+
+export const pushColor = (out: number[], value: ParticleColor): void => {
+  let d: Float32Array
+  if (hasData(value)) {
+    d = value._data
+  } else if (isColorRange(value)) {
+    d = new ColorCurveBuilder(value)._data
+  } else {
+    d = new ColorCurveBuilder(value as ColorInput)._data
+  }
+  out.push(TAG_COLOR_CURVE, d.length)
+  for (let i = 0; i < d.length; i++) out.push(d[i])
+}
+
+export const pushMesh = (out: number[], g: ParticleMeshData): void => {
+  const nv = g.vertices.length / 3
+  const ni = g.indices.length
+  out.push(TAG_MESH_GEOMETRY, 2 + nv * 8 + ni, nv, ni)
+  for (let i = 0; i < nv * 3; i++) out.push(g.vertices[i])
+  for (let i = 0; i < nv * 3; i++) out.push(g.normals[i])
+  for (let i = 0; i < nv * 2; i++) out.push(g.uv[i])
+  for (let i = 0; i < ni; i++) out.push(g.indices[i])
+}
+
+export const pushAngularVelocity = (out: number[], v: Vec3Like | { min: Vec3Like, max: Vec3Like }): void => {
+  const r = v as { min: Vec3Like, max: Vec3Like }
+  if (typeof r === "object" && r !== null && !Array.isArray(r) && "min" in r && !(v instanceof Float32Array) && !(v instanceof Vec3)) {
+    out.push(TAG_ANGULAR_VELOCITY, 6, cx(r.min), cy(r.min), cz(r.min), cx(r.max), cy(r.max), cz(r.max))
+  } else {
+    const a = v as Vec3Like
+    out.push(TAG_ANGULAR_VELOCITY, 6, cx(a), cy(a), cz(a), cx(a), cy(a), cz(a))
+  }
+}
+
+export const pushGround = (out: number[], g: ParticleGround | null): void => {
+  if (g === null) out.push(TAG_GROUND, 5, 0, 0, 0, 0, 0)
+  else out.push(TAG_GROUND, 5, 1, g.height ?? 0, g.radius ?? 0, g.bounce ?? 0.3, g.friction ?? 8)
+}
+
+export const pushShape = (out: number[], shape: ParticleShape): void => {
+  if (shape.type === "point") out.push(TAG_SHAPE, 4, 0, cx(shape.v), cy(shape.v), cz(shape.v))
+  else if (shape.type === "box") out.push(TAG_SHAPE, 7, 1, cx(shape.min), cy(shape.min), cz(shape.min), cx(shape.max), cy(shape.max), cz(shape.max))
+  else if (shape.type === "circle") out.push(TAG_SHAPE, 5, 2, cx(shape.center), cy(shape.center), cz(shape.center), shape.radius)
+  else {
+    const c = shape.center ?? [ 0, 0, 0 ]
+    const thickness = shape.thickness ?? 1
+    if (shape.type === "cone") out.push(TAG_SHAPE, 8, 5, cx(c), cy(c), cz(c), shape.radius, shape.angle ?? 0, shape.length ?? 0, thickness)
+    else out.push(TAG_SHAPE, 6, shape.type === "sphere" ? 3 : 4, cx(c), cy(c), cz(c), shape.radius, thickness)
+  }
+}
+
+export const pushVelocityLife = (out: number[], v: VelocityOverLife): void => {
+  const axes: Array<[number, ParticleValue | undefined]> = [ [ 0, v.radial ], [ 1, v.x ], [ 2, v.y ], [ 3, v.z ] ]
+  for (const [ axis, value ] of axes) {
+    if (value === undefined) continue
+    if (typeof value === "number") out.push(TAG_VELOCITY_LIFE, 5, axis, 0, value, value, 0)
+    else if (hasData(value)) {
+      const d = value._data
+      out.push(TAG_VELOCITY_LIFE, d.length + 1, axis)
+      for (let i = 0; i < d.length; i++) out.push(d[i])
+    } else out.push(TAG_VELOCITY_LIFE, 5, axis, 0, value.min, value.max, 0)
+  }
+}
+
+export const pushVelocity = (out: number[], val: Vec3Like | VelocityValue): void => {
+  if (Array.isArray(val) || val instanceof Float32Array || val instanceof Vec3) {
+    // a plain vector: launch along it, its length is the speed (native derives it)
+    out.push(TAG_VELOCITY, 6, 1, cx(val), cy(val), cz(val), 0, 0)
+    out.push(TAG_VELOCITY_RND, 5, 0, 0, 0, 0, 0)
+    return
+  }
+  const v = val as VelocityValue
+  let mode = 0
+  let p: Vec3Like = [ 0, 0, 0 ]
+  if ("dir" in v) { mode = 1; p = v.dir }
+  else if ("from" in v) { mode = 2; p = v.from }
+  else if ("to" in v) { mode = 3; p = v.to }
+  let lo = 0, hi = 0
+  if (v.speed !== undefined) {
+    if (typeof v.speed === "number") lo = hi = v.speed
+    else { lo = v.speed.min; hi = v.speed.max }
+  }
+  out.push(TAG_VELOCITY, 6, mode, cx(p), cy(p), cz(p), lo, hi)
+  if (v.spread !== undefined) {
+    out.push(TAG_VELOCITY_RND, 5, 1, -v.spread, -v.spread, v.spread, v.spread)
+  } else if (v.randomizeAngle) {
+    const a = v.randomizeAngle
+    out.push(TAG_VELOCITY_RND, 5, 1, cx(a.min), cy(a.min), cx(a.max), cy(a.max))
+  } else {
+    out.push(TAG_VELOCITY_RND, 5, 0, 0, 0, 0, 0)
+  }
+}
+
+/** A NOISE record; `null` turns the field off. */
+export const pushNoise = (out: number[], n: ParticleNoise | null): void => {
+  out.push(TAG_NOISE, 4, n ? n.strength ?? 1 : 0, n ? n.frequency ?? 1 : 0, n ? n.speed ?? 1 : 0, n ? n.ramp ?? 0 : 0)
+}
+
+/** A LIFETIME record. */
+export const pushLifetime = (out: number[], val: Range<number>): void => {
+  const [ lo, hi ] = lohi(val)
+  out.push(TAG_LIFETIME, 2, lo, hi)
+}
+
+/** The default flipbook: with a sheet of more than one frame and no explicit `frame`, one full sheet
+ *  cycle over each particle's lifetime, starting at `startFrame` (`'random'` = desynchronized loops). */
+export const pushDefaultFrames = (out: number[], cols: number, rows: number, startFrame: number | "random" = "random"): void => {
+  const frames = cols * rows
+  if (frames <= 1) return
+  const base = startFrame === "random" ? { min: 0, max: frames - 1 } : startFrame
+  pushParam(out, SLOT_FRAME, curve(base, "add").from(0).to(frames))
+}

package/src/g2/Font2D.ts

@@ -0,0 +1,87 @@
+// A font for 2D text (Text2D): a TTF / OTF file parsed natively by creator-2d, whose glyphs are
+// rasterized on demand as signed distance fields into ONE atlas per font — the same atlas serves every
+// size, so a Font2D is loaded once and used at any fontSize.
+//
+//   const inter = await Font2D.load(font("inter"))                 // a family the font() macro registered
+//   const bold  = await Font2D.load(font("inter"), { weight: 700 })
+//   const brand = await Font2D.load(asset('./fonts/Brand.ttf'))      // a file of the project, fetched as is
+//
+// A family name resolves through the faces the `font()` compile macro registered (ui/fonts.ts records
+// each face's TTF URL beside its UI registration — the native parser reads TTF / OTF, never the woff2
+// a browser's UI text may use): the exact weight / style, else the nearest registered weight of that
+// style. A name nobody registered fails with an error listing the registered families. Anything that
+// is not a bare name (it has a "/", "." or ":") is a URL / asset path and is fetched as is.
+//
+// Loads are cached per resolved URL, so every `Font2D.load("Inter")` of a project shares one native
+// font (and one atlas). `destroy()` frees it for every holder.
+
+import { fetch, type FetchResponse, type File } from "../runtime/fetch"
+import { _fontUrlOf, _registeredFontFamilies } from "../ui/fonts"
+
+export type Font2DOptions = {
+  /** For a registered family: the face's weight (default 400; the nearest registered one is used). */
+  weight?: number
+  /** For a registered family: the italic face (default false). */
+  italic?: boolean
+}
+
+// A bare family name ("Inter", "Brand Sans") — a URL or asset path always carries one of / . :
+const FAMILY_NAME = /^[^/\\.:]+$/
+
+let loaded: Map<string, Promise<Font2D>> | undefined   // resolved URL → the (pending) font
+const cache = (): Map<string, Promise<Font2D>> => (loaded ??= new Map())
+
+const resolveUrl = (source: string, options: Font2DOptions): string => {
+  if (!FAMILY_NAME.test(source)) return source
+  const italic = options.italic ?? false
+  const url = _fontUrlOf(source, options.weight ?? 400, italic)
+  if (url !== undefined) return url
+  const families = _registeredFontFamilies()
+  if (families.some((f) => f.toLowerCase() === source.toLowerCase())) {
+    throw new Error(`Font2D.load("${source}"): the family has no ${italic ? "italic" : "upright"} face registered — add it to the font("…") call (e.g. { italic: true }).`)
+  }
+  throw new Error(
+    `Font2D.load("${source}"): no font family "${source}" is registered — declare it with font("…") (a registry id or './fonts/X.ttf'), ` +
+    `or pass a URL / asset('./x.ttf'). Registered families: ${families.length > 0 ? families.join(", ") : "none"}.`,
+  )
+}
+
+export class Font2D {
+  /** Native font handle. */
+  readonly id: number
+  private _key?: string
+
+  /** @internal Use {@link Font2D.load}. */
+  constructor(id: number) {
+    this.id = id
+  }
+
+  /** A registered family name (what `font("inter")` compiles to, e.g. "Inter") picks the ttf of
+   *  (weight ?? 400, italic); anything else is a URL / asset path / response / File fetched as is
+   *  (`asset('./fonts/Brand.ttf')`). Cached per resolved URL: a family loads once. */
+  static load(source: string | FetchResponse | File, options: Font2DOptions = {}): Promise<Font2D> {
+    if (typeof source !== "string") {
+      return new Promise<Font2D>((resolve, reject) => {
+        _creator2d.createFont((source as any)._h.id, (id) => resolve(new Font2D(id)), (e) => reject(e instanceof Error ? e : new Error(`Font2D.load: not a TTF / OTF font (${String(e)})`)))
+      })
+    }
+    let url: string
+    try { url = resolveUrl(source, options) } catch (e) { return Promise.reject(e) }
+    const hit = cache().get(url)
+    if (hit) return hit
+    const pending = fetch(url, { useOnce: true }).then((resp) => {
+      if (resp.status >= 400) throw new Error(`Failed to fetch font from ${url}. HTTP ${resp.status}`)
+      return Font2D.load(resp)
+    }).then((font) => { font._key = url; return font })
+    pending.catch(() => { if (cache().get(url) === pending) cache().delete(url) })
+    cache().set(url, pending)
+    return pending
+  }
+
+  /** Free the native font (and its atlas) — for every holder of this cached font; a later load
+   *  parses it again. Texts still using it stop drawing. */
+  destroy(): void {
+    if (this._key !== undefined) { cache().delete(this._key); this._key = undefined }
+    _creator2d.destroyFont(this.id)
+  }
+}

package/src/g2/Material2D.ts

@@ -0,0 +1,64 @@
+// A 2D material: how a sprite or tilemap blends into what is under it and how its texture is
+// sampled. That is all a material is in 2D — no shader, no uniforms:
+//   - blend 'additive' adds the colour instead of covering: glow, fire, sparks, muzzle flashes, light
+//     shafts (black is transparent, overlaps brighten).
+//   - wrap 'repeat' tiles the texture when a sprite's UV `frame` reaches past [0,1]: a scrolling or
+//     parallax background is one sprite with a growing frame offset.
+//   - filter per texture: crisp 'nearest' pixel art beside smooth 'linear' hi-res art in one scene.
+//     Unset = the renderer default (the Scene2D `filter`).
+//
+//   new Sprite({ texture: flare, material: Material2D.additive() })
+//   sky.material = Material2D.sprite({ wrap: 'repeat', filter: 'linear' })
+//
+// The shape mirrors the 3D `Material.lit()` / `Material.unlit()` factories, but a Material2D is DATA,
+// not a native handle: the engine takes three ints per node, so one value can be shared by any number
+// of nodes and is immutable — to change a node's material, assign a new one.
+
+export type Blend2D = "alpha" | "additive"
+export type Filter2D = "nearest" | "linear"
+export type Wrap2D = "clamp" | "repeat"
+
+export type Material2DOptions = {
+  /** `'alpha'` (default) covers what is under it by its alpha; `'additive'` adds its colour. */
+  blend?: Blend2D
+  /** Texture sampling; unset = the renderer default (the Scene2D `filter`). */
+  filter?: Filter2D
+  /** `'clamp'` (default) stretches the edge texel past [0,1]; `'repeat'` tiles the texture. */
+  wrap?: Wrap2D
+}
+
+export class Material2D {
+  readonly blend: Blend2D
+  /** Undefined = the renderer default (the Scene2D `filter`). */
+  readonly filter?: Filter2D
+  readonly wrap: Wrap2D
+
+  private constructor(options: Material2DOptions) {
+    this.blend = options.blend ?? "alpha"
+    this.filter = options.filter
+    this.wrap = options.wrap ?? "clamp"
+  }
+
+  /** An alpha-blended material — what every sprite and tilemap has by default. */
+  static sprite(options: Material2DOptions = {}): Material2D {
+    return new Material2D(options)
+  }
+
+  /** An additive material: glow, fire, sparks, flashes. */
+  static additive(options: Omit<Material2DOptions, "blend"> = {}): Material2D {
+    return new Material2D({ ...options, blend: "additive" })
+  }
+
+  /** The default material (alpha blend, renderer-default filter, clamp). */
+  static readonly default: Material2D = Material2D.sprite()
+
+  /** @internal Push this material to an entity — the engine's three ints. */
+  _apply(entityId: number): void {
+    _creator2d.setMaterial(
+      entityId,
+      this.blend === "additive" ? 1 : 0,
+      this.filter === "nearest" ? 1 : this.filter === "linear" ? 2 : 0,
+      this.wrap === "repeat" ? 1 : 0,
+    )
+  }
+}

package/src/g2/Node2D.ts

@@ -1,5 +1,5 @@
 // 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
+// (position, draw order, 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
@@ -74,7 +74,7 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
   protected _rotation = 0
   protected _sx = 1
   protected _sy = 1
-  protected _layer = 0
+  protected _renderPriority = 4
   protected _z = 0
   protected _visible = true
 
@@ -183,11 +183,15 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
     }
   }
 
-  /** 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) }
+  /** Coarse draw order: 0 draws first, 7 last, 4 is the default — the 3D `Mesh.renderPriority`.
+   *  Within one priority `z` orders, then (with `scene.ySort` on) world Y. Rounded and clamped to 0..7. */
+  get renderPriority(): number { return this._renderPriority }
+  set renderPriority(v: number) {
+    this._renderPriority = Math.max(0, Math.min(7, Math.round(v)))
+    _creator2d.setRenderPriority(this.id, this._renderPriority)
+  }
 
-  /** Intra-layer depth for non-Y-sorted layers (higher z = on top). */
+  /** Draw order within a renderPriority (higher = on top); with `scene.ySort` on, equal z sorts by world Y. */
   get z(): number { return this._z }
   set z(v: number) { this._z = v; _creator2d.setZ(this.id, v) }