lecodes-sdk 2.4.9 → 2.5.0

package/src/g2/Sprite.ts

@@ -1,12 +1,15 @@
 // A textured 2D node. Cheap setters proxy straight to the native sprite; the data lives in
 // creator-2d. Sprite-sheet animation is no longer built in — attach the SpriteAnimation aspect:
 //   new Sprite({ texture }).aspect(SpriteAnimation, { size: [32, 48], idle: [0,1,2,3] }).anim.play('idle')
+// Without a texture a sprite is a solid rect: it draws the engine's 1x1 white texture, so `color` is
+// the rect's colour and `size` its world size — new Sprite({ size: [200, 20], color: '#3a7' }).
 
 import { Color, type ColorInput } from "../core/color"
 import { Vec2, type Vec2Like } from "../math/vec"
 import { Canvas, isCanvas } from "../canvas/Canvas"
 import { Node2D, type Node2DTweenProps } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
+import type { Material2D } from "./Material2D"
 import { DOM_SPRITE2D, colorValue, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
 import type { Animation } from "../animate/tween/Animation"
 
@@ -20,6 +23,7 @@ export type SpriteTweenProps = Node2DTweenProps & {
 export type TextureSource = Texture2D | Canvas
 
 export type SpriteOptions = {
+  /** Omit the texture for a solid rect of `color` with `size`. */
   texture?: TextureSource
   /** Pivot, [0,0] = top-left .. [1,1] = bottom-right. Use [0.5, 1] (feet) for Y-sorted depth. */
   anchor?: Vec2Like
@@ -30,7 +34,10 @@ export type SpriteOptions = {
   /** Tint multiplied with the texture. */
   color?: ColorInput
   opacity?: number
-  layer?: number
+  /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+  renderPriority?: number
+  /** Blend + sampling — see {@link Material2D}. Default `Material2D.default`. */
+  material?: Material2D
   position?: Vec2Like
 }
 
@@ -42,25 +49,32 @@ export class Sprite extends Node2D {
   private _flipX = false
   private _flipY = false
   private _size: Vec2 | null = null
+  private _material?: Material2D
 
   constructor(options: SpriteOptions = {}) {
     super()
+    // The texture first (its setSprite resets the native size to the texture's), then the size.
+    // No texture but a size / colour = a solid rect (the white texture). No texture and neither = a
+    // sprite whose texture comes later (a SpriteSheet entry still loading): nothing to draw yet.
     if (options.texture) this.texture = options.texture
+    else if (options.size || options.color !== undefined) this.texture = undefined
     if (options.size) this.size = options.size
     if (options.anchor) this.anchor = options.anchor
     if (options.frame) this.frame = options.frame
     if (options.color !== undefined) this.color = options.color
     if (options.opacity !== undefined) this.opacity = options.opacity
-    if (options.layer !== undefined) this.layer = options.layer
+    if (options.renderPriority !== undefined) this.renderPriority = options.renderPriority
+    if (options.material) this.material = options.material
     if (options.position) this.position = options.position
   }
 
+  /** The art; undefined = a solid rect of `color` (the engine's white texture). */
   get texture(): Texture2D | undefined { return this._texture }
   set texture(t: TextureSource | undefined) {
     const tex = isCanvas(t) ? t.texture() : t   // a Canvas bakes to a texture on assign
     this._texture = tex
-    if (!tex) return
-    _creator2d.setSprite(this.id, tex.id) // native resets UV + size to the full (pixel) texture
+    // native resets UV + size to the full (pixel) texture — 1x1 for the white one
+    _creator2d.setSprite(this.id, tex ? tex.id : _creator2d.whiteTexture())
     // A Canvas is authored in LOGICAL units but baked at logical × pixelRatio, so default the sprite's
     // WORLD size to the canvas's LOGICAL size — pixelRatio then only affects crispness, not on-screen
     // size. (A plain texture keeps the native default: the texture's pixel dimensions.)
@@ -101,6 +115,11 @@ export class Sprite extends Node2D {
   get opacity(): number { return this._opacity }
   set opacity(a: number) { this._opacity = a; _creator2d.setSpriteOpacity(this.id, a) }
 
+  /** Blend + sampling ({@link Material2D}); undefined = the default (alpha, renderer filter, clamp).
+   *  A material is data: assign a new one to change it. */
+  get material(): Material2D | undefined { return this._material }
+  set material(m: Material2D) { this._material = m; m._apply(this.id) }
+
   get flipX(): boolean { return this._flipX }
   set flipX(v: boolean) { this._flipX = v; _creator2d.setSpriteFlip(this.id, v, this._flipY) }
   get flipY(): boolean { return this._flipY }

package/src/g2/SpriteSheet.ts

@@ -5,9 +5,9 @@
 //
 //   import props from './props.sprite'
 //   import hero from './hero.sprite'
-//   scene.add(props.make('tree_orange', { position: [80, 144], layer: 1 }))
-//   scene.add(props.make('water', { position: [0, 0] }))            // sliced, loops on its own
-//   const player = hero.make('hero', { clip: 'idle', layer: 1 })
+//   scene.add(props.make('tree_orange', { position: [80, 144] }))
+//   scene.add(props.make('water', { position: [0, 0], z: -1 }))     // sliced, loops on its own
+//   const player = hero.make('hero', { clip: 'idle' })
 //   player.anim.play('walk', inputVector)
 //
 // A sheet describes ART only — rects, slices, clips, anchors. World semantics (colliders, bodies)
@@ -57,7 +57,10 @@ export type SpriteSheetDef = {
 
 export type SpriteMakeOptions = {
   position?: Vec2Like
-  layer?: number
+  /** Coarse draw order 0..7, default 4 — see {@link Node2D.renderPriority}. */
+  renderPriority?: number
+  /** Draw order within a renderPriority — see {@link Node2D.z}. */
+  z?: number
   /** Overrides the sheet/sprite anchor. */
   anchor?: Vec2Like
   /** Start this clip immediately (sliced sprites with clips). */
@@ -109,9 +112,10 @@ export class SpriteSheet {
 
     const sprite = new Sprite({
       anchor: opts.anchor ?? named.anchor ?? def.anchor,
-      layer: opts.layer,
+      renderPriority: opts.renderPriority,
       position: opts.position,
     })
+    if (opts.z !== undefined) sprite.z = opts.z
 
     // The world size is known without the texture (the rect, or its slice cell) — set it up front
     // so layout, Y-sort and colliders are correct even while the image is still loading.

package/src/g2/Text2D.ts

@@ -0,0 +1,178 @@
+// Text in a 2D scene: signed-distance-field glyphs drawn in the sprite batch, so a text sorts by
+// renderPriority / z (and ySort) like any sprite and batches with them.
+//
+//   const inter = await Font2D.load(font("inter"))
+//   new Text2D({ font: inter, text: 'Score 0', fontSize: 24, position: [0, 120] })
+//   new Text2D({ font: inter, text: 'Moscow', fontSize: 13, units: 'px', anchor: [0.5, 1],
+//                outline: { width: 0.12, color: '#000' } })            // a map label
+//
+// One atlas per font serves every size, and SDF edges stay sharp when the camera zooms in. `units:
+// 'px'` sizes the text in logical screen pixels, constant while the camera zooms — map labels,
+// nameplates; the default 'world' scales with the scene. `outline` is a halo around the glyphs
+// (width in em), what keeps a label readable over any background.
+//
+// Scope: Latin / Cyrillic / Greek-style scripts with kerning, '\n' and width wrapping, left / centre /
+// right alignment. No complex shaping (Arabic, Indic) and no emoji — UI text (UIText) does those.
+//
+// Layout is native: the block is laid out once per `text` / `font` / `fontSize` / `units` / style write,
+// never per frame — animate the node's transform, not its text, when something only moves.
+
+import { Color, type ColorInput } from "../core/color"
+import { Vec2, type Vec2Like } from "../math/vec"
+import { Node2D } from "./Node2D"
+import type { Font2D } from "./Font2D"
+import type { Material2D } from "./Material2D"
+
+export type TextAlign2D = "left" | "center" | "right"
+
+export type TextOutline2D = {
+  /** Halo width in em: 0.05 thin … 0.15 the maximum. 0 = none. */
+  width: number
+  /** Default black. */
+  color?: ColorInput
+}
+
+export type Text2DOptions = {
+  font: Font2D
+  text: string
+  /** Em height. `units: 'world'` (default) world units; `'px'` logical screen px — constant while the
+   *  camera zooms (map labels, nameplates). Default 16. */
+  fontSize?: number
+  units?: "world" | "px"
+  /** Default white. */
+  color?: ColorInput
+  /** Line alignment inside the block; default 'left'. */
+  align?: TextAlign2D
+  /** Wrap width in fontSize units; omit = no wrap. '\n' always breaks. */
+  maxWidth?: number
+  /** Multiplier of the font's own line height (default: the font's). */
+  lineHeight?: number
+  /** Extra spacing between letters, in em. Default 0. */
+  letterSpacing?: number
+  /** A halo around the glyphs; omit = none. */
+  outline?: TextOutline2D
+  /** Block anchor, [0,0] top-left … [1,1] bottom-right; default [0.5, 0.5] (centred on the node). */
+  anchor?: Vec2Like
+  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 text; see Material2D. */
+  material?: Material2D
+}
+
+const ALIGNS: Record<TextAlign2D, number> = { left: 0, center: 1, right: 2 }
+
+export class Text2D extends Node2D {
+  private _font: Font2D
+  private _text: string
+  private _fontSize = 16
+  private _units: "world" | "px" = "world"
+  private _color: ColorInput = 0xffffff
+  private _align: TextAlign2D = "left"
+  private _maxWidth?: number
+  private _lineHeight?: number
+  private _letterSpacing = 0
+  private _outline: TextOutline2D | null = null
+  private _anchor = new Vec2(0.5, 0.5)
+  private _material?: Material2D
+
+  constructor(options: Text2DOptions) {
+    super()
+    this._font = options.font
+    this._text = options.text
+    if (options.fontSize !== undefined) this._fontSize = options.fontSize
+    if (options.units !== undefined) this._units = options.units
+    if (options.align !== undefined) this._align = options.align
+    this._maxWidth = options.maxWidth
+    this._lineHeight = options.lineHeight
+    if (options.letterSpacing !== undefined) this._letterSpacing = options.letterSpacing
+    // setText first: it is what makes the entity a text natively; style / colour / anchor come after.
+    this._sendText()
+    this._sendStyle()
+    this.color = options.color ?? this._color
+    if (options.outline) this.outline = options.outline
+    this.anchor = options.anchor ?? this._anchor
+    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
+  }
+
+  // One call carries text + font + size + units: any of them re-lays out the block.
+  private _sendText(): void {
+    _creator2d.setText(this.id, this._font.id, this._text, this._fontSize, this._units === "px")
+  }
+
+  private _sendStyle(): void {
+    _creator2d.setTextStyle(
+      this.id, ALIGNS[this._align], this._maxWidth ?? 0, this._lineHeight ?? 0, this._letterSpacing,
+    )
+  }
+
+  /** The string; '\n' breaks a line. A write re-lays out the block natively. */
+  get text(): string { return this._text }
+  set text(v: string) { this._text = v; this._sendText() }
+
+  get font(): Font2D { return this._font }
+  set font(f: Font2D) { this._font = f; this._sendText() }
+
+  /** Em height, in `units`. */
+  get fontSize(): number { return this._fontSize }
+  set fontSize(v: number) { this._fontSize = v; this._sendText() }
+
+  /** 'world' (default) scales with the camera; 'px' = logical screen px, constant while zooming. */
+  get units(): "world" | "px" { return this._units }
+  set units(v: "world" | "px") { this._units = v; this._sendText() }
+
+  get color(): ColorInput { return this._color }
+  set color(c: ColorInput) {
+    this._color = c
+    const [ r, g, b, a ] = Color.toRgba01(c)
+    _creator2d.setTextColor(this.id, r, g, b, a)
+  }
+
+  get align(): TextAlign2D { return this._align }
+  set align(v: TextAlign2D) { this._align = v; this._sendStyle() }
+
+  /** Wrap width in fontSize units; undefined = no wrap. */
+  get maxWidth(): number | undefined { return this._maxWidth }
+  set maxWidth(v: number | undefined) { this._maxWidth = v; this._sendStyle() }
+
+  /** Multiplier of the font's own line height; undefined = the font's. */
+  get lineHeight(): number | undefined { return this._lineHeight }
+  set lineHeight(v: number | undefined) { this._lineHeight = v; this._sendStyle() }
+
+  /** Extra spacing between letters, in em. */
+  get letterSpacing(): number { return this._letterSpacing }
+  set letterSpacing(v: number) { this._letterSpacing = v; this._sendStyle() }
+
+  /** The halo, or null = none. */
+  get outline(): TextOutline2D | null { return this._outline ? { ...this._outline } : null }
+  set outline(o: TextOutline2D | null) {
+    this._outline = o ? { ...o } : null
+    if (!o || o.width <= 0) { _creator2d.setTextOutline(this.id, 0, 0, 0, 0, 0); return }
+    const [ r, g, b, a ] = o.color !== undefined ? Color.toRgba01(o.color) : [ 0, 0, 0, 1 ]
+    _creator2d.setTextOutline(this.id, o.width, r, g, b, a)
+  }
+
+  /** Block anchor, [0,0] top-left … [1,1] bottom-right. */
+  get anchor(): Vec2 { return this._anchor.clone() }
+  set anchor(v: Vec2Like) { this._anchor = new Vec2(v); _creator2d.setSpriteAnchor(this.id, this._anchor.x, this._anchor.y) }
+
+  /** Blend ({@link Material2D}) — only `blend` matters for a text. Undefined = the default (alpha). */
+  get material(): Material2D | undefined { return this._material }
+  set material(m: Material2D) { this._material = m; m._apply(this.id) }
+
+  /** The laid-out block [width, height] in fontSize units (from the engine). */
+  get bounds(): Vec2 {
+    const s = _creator2d.getTextSize(this.id)
+    return new Vec2(s[0]!, s[1]!)
+  }
+}

package/src/g2/Tilemap.ts

@@ -3,6 +3,7 @@
 
 import { Node2D } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
+import type { Material2D } from "./Material2D"
 
 export type TilemapOptions = {
   texture: Texture2D
@@ -15,11 +16,14 @@ export type TilemapOptions = {
   atlas: [number, number]
   /** Row-major tile indices into the atlas (-1 = empty), length cols*rows. Row 0 is the top row. */
   data: number[] | Int32Array
+  /** Blend + sampling — see {@link Material2D}. Default `Material2D.default`. */
+  material?: Material2D
 }
 
 export class Tilemap extends Node2D {
   readonly cols: number
   readonly rows: number
+  private _material?: Material2D
 
   constructor(options: TilemapOptions) {
     const data = options.data instanceof Int32Array ? options.data : Int32Array.from(options.data)
@@ -32,8 +36,14 @@ export class Tilemap extends Node2D {
     super(id) // wrap the native tilemap entity
     this.cols = options.cols
     this.rows = options.rows
+    if (options.material) this.material = options.material
   }
 
+  /** Blend + sampling ({@link Material2D}); undefined = the default (alpha, renderer filter, clamp).
+   *  A material is data: assign a new one to change it. */
+  get material(): Material2D | undefined { return this._material }
+  set material(m: Material2D) { this._material = m; m._apply(this.id) }
+
   setTile(x: number, y: number, index: number): this {
     _creator2d.setTile(this.id, x, y, index)
     return this

package/src/g2/defineScene2d.ts

@@ -2,19 +2,24 @@
 // The 2D sibling of scene/defineScene.ts — same literal grammar (one default-exported
 // `defineScene2d({...})` call, nodes keyed by name, `use(...)` aspects, `make(...)` factories),
 // with the 2D source vocabulary: `sprite` (a named entry of an imported `.sprite.ts` sheet),
-// `tilemap` (texture + grid + a `cells('…')` payload), `camera`, `make`, or none = group.
+// `tilemap` (texture + grid + a `cells('…')` payload), `path` (vector lines / polygons — Path2D),
+// `text` (SDF text — Text2D; `font` is a font("…") family or a font file URL), `particles` (a 2D
+// particle system — Particles2D; `texture` is an asset URL), `camera`, `make`, or none = group.
 //
 //   // forest.scene2d.ts
 //   import props from './props.sprite'
 //   import hero from './hero.sprite'
 //   export default defineScene2d({
-//     env: { background: '#5a6b3b', pixelPerfect: true, gravity: [0, 0] },
-//     layers: { 1: { ySort: true } },
+//     env: { background: '#5a6b3b', pixelPerfect: true, gravity: [0, 0], ySort: true },
 //     nodes: {
 //       ground: { tilemap: { texture: asset('./TileSet.png'), tile: 64, atlas: [64, 64],
-//                            cells: cells('…') }, layer: 0 },
-//       tree1:  { sprite: { sheet: props, name: 'tree_orange' }, position: [160, 288], layer: 1 },
-//       player: { sprite: { sheet: hero, clip: 'idle' }, position: [800, 200], layer: 1,
+//                            cells: cells('…') }, z: -1 },   // under everything Y-sorted at z 0
+//       tree1:  { sprite: { sheet: props, name: 'tree_orange' }, position: [160, 288] },
+//       road:   { path: { points: [[0, 0], [400, 120]], stroke: { width: 3, units: 'px' } } },
+//       sign:   { text: { font: font('inter'), text: 'Forest', fontSize: 14, units: 'px' }, position: [0, 64] },
+//       fire:   { particles: { rate: 40, lifetime: 0.8, size: 16, startVelocity: [0, 90], color: '#ffaa33' },
+//                 material: { blend: 'additive' }, position: [320, 96] },
+//       player: { sprite: { sheet: hero, clip: 'idle' }, position: [800, 200],
 //                 aspects: [use(CameraFollow, { smooth: 0.12 })] },
 //     },
 //   })
@@ -38,6 +43,11 @@ import { Scene2D } from "./Scene2D"
 import { Node2D } from "./Node2D"
 import { Sprite } from "./Sprite"
 import { Tilemap } from "./Tilemap"
+import { Path2D, type Stroke2D } from "./Path2D"
+import { Text2D, type TextAlign2D, type TextOutline2D } from "./Text2D"
+import { Particles2D, type Particles2DOptions } from "./Particles2D"
+import { Font2D } from "./Font2D"
+import { Material2D, type Material2DOptions } from "./Material2D"
 import { Texture2D } from "./Texture2D"
 import { Physics2D } from "./Physics2D"
 import { SpriteSheet } from "./SpriteSheet"
@@ -51,8 +61,12 @@ import type { With } from "../core/Aspect"
 export type Scene2dEnv = {
   /** Background color — '#5a6b3b', 0x5a6b3b, or [r,g,b] in 0..1. */
   background?: ColorInput
-  /** Texture sampling: 'nearest' (crisp pixel art, engine default) or 'linear'. */
+  /** Default texture sampling: 'nearest' (crisp pixel art, engine default) or 'linear'. A node's
+   *  `material.filter` overrides it. */
   filter?: "nearest" | "linear"
+  /** Top-down depth: among nodes of one renderPriority and one z, the one lower on screen draws on
+   *  top (see Scene2D.ySort). */
+  ySort?: boolean
   /** Pixel-art crispness: snap the camera to whole screen pixels (seeds CameraFollow's
    *  `pixelSnap`, and the initial camera position lands on whole world units). */
   pixelPerfect?: boolean
@@ -85,6 +99,51 @@ export type TilemapSourceDef = {
   cells: CellsData | { cols: number, rows: number, data: number[] | Int32Array }
 }
 
+/** A vector node (Path2D): a polyline / polygon in the node's local frame. */
+export type PathSourceDef = {
+  points: readonly Vec2Like[]
+  /** Close the stroke's ring (fills always close). Default false. */
+  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). */
+  antialias?: boolean
+}
+
+/** A text node (Text2D). `font` is a STRING: a family registered by `font("…")` (what the macro
+ *  compiles to, e.g. "Inter") or a font file URL — `asset('./fonts/Brand.ttf')`. */
+export type TextSourceDef = {
+  font: string
+  text: string
+  /** Em height (default 16), in `units`. */
+  fontSize?: number
+  /** 'world' (default) or 'px' — logical screen px, constant while the camera zooms. */
+  units?: "world" | "px"
+  /** Default white. */
+  color?: ColorInput
+  align?: TextAlign2D
+  /** Wrap width in fontSize units; omit = no wrap. */
+  maxWidth?: number
+  /** Multiplier of the font's own line height. */
+  lineHeight?: number
+  /** Extra spacing in em. */
+  letterSpacing?: number
+  outline?: TextOutline2D
+  /** Block anchor, [0,0] top-left … [1,1] bottom-right; default [0.5, 0.5]. */
+  anchor?: Vec2Like
+}
+
+/** A particle system node (Particles2D): the Particles2D options, with `texture` as a STRING — the
+ *  sheet image's URL (`asset('./spark.png')`), loaded with Texture2D.load. The blend is the node's
+ *  generic `material`; position / z / renderPriority are the node's too. */
+export type Particles2DSourceDef = Omit<Particles2DOptions, "texture" | "material" | "position" | "z" | "renderPriority"> & {
+  texture?: string
+}
+
 /** A camera marker node: seeds the scene camera's starting position (+ zoom). To MOVE the camera
  *  in play, attach `CameraFollow` to the node being followed — not aspects on this marker. */
 export type Camera2dNodeDef = { zoom?: number }
@@ -93,6 +152,9 @@ export type Scene2dNodeDef = {
   // -- source (at most one; none = plain group node) --
   sprite?: SpriteSourceDef
   tilemap?: TilemapSourceDef
+  path?: PathSourceDef
+  text?: TextSourceDef
+  particles?: Particles2DSourceDef
   camera?: Camera2dNodeDef
   /** A code-built subtree — `make(factoryFn, { ...literal args })`, factory returns a Node2D. */
   make?: SharedMakeEntry<any, Node2D>
@@ -101,11 +163,14 @@ export type Scene2dNodeDef = {
   /** Degrees, CCW. */
   rotation?: number
   scale?: Vec2Like | number
-  /** Draw layer (int) — higher renders on top. */
-  layer?: number
-  /** Intra-layer depth for non-Y-sorted layers. */
+  /** Coarse draw order 0 (first) … 7 (last), default 4 — see Node2D.renderPriority. */
+  renderPriority?: number
+  /** Draw order within a renderPriority (higher = on top); with `env.ySort`, equal z sorts by Y. */
   z?: number
-  /** Sprite tint (sprite nodes only). */
+  /** Blend + sampling (sprite, tilemap, text and particles nodes; only `blend` matters for a text) —
+   *  see Material2D. */
+  material?: Material2DOptions
+  /** Sprite tint / text colour (sprite and text nodes). */
   color?: ColorInput
   /** Sprite opacity 0..1 (sprite nodes only). */
   opacity?: number
@@ -126,8 +191,6 @@ export type Scene2dCameraDef = {
 
 export type Scene2dDef = {
   env?: Scene2dEnv
-  /** Per-layer config, keyed by layer number: `layers: { 1: { ySort: true } }`. */
-  layers?: Record<number | string, { ySort?: boolean }>
   /** Starting camera when there's no camera NODE (a camera node wins). */
   camera?: Scene2dCameraDef
   nodes?: Record<string, Scene2dNodeDef>
@@ -139,6 +202,9 @@ type SourceNodeOf<N extends Scene2dNodeDef> =
   N extends { sprite: { clip: string } } ? Sprite & { anim: SpriteAnimation }
   : N extends { sprite: SpriteSourceDef } ? Sprite
   : N extends { tilemap: TilemapSourceDef } ? Tilemap
+  : N extends { path: PathSourceDef } ? Path2D
+  : N extends { text: TextSourceDef } ? Text2D
+  : N extends { particles: Particles2DSourceDef } ? Particles2D
   : Node2D
 
 type AspectsOf<N extends Scene2dNodeDef> =
@@ -209,11 +275,31 @@ const createTilemap = async (
   })
 }
 
+const createText = async (name: string, def: TextSourceDef): Promise<Text2D> => {
+  if (typeof def.font !== "string") {
+    throw new Error(`Scene2d node "${name}": text.font must be a string — a font("…") family or a font file URL`)
+  }
+  const { font, ...rest } = def
+  return new Text2D({ ...rest, font: await Font2D.load(font) })
+}
+
+const createParticles = async (name: string, def: Particles2DSourceDef): Promise<Particles2D> => {
+  const { texture, ...rest } = def
+  if (texture === undefined) return new Particles2D(rest)
+  if (typeof texture !== "string") {
+    throw new Error(`Scene2d node "${name}": particles.texture must be a string — an image URL (asset('./spark.png'))`)
+  }
+  return new Particles2D({ ...rest, texture: await Texture2D.load(texture) })
+}
+
 const createSource = (name: string, def: Scene2dNodeDef): Node2D | Promise<Node2D> => {
-  const sources = [ def.sprite, def.tilemap, def.camera, def.make ].filter((s) => s !== undefined).length
-  if (sources > 1) throw new Error(`Scene2d node "${name}" declares more than one source (sprite/tilemap/camera/make)`)
+  const sources = [ def.sprite, def.tilemap, def.path, def.text, def.particles, def.camera, def.make ].filter((s) => s !== undefined).length
+  if (sources > 1) throw new Error(`Scene2d node "${name}" declares more than one source (sprite/tilemap/path/text/particles/camera/make)`)
   if (def.sprite !== undefined) return createSprite(name, def.sprite)
   if (def.tilemap !== undefined) return createTilemap(name, def.tilemap, def.aspects)
+  if (def.path !== undefined) return new Path2D(def.path)
+  if (def.text !== undefined) return createText(name, def.text)
+  if (def.particles !== undefined) return createParticles(name, def.particles)
   // make/camera/group nodes are plain wrappers — make subtrees mount under them in phase 2
   return new Node2D()
 }
@@ -223,8 +309,11 @@ const applyNode = (node: Node2D, name: string, def: Scene2dNodeDef): void => {
   if (def.position) node.position = def.position
   if (def.rotation !== undefined) node.rotation = def.rotation
   if (def.scale !== undefined) node.scale = def.scale
-  if (def.layer !== undefined) node.layer = def.layer
+  if (def.renderPriority !== undefined) node.renderPriority = def.renderPriority
   if (def.z !== undefined) node.z = def.z
+  if (def.material !== undefined && (node instanceof Sprite || node instanceof Tilemap || node instanceof Text2D || node instanceof Particles2D)) {
+    node.material = Material2D.sprite(def.material)
+  }
   if (def.visible !== undefined) node.visible = def.visible
   if (def.locked !== undefined) (node as { _sceneLocked?: boolean })._sceneLocked = def.locked
   if (def.camera !== undefined) (node as { _sceneCamera?: boolean })._sceneCamera = true
@@ -235,6 +324,7 @@ const applyNode = (node: Node2D, name: string, def: Scene2dNodeDef): void => {
     if (def.flipX !== undefined) node.flipX = def.flipX
     if (def.flipY !== undefined) node.flipY = def.flipY
   }
+  if (node instanceof Text2D && def.color !== undefined) node.color = def.color
 }
 
 /** The first camera-source def in file order (depth-first), or null. */
@@ -323,10 +413,7 @@ const instantiate = async (def: Scene2dDef): Promise<{ scene: Scene2D, nodes: Re
   // create bodies right after the node build). Edit mode holds physics as data — skip.
   if (env.gravity !== undefined && !isEditMode()) Physics2D.configure({ gravity: env.gravity })
 
-  const scene = new Scene2D({ background: env.background, filter: env.filter })
-  for (const [ key, layer ] of Object.entries(def.layers ?? {})) {
-    if (layer?.ySort) scene.layer(Number(key)).ySort(true)
-  }
+  const scene = new Scene2D({ background: env.background, filter: env.filter, ySort: env.ySort })
 
   const nodes: Record<string, Node2D> = {}
   await buildNodes(def.nodes ?? {}, null, scene, nodes, env)
@@ -370,7 +457,7 @@ export class Scene2dHandle<D extends Scene2dDef = Scene2dDef> {
 /**
  * Define a 2D scene as data — the default export of a `.scene2d.ts` file. Returns a typed handle:
  * `const { scene, nodes } = await handle.open()` gives `nodes.<name>` typed by its source block
- * (Sprite / Tilemap / Node2D) with its `use(...)`d aspects attached.
+ * (Sprite / Tilemap / Path2D / Text2D / Particles2D / Node2D) with its `use(...)`d aspects attached.
  */
 export const defineScene2d = <const D extends Scene2dDef>(def: D): Scene2dHandle<D> => {
   const handle = new Scene2dHandle(def)

package/src/g2/groups2d.ts

@@ -1,5 +1,5 @@
-// Collision groups — which bodies are allowed to touch which. Called groups, not layers, because
-// `layer` already means DRAW order in 2D (`node.layer`, `scene2d.layer(n).ySort()`).
+// Collision groups — which bodies are allowed to touch which. Called groups, not layers, so the name
+// never reads as DRAW order (that is `node.renderPriority` / `node.z` / `scene.ySort` in 2D).
 //
 //   // game/groups.ts
 //   export const player  = Physics2D.addGroup()

package/src/gl/Foliage.ts

@@ -61,13 +61,6 @@ export type FoliageOptions = {
   /** 0..1: how far the baked per-vertex sky visibility (the crown's interior, the trunk under it) darkens the ambient.
    *  Default 0.7. */
   skyAo?: number
-  /** 0..1: a leaf card's shading normal, from the card's own plane (0) to the crown's hull normal (1) — what hides that a
-   *  crown is flat quads: each card is lit as the part of the volume it sits in. Default 0.7. */
-  canopy?: number
-  /** The cards' normal-map strength (a strong map brings the planes back). Default 0.5. */
-  normalMap?: number
-  /** A card seen edge-on dissolves over this much of |N·V| — no paper edges on the silhouette. Default 0.15, 0 = none. */
-  edgeFade?: number
   /** Coverage held over distance: the cards' alpha × (1 + coverage × mip level), so a far crown does not thin out as its
    *  atlas mips away. Default 0.25, 0 = none; past ~0.5 a crown turns into a solid mass. */
   coverage?: number
@@ -89,9 +82,6 @@ const state: Required<Omit<FoliageOptions, "wind">> & { wind: Required<FoliageWi
   translucency: 0.35,
   leafShadow: 0.6,
   skyAo: 0.7,
-  canopy: 0.7,
-  normalMap: 0.5,
-  edgeFade: 0.15,
   coverage: 0.25,
   castDistance: 0,
 }
@@ -118,12 +108,7 @@ export const Foliage = {
     if (options.leafShadow !== undefined) { state.leafShadow = options.leafShadow; leaf = true }
     if (options.skyAo !== undefined) { state.skyAo = options.skyAo; leaf = true }
     if (leaf) _creator.foliageSetLeaf?.(state.shiver, state.translucency, state.leafShadow, state.skyAo)
-    let look = false
-    if (options.canopy !== undefined) { state.canopy = options.canopy; look = true }
-    if (options.normalMap !== undefined) { state.normalMap = options.normalMap; look = true }
-    if (options.edgeFade !== undefined) { state.edgeFade = options.edgeFade; look = true }
-    if (options.coverage !== undefined) { state.coverage = options.coverage; look = true }
-    if (look) _creator.foliageSetLook?.(state.canopy, state.normalMap, state.edgeFade, state.coverage)
+    if (options.coverage !== undefined) { state.coverage = options.coverage; _creator.foliageSetLook?.(state.coverage) }
     if (options.castDistance !== undefined) { state.castDistance = options.castDistance; _creator.foliageSetCast?.(state.castDistance) }
   },