cookbookcanonicalOWNER-2026-07-10

Cookbook — Royal Orbit Engine Patterns · cb-patterns-royal-orbit

Owner directive (2026-07-10), canonical. "Refine and make it in the level of the sceneries, transitions, elements, effects, story telling, composition, of mont-fort.com. … SITES LEVEL AWWARD, SPATIAL SITE, ROYALORBIT THE FIRST BETTER THAN MONT-FORT, perfomance awesome, you may have loading, no worries, but the experience should be pristine." [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:455]

Official docs

This is a patterns cookbook — its "official doc" is our own proven engine, @hos/engine ("HOS Spatial Site engine — Gaussian-splat scroll-film HolonPrint renderer (framework-agnostic vanilla TS)" [src: HOS-Instance/packages/engine/package.json:5]). Library pins per cb-spark, cb-threejs, cb-lenis, cb-gsap.

Our proven patterns

Architecture. The site is one fixed WebGL canvas (Gaussian splats via Spark) behind normal DOM sections. DOM sections define scroll length; a master Lenis scrub produces pageProgress ∈ [0,1]; chapters map sub-ranges of that progress to camera keyframes through their splat worlds. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:6]

  1. Chapter slabs. Every chapter owns a disjoint world slab along −Z (hero [0,−200] … finale [−2000,−2200]); generators bake geometry centered on the slab, so adjacent chapters can be co-resident with zero overlap and the camera simply flies forward. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:179]
  2. Theme arc (dawn → night). A single THEME_ARC of {at, fog, ink} stops keyed to page progress; canvas clear color and page background lerp through it; ink sets flip once at the night threshold NIGHT_AT = 0.48, write-on-change only. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:83]
  3. Fog = background dissolve trick. The fog hue "equals page bg" by contract — the canvas clear color and CSS --bg are the same lerped color every frame, so splat-world edges dissolve invisibly into the DOM page. This is what makes one canvas feel like continuous sceneries. [src: HOS-Instance/packages/engine/src/engine/contracts.ts:73] [src: HOS-Instance/packages/engine/src/engine/theme.ts:60]
  4. Director lifecycle: mount active, prefetch next, evict ≥2 away. Prefetch warms bytes+meshes without adding to scene; eviction is soft-budget, farthest-first, only while resident splats exceed SPLAT_BUDGET[tier]; mounts are deduped through an in-flight map. [src: HOS-Instance/packages/engine/src/engine/director.ts:142]
  5. Unclamped adjacent updates. Active ±1 chapters get update(ctx, p, t) with chapter-local progress that may be <0/>1 — enables cross-chapter transition choreography without special cases. [src: HOS-Instance/packages/engine/src/engine/director.ts:113]
  6. DPR governor. Frame-time EMA (τ=1 s) evaluated every 2 s: step DPR down when fps < 50, back up (never above the starting step) after 6 s of fps > 58; steps per tier desktop [1.75…0.7] / mobile [1.25…0.5]. [src: HOS-Instance/packages/engine/src/engine/quality.ts:38] [src: HOS-Instance/packages/engine/src/engine/contracts.ts:143]
  7. Tier pick + ?lite=1. Device tier decided once at boot (small screen / deviceMemory ≤ 4 / coarse+small); ?lite=1 forces mobile tier at lowest DPR for verification and weak hardware. [src: HOS-Instance/packages/engine/src/engine/quality.ts:16]
  8. Byte-progress loading UX. Loader emits (id, loaded, total) per network chunk so the loading experience is honest ("you may have loading, no worries"); totals come from the manifest. [src: HOS-Instance/packages/engine/src/engine/loader.ts:47]
  9. rAF-starvation / 0×0-boot guard. Viewport is polled every frame with a fallback chain (innerWidth → clientWidth → wrapper → constant); dt clamped to 0.1 s. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:49]
  10. Reduced-motion parity. With prefers-reduced-motion, Lenis is never created but native scroll feeds the identical progress events — every consumer is smoothing-agnostic. [src: HOS-Instance/packages/engine/src/engine/scroll.ts:64]
  11. Dual-position morph plan (v2, planned). Bake each letterform splat with two positions (scenery pose / Arabic-letterform pose) and lerp by chapter progress — the v2 letterforms directive [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:481]; executed as pb-001-spatial-site-loop step 4.

Gotchas

  • Progress must be emitted from the Lenis scroll event; an animation-less scrub ScrollTrigger silently under-fires onUpdate. [src: HOS-Instance/packages/engine/src/engine/scroll.ts:60]
  • disposeAsset during an in-flight load is legal — the slot flag handles it; never assume load completion before dispose. [src: HOS-Instance/packages/engine/src/engine/loader.ts:147]
  • The world-camera convention (fly along −Z with lateral drift) is a contract with the generators — cameras that leave the slab corridor will see neighbouring chapters pop.

Budgets

SPLAT_BUDGET desktop 700k / mobile 300k [src: HOS-Instance/packages/engine/src/engine/contracts.ts:149] governed by bm-002-splat-budget; fps/DPR thresholds by bm-001-web-perf.

Composition

See also

Linked from — 17 cards