lecodes-cli 0.10.0 → 0.10.2

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "lecodes-cli",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "dependencies": {
-    "@letary/chisel": "^0.5.1"
+    "@letary/chisel": "^0.6.0"
   },
   "devDependencies": {
     "lecodes-design": "workspace:*",

package/runtime/sdk/canvas/Canvas.ts

@@ -241,8 +241,8 @@ export class Canvas {
   }
 
   /** Encode the current pixels to an image `File` — 'image/png' (default) or 'image/jpeg'. The File
-   *  is a host buffer handle {id,name,size}: append it to a FormData to upload, load it as a texture
-   *  (`Texture2D.load(file)`), or hand it to a share/save sheet. */
+   *  is an opaque host buffer handle (`name`/`size` only): append it to a FormData to upload, load it
+   *  as a texture (`Texture2D.load(file)`), or hand it to a share/save sheet. */
   toFile(name = "canvas.png", type = "image/png"): Promise<File> {
     const surfaceId = this._bakeSurface()
     return new Promise<File>((res, rej) => {

package/runtime/sdk/g2/Texture2D.ts

@@ -37,7 +37,7 @@ export class Texture2D {
       })
     }
     return new Promise<Texture2D>((resolve, reject) => {
-      _creator2d.createTexture((source as any).id ?? (source as any)._id, (id, w, h) => resolve(new Texture2D(id, w, h)), reject)
+      _creator2d.createTexture((source as any)._id, (id, w, h) => resolve(new Texture2D(id, w, h)), reject)
     })
   }
 

package/runtime/sdk/gl/Material.ts

@@ -36,6 +36,36 @@ const applyUniform = (id: number, key: string, value: UniformValue): void => {
 
 export type MaterialColorOptions = { color?: ColorInput, map?: Texture | Canvas | null }
 
+/** `Material.particles` options — the default point-sprite material for particle systems. */
+export type ParticlesMaterialOptions = {
+  /** Sprite texture — a single image or a flipbook sheet of frames. Unset = soft round dot. */
+  map?: Texture | null
+  /** Flipbook grid: `N` = an N×N sheet, `[cols, rows]` = a non-square one. Frames run
+   *  left-to-right, top-to-bottom; drive the index via `particles.frame`. Default 1. */
+  sheet?: number | [number, number]
+  /** Extra brightness multiplier for a glow look (0 = off). */
+  emissive?: number
+  /** Compositing: `"alpha"` (default — smoke, dust) or `"add"` (fire, sparks, magic). */
+  blend?: "alpha" | "add"
+  /** Soft radial falloff toward the sprite edge. Defaults to true without a map, false with one. */
+  soft?: boolean
+  /** How each particle is drawn: `'point'` (default — GPU point sprites, cheapest), `'quad'`
+   *  (real camera-facing quads — no driver size cap, geometric rotation), or `'stretch'`
+   *  (quads stretched along velocity — sparks, rain, speed streaks). `'ribbon'` is what `Trail`
+   *  uses internally. */
+  render?: "point" | "quad" | "stretch" | "ribbon"
+  /** (`render: 'stretch'`) extra sprite length in world units per unit of speed:
+   *  length = size + stretch·|velocity|. Default 0.05. */
+  stretch?: number
+}
+
+/** @internal — the sheet option as whole [cols, rows], both ≥ 1. The particles shader divides
+ *  by these with no guard of its own, so this clamp is the only thing between it and a NaN UV. */
+export 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) ]
+}
+
 /** `Material.lit` options — PBR scalars on top of the color/map pair. */
 export type LitMaterialOptions = MaterialColorOptions & {
   /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
@@ -116,6 +146,28 @@ export class Material {
     return m
   }
 
+  /** Default particle material — camera-facing point sprites with tint/opacity/rotation/flipbook
+   *  driven by the particle curves. Uniforms all default to 0 on a fresh instance, so every look
+   *  knob is primed here; JS writes after construction override them. */
+  static particles(options: ParticlesMaterialOptions = {}): Material {
+    const quad = options.render !== undefined && options.render !== "point"
+    // Both fetchLocal literals inline so the compiler's preload header captures the shader names.
+    const m = quad
+      ? new Material({ _id: _creatorUtils.fetchLocal("particles-quad.filamat") } as any)
+      : new Material({ _id: _creatorUtils.fetchLocal("particles.filamat") } as any)
+    m._useMapFlag = false
+    m.uniforms.sheetSize = _sheetColsRows(options.sheet)
+    m.uniforms.emissive = options.emissive ?? 0
+    m.uniforms.additive = options.blend === "add" ? 1 : 0
+    m.uniforms.softness = (options.soft ?? !options.map) ? 1 : 0
+    if (quad) {
+      m.uniforms.mode = options.render === "ribbon" ? 2 : options.render === "stretch" ? 1 : 0
+      m.uniforms.stretch = options.stretch ?? (options.render === "stretch" ? 0.05 : 0)
+    }
+    if (options.map) m.map = options.map
+    return m
+  }
+
   /** Material that samples a VideoPlayer's texture. */
   static video(map?: Texture): Material {
     const m = new Material({ _id: _creatorUtils.fetchLocal("video.filamat") } as any)