lecodes-sdk 0.20.2 → 1.0.0

package/src/canvas/Canvas.ts

@@ -35,6 +35,11 @@ const OP = {
   DRAW_IMAGE: 30,
 } as const
 
+// Above this many buffered values, a buffer that is STILL growing between bakes is a leak, not a
+// drawing (a dense static picture is a few thousand; a 15 Hz graph without reset() passes this in
+// seconds and doubles its frame cost every minute).
+const CMD_GROWTH_WARN = 20000
+
 const ALIGN = { left: 0, center: 1, right: 2, start: 3, end: 4 } as const
 const BASELINE = { alphabetic: 0, top: 1, middle: 2, bottom: 3, hanging: 4, ideographic: 5 } as const
 const JOIN = { miter: 0, round: 1, bevel: 2 } as const
@@ -76,6 +81,11 @@ export class Canvas {
   // also refreshes the on-screen image node(s) via _creatorUI — the UI consumer the 2D/3D texture
   // hooks below don't cover. Stays a bare flag so a non-UI canvas never references the UI bridge.
   private _uiBound = false
+  // Growth watch: the command buffer is a RECORDING that every bake replays in full, so a canvas
+  // redrawn every frame without `reset()` gets slower with every update. `_bakeSurface` compares the
+  // buffer against the previous bake and warns once when it keeps growing past the threshold.
+  private _lastBakeLen = 0
+  private _warnedGrowth = false
 
   constructor(width: number, height: number, opts: { pixelRatio?: number } = {}) {
     this.width = width
@@ -198,6 +208,17 @@ export class Canvas {
 
   /** @internal — rasterize the recorded commands into the surface; returns the surface id. */
   _bakeSurface(): number {
+    const len = this._cmd.length
+    if (!this._warnedGrowth && len > CMD_GROWTH_WARN && this._lastBakeLen > 0 && len > this._lastBakeLen) {
+      this._warnedGrowth = true
+      console.warn(
+        `[canvas] ${this.width}×${this.height}: the command buffer keeps growing (${len} values, ` +
+        `${this._lastBakeLen} at the previous bake) — a Canvas records every call and each update() ` +
+        `replays all of it, so a redraw that never calls reset() gets slower every frame. ` +
+        `Call canvas.reset() before redrawing (or toBitmap() + reset() to flatten a drawing).`,
+      )
+    }
+    this._lastBakeLen = len
     const buf = new Float32Array(this._cmd)
     this._surfaceId = _creatorCanvas.rasterize(this._surfaceId, this.width, this.height, this.pixelRatio, buf, buf.length, this._refs)
     return this._surfaceId

package/src/compile/__tests__/compile.test.ts

@@ -39,6 +39,17 @@ test("a 2D project (new Scene2D) is marked 2d: enable and gl: disable", async ()
   expect(js).toContain("_creator2d.createScene")
 })
 
+test("a 3D project with a Canvas is NOT marked 2d: enable (Canvas keeps a `_creator2d.` texture path)", async () => {
+  const js = await compileProject({
+    name: "Car",
+    publicUrl: "https://le.codes",
+    entries: [ { path: "/main.ts", type: "text", text: "const c = new Canvas(64, 64)\nc.update()\nnew Scene().open()\n" } ],
+  })
+  expect(js).toContain("_creator2d.") // the canvas 2D-texture path survives tree-shaking
+  expect(js).not.toContain("// 2d: enable") // …but no Scene2D → the 2D engine is not in use
+  expect(js).not.toContain("// gl: disable")
+})
+
 test("2D and 3D bundles are DISJOINT (tree-shake drops the other engine)", async () => {
   const twoD = await compileProject({
     name: "2D", publicUrl: "https://le.codes", header: false,

package/src/compile/header.ts

@@ -33,8 +33,11 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
   else if (code.includes("_creator.createEngine")) header += `// gl: defer\n`
 
   // 2D (creator-2d) — non-exclusive: emitted alongside `gl: disable` so hosts skip Filament and a
-  // 2D-aware host brings up the lightweight sokol engine instead.
-  if (code.includes("_creator2d.")) header += `// 2d: enable\n`
+  // 2D-aware host brings up the lightweight sokol engine instead. Keyed on the scene constructor
+  // (like GL above), NOT on any `_creator2d.` reference: Canvas carries a 2D-texture path
+  // (`canvas.texture()` → `_creator2d.createTextureFromCanvas`) that chisel keeps in a pure-3D
+  // bundle, and nothing 2D works without a Scene2D anyway.
+  if (code.includes("_creator2d.createScene")) header += `// 2d: enable\n`
 
   if (code.includes("_creator.createARController")) header += `// ar: enable\n`
 
@@ -61,7 +64,7 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
 /** Same engine signals the header uses, for callers that need the project kind (e.g. icon type). */
 export const detectProjectKind = (code: string): "ar" | "ui" | "2d" | "3d" => {
   if (code.includes("_creator.createARController")) return "ar"
-  if (code.includes("_creator2d.")) return "2d"
+  if (code.includes("_creator2d.createScene")) return "2d"
   if (!code.includes("_creator.")) return "ui"
   return "3d"
 }

package/src/compile/index.ts

@@ -73,6 +73,7 @@ export {
 export {
   loadSceneHarness,
   sceneEditorEntries,
+  sceneImportsOf,
   SCENE_ENTRY_PATH,
   SCENE_HARNESS_DIR,
 } from "./sceneEditor"

package/src/compile/sceneEditor.ts

@@ -47,10 +47,44 @@ export const loadSceneHarness = (fallbackDir?: string): Record<string, string> =
  * the project's file list — `.editor.ts` entries are picked out of it. Compile with
  * `entryOverride: SCENE_ENTRY_PATH`, `header: false`, `format: "iife"`, `editor: true`.
  */
+/** Resolve a relative import specifier against a project path ("./src/map.scene.ts" + "./map/x.scene"
+ *  → "./src/map/x.scene"). */
+const resolveRelative = (fromPath: string, spec: string): string => {
+  const segs = (p: string) => p.split("/").filter((s) => s !== "" && s !== ".")
+  const out = segs(fromPath).slice(0, -1)
+  for (const seg of segs(spec)) {
+    if (seg === "..") out.pop()
+    else out.push(seg)
+  }
+  return "./" + out.join("/")
+}
+
+/**
+ * The other scene files a scene file imports as prefabs (`import x from './x.scene'`), as project
+ * paths present in `projectPaths`. The edit bundle registers their handles BY PATH
+ * (`__lecodesSceneFiles`), so the editor can live-patch a `prefab:` node — add, duplicate, undo —
+ * without a compile: the doc sees `prefab: X` as an identifier, the host maps it through the
+ * file's import table to this path, and the harness resolves the path to the running handle.
+ */
+export const sceneImportsOf = (sceneText: string, scenePath: string, projectPaths: string[]): string[] => {
+  const known = new Set(projectPaths)
+  const out: string[] = []
+  const re = /^\s*import\s+[A-Za-z_$][\w$]*\s+from\s+["']([^"']+\.scene(?:\.ts)?)["']/gm
+  for (const m of sceneText.matchAll(re)) {
+    const spec = m[1]
+    if (!spec.startsWith(".")) continue
+    let p = resolveRelative(scenePath, spec)
+    if (!p.endsWith(".ts")) p += ".ts"
+    if (known.has(p) && !out.includes(p)) out.push(p)
+  }
+  return out
+}
+
 export const sceneEditorEntries = (
   scenePath: string,
   harness: Record<string, string>,
   projectPaths: string[] = [],
+  sceneImports: string[] = [],
 ): CompileEntry[] => {
   const entries: CompileEntry[] = Object.entries(harness).map(([ name, text ]) => ({
     path: `${SCENE_HARNESS_DIR}/${name}`,
@@ -74,15 +108,22 @@ export const sceneEditorEntries = (
   const materialImports = materialPaths.map((p, i) => `import __mat${i} from "${p}"\n`).join("")
   const materialRegister = materialPaths.length === 0 ? ""
     : `;(globalThis as any).__lecodesMaterials = { ${materialPaths.map((p, i) => `${JSON.stringify(p)}: __mat${i}`).join(", ")} }\n`
+  // The scene's prefab imports, registered by project path (see sceneImportsOf) — the same module
+  // instances the scene itself imported, so a live-patched prefab node is the same handle.
+  const sceneImportLines = sceneImports.map((p, i) => `import __scn${i} from "${p}"\n`).join("")
+  const sceneRegister = sceneImports.length === 0 ? ""
+    : `;(globalThis as any).__lecodesSceneFiles = { ${sceneImports.map((p, i) => `${JSON.stringify(p)}: __scn${i}`).join(", ")} }\n`
   entries.push({
     path: SCENE_ENTRY_PATH,
     type: "text",
     text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
       + materialImports
+      + sceneImportLines
       + `import "${scenePath}"\n`
       + editorImports
       + `import "${SCENE_HARNESS_DIR}/main.ts"\n`
-      + materialRegister,
+      + materialRegister
+      + sceneRegister,
   })
   return entries
 }

package/src/gl/DecalSet.ts

@@ -35,6 +35,14 @@ export type DecalOptions = {
   fadeIn?: number
   /** Seconds of fade at the end of `life` (ignored with life 0). Default 0. */
   fadeOut?: number
+  /** Opacity multipliers at the image's BOTTOM and TOP edge (−Y / +Y), interpolated along it — a
+   *  tire mark that darkens as the slide deepens. Default `[1, 1]`. */
+  gradient?: [number, number]
+  /** Tilt of the image's bottom and top edge, as a unit-space slope (Δy per Δx across the box):
+   *  the edge pivots on the corner of the side it keeps and cuts INTO the box on the other, so two
+   *  boxes can meet on one shared line — what `DecalTrail` uses to mitre its joints. `0` = square.
+   *  Default `[0, 0]`. */
+  caps?: [number, number]
 }
 
 export type DecalSetOptions = DecalOptions & {
@@ -63,8 +71,10 @@ export type DecalSetOptions = DecalOptions & {
   /** HDR boost of the image (0 = none). Default material only. */
   emissive?: number
   name?: string
-  /** Coarse draw order, 0 (first) … 7 (last); default 4 — see `Mesh.renderPriority`. Decals are
-   *  blended and sort with the other blended draws of their priority. */
+  /** Coarse draw order, 0 (first) … 7 (last) — see `Mesh.renderPriority`. Default 3: a decal is
+   *  part of the surface it sits on, so it draws before every other blended thing (meshes 4,
+   *  particles 5) — the engine's depth sort compares object centres, and a set spread over the
+   *  level has no useful centre. */
   renderPriority?: number
 }
 
@@ -86,7 +96,7 @@ export type DecalPlacement = DecalOptions & {
   rotation?: QuatLike | Vec3Like
 }
 
-const RECORD = 23
+const RECORD = 27
 const NO_SLOT = 0xFFFFFFFF
 
 export class DecalSet extends Node {
@@ -116,7 +126,7 @@ export class DecalSet extends Node {
     }
     if (_creator.createDecalSet) {
       _creator.createDecalSet(this.id, Material.idOf(this._material), this._max)
-      if (options.renderPriority !== undefined) this.renderPriority = options.renderPriority
+      this.renderPriority = options.renderPriority ?? 3
     } else if (!DecalSet._warned) {
       DecalSet._warned = true
       console.warn("[decals] this host has no createDecalSet — decals are not drawn")
@@ -200,7 +210,8 @@ export class DecalSet extends Node {
     return this._write(slot, right, up, normal, new Vec3(p.position), p)
   }
 
-  private _write(slot: number, right: Vec3, up: Vec3, normal: Vec3, centre: Vec3, o: DecalOptions): number {
+  /** @internal One decal's frame → record → host (`DecalTrail` writes its segments through here). */
+  _write(slot: number, right: Vec3, up: Vec3, normal: Vec3, centre: Vec3, o: DecalOptions): number {
     const d = this._defaults
     const size = o.size ?? d.size!
     const w = typeof size === "number" ? size : size[0]
@@ -222,6 +233,10 @@ export class DecalSet extends Node {
     const opacity = o.opacity ?? d.opacity!
     r[16] = tr; r[17] = tg; r[18] = tb; r[19] = ta * opacity
     r[20] = o.life ?? d.life!; r[21] = o.fadeIn ?? d.fadeIn!; r[22] = o.fadeOut ?? d.fadeOut!
+    const caps = o.caps ?? d.caps
+    r[23] = caps ? caps[0] : 0; r[24] = caps ? caps[1] : 0
+    const gradient = o.gradient ?? d.gradient
+    r[25] = gradient ? gradient[0] : 1; r[26] = gradient ? gradient[1] : 1
     if (slot === NO_SLOT) {
       if (!_creator.addDecal) return -1
       const s = _creator.addDecal(this.id, r)
@@ -231,3 +246,115 @@ export class DecalSet extends Node {
     return slot
   }
 }
+
+/** A `DecalTrail`'s look: the strip's width, and what every segment carries. */
+export type DecalTrailOptions = Omit<DecalOptions, "size" | "caps" | "gradient"> & {
+  /** Width of the strip on the surface, world units. */
+  width: number
+}
+
+// The mitre stops making sense past this turn between two segments (a sharp reversal would need a
+// box longer than the strip is wide); the trail breaks there and starts afresh.
+const TRAIL_MAX_SLOPE = 1.75   // tan 60°
+
+/**
+ * A continuous strip of decals along a path — a tire's skid mark, a dragged body, a tread track.
+ * Feed it points (`add`) as the thing moves; every new point becomes one box-decal SEGMENT from the
+ * previous point, its image's up along the travel, and the joints between segments are MITRED: each
+ * box is cut along the bisector it shares with its neighbour (`caps`), so the strip has no overlaps
+ * darkening the outside of a bend and no wedges of gap on the inside. The opacity given with each
+ * point is interpolated along the segment (`gradient`), so a mark can darken as a slide deepens and
+ * fade as it ends. Segments are the set's decals — same ring, same `max` budget: a set of 900 holds
+ * 900 segments across every trail drawn from it.
+ *
+ * The previous segment is REWRITTEN when the next point arrives (its far cap becomes the shared
+ * mitre), through `DecalSet.update`'s path — a recycled slot is simply left alone by the engine.
+ */
+export class DecalTrail {
+  private _prev: { point: Vec3, opacity: number } | null = null
+  private _seg: {
+    slot: number, start: Vec3, end: Vec3, dir: Vec3, right: Vec3, normal: Vec3,
+    slopeStart: number, a0: number, a1: number,
+  } | null = null
+
+  readonly set: DecalSet
+  readonly options: DecalTrailOptions
+
+  constructor(set: DecalSet, options: DecalTrailOptions) {
+    this.set = set
+    this.options = options
+  }
+
+  /** Extend the strip to `point` on a surface with `normal`, `opacity` (0..1) at that point. The
+   *  first call after a start / `end()` only anchors the strip. Returns the new segment's slot, or
+   *  −1 when nothing was drawn (the anchor, a point that did not move, no host support). */
+  add(point: Vec3Like, normal: Vec3Like, opacity = 1): number {
+    const p = new Vec3(point)
+    const n = new Vec3(normal).normalize()
+    const prev = this._prev
+    this._prev = { point: p, opacity }
+    if (!prev) return -1
+    // The segment, flattened onto the surface plane.
+    let d = p.sub(prev.point)
+    d = d.sub(n.scale(d.dot(n)))
+    const len = d.length()
+    if (len < 1e-3) { this._prev = prev; return -1 }   // not moved: wait for a real step
+    const dir = d.scale(1 / len)
+    const right = dir.cross(n)   // DecalSet.spawn's frame: right × up = normal, image unmirrored from the normal's side
+    const w = this.options.width
+
+    // Mitre with the previous segment: the joint's bisector is the sum of the two right normals,
+    // and each box takes it as a cap — the previous one at its END (rewritten now), this one at its
+    // START — with the slopes measured in each box's own frame. A trail's first segment, or one
+    // after a break, starts square.
+    let slopeStart = 0
+    const last = this._seg
+    if (last) {
+      const lastDir = last.dir.sub(n.scale(last.dir.dot(n))).normalize()
+      const lastRight = lastDir.cross(n)
+      const m = lastRight.add(right)
+      const denom = m.dot(right)
+      const slopeEnd = Math.abs(denom) > 1e-4 ? m.dot(lastDir) / denom : Infinity
+      if (Math.abs(slopeEnd) <= TRAIL_MAX_SLOPE) {
+        this._rewrite(last, slopeEnd)
+        slopeStart = -slopeEnd
+      } else {
+        this._rewrite(last, 0)   // too sharp to mitre: leave the last one square, start afresh
+      }
+    }
+    const seg = { slot: -1, start: prev.point, end: p, dir, right, normal: n, slopeStart, a0: prev.opacity, a1: opacity }
+    seg.slot = this._box(seg, 0, -1)
+    this._seg = seg
+    return seg.slot
+  }
+
+  /** Finish the strip. With a `point`, one last segment runs out to it at opacity 0 — a mark that
+   *  tapers away instead of stopping dead. The next `add` anchors a new strip. */
+  end(point?: Vec3Like, normal: Vec3Like = Vec3.up): this {
+    if (point && this._prev) this.add(point, normal, 0)
+    this._prev = null
+    this._seg = null
+    return this
+  }
+
+  private _rewrite(seg: NonNullable<DecalTrail["_seg"]>, slopeEnd: number): void {
+    if (seg.slot >= 0) this._box(seg, slopeEnd, seg.slot)
+  }
+
+  /** Write one segment's box: the strip between its joints, extended past each mitred joint by the
+   *  mitre's reach (w/2 · |slope|) so the tilted cap still passes through the joint's centre. */
+  private _box(seg: NonNullable<DecalTrail["_seg"]>, slopeEnd: number, slot: number): number {
+    const w = this.options.width
+    const L = seg.end.sub(seg.start).length()
+    const extStart = 0.5 * w * Math.abs(seg.slopeStart)
+    const extEnd = 0.5 * w * Math.abs(slopeEnd)
+    const boxLen = L + extStart + extEnd
+    const centre = seg.start.add(seg.dir.scale(0.5 * boxLen - extStart))
+    // World slopes → unit-space slopes: x is measured in widths, y in box lengths.
+    const caps: [number, number] = [ seg.slopeStart * (w / boxLen), slopeEnd * (w / boxLen) ]
+    const { width: _w, ...rest } = this.options
+    const s = this.set._write(slot < 0 ? NO_SLOT : slot, seg.right, seg.dir, seg.normal, centre,
+      { ...rest, size: [ w, boxLen ], caps, gradient: [ seg.a0, seg.a1 ] })
+    return slot < 0 ? s : slot
+  }
+}