Cookbook — Spark (Gaussian Splats) · cb-spark

Owner directive (2026-07-10), canonical. "For now, generate with the Holonprint Loop with gaussian splatting, lenis, tailwind, react, next, use webgl … just execute what is being said in official doc." [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:498]

Official docs

Cookbook rule per the owner order: implementations follow the official docs exactly; the patterns below are our proven applications of them, not replacements.

Our proven patterns

1. fileBytes loader with byte-true progress. Stream the .splat over fetch + res.body.getReader(), emit (id, loadedBytes, totalBytes) per chunk, concatenate, then construct new SplatMesh({ fileBytes, fileName, onLoad }) and await onLoad. Spark decodes the packed-splat layout natively when fileName ends in .splat. [src: HOS-Instance/packages/engine/src/engine/loader.ts:108]
2. Packed .splat record contract (32 bytes, little-endian): f32×3 position · f32×3 scale · u8×4 color(rgba) · u8×4 rotation(qw,qx,qy,qz mapped q*128+128) — written by the offline generators, consumed by Spark. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:154]
3. One SparkRenderer in the scene. Create it once with the shared WebGLRenderer and scene.add(spark); all SplatMeshes render through it. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:44]
4. Manifest-driven tiered assets. Every asset declares files/bytes/count per desktop|mobile tier plus its world AABB and owning chapter; the loader sums totalBytes/totalCount for budget checks. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:17]
5. Dispose-safe mid-flight loads. Cache slots carry a disposed flag; if dispose(id) lands while bytes are in flight, the built mesh is immediately disposed and the promise rejects — no orphan GPU memory. [src: HOS-Instance/packages/engine/src/engine/loader.ts:147]
6. Chapter slabs. Each chapter owns a disjoint world-space slab along −Z so adjacent chapters can be co-resident without overlap; camera flies mostly along −Z. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:166]
7. Dual-position morph plan (Spatial Site v2, planned). Letterform sceneries are baked with two positions per splat (scenery pose / Arabic-letterform pose per the owner order [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:481]) and morphed by scroll progress — see pb-001-spatial-site-loop step 4.

Gotchas

• Never trust content-length alone — prefer the manifest's declared bytes, fall back to the header, else to running total. [src: HOS-Instance/packages/engine/src/engine/loader.ts:119]
• The loader deliberately does NOT add meshes to the scene — placement belongs to the director's ChapterContext. [src: HOS-Instance/packages/engine/src/engine/loader.ts:53]
• Eviction is a soft budget: unmount chapters ≥2 away, farthest first, only while resident count exceeds SPLAT_BUDGET[tier]. [src: HOS-Instance/packages/engine/src/engine/director.ts:182]

Budgets

SPLAT_BUDGET = { desktop: 700_000, mobile: 300_000 } visible-splat ceilings [src: HOS-Instance/packages/engine/src/engine/contracts.ts:149] — thresholds governed by bm-002-splat-budget; frame budgets by bm-001-web-perf.

Composition

• uses: cb-threejs (peer runtime) · gaussian-splatting · spark-renderer
• used-by: pb-001-spatial-site-loop (steps 3–6) · cb-patterns-royal-orbit · schema-holonprint (method gaussian-splatting)

See also

• bm-002-splat-budget · holonprint · spatial-site