{
  "schema": "leumas.docs.page/1",
  "id": "skill:threejs-leumas",
  "slug": "skills/threejs-leumas",
  "kind": "tools",
  "bucket": "skill",
  "title": "threejs-leumas",
  "name": "Threejs Leumas",
  "eyebrow": null,
  "chip": null,
  "summary": "Three.js, WebGL and GLSL work inside Leumas2 — which scene rig to reuse, where 3D code may live, the pinned three version, the shader-adapter convention.",
  "keywords": [
    "threejs-leumas",
    "glsl",
    "loading accessibility",
    "leumas2",
    "webgl",
    "leumas threejs leumas",
    "hand-roll renderer",
    "convention"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "\n# Three.js in Leumas2\n\nTwo skills, two jobs. **`threejs-skill-router`** (24-skill pack, installed at user scope) owns *technique* — how to author an ocean, a volumetric cloud, bloom, GTAO, a camera rig. **This skill** owns *placement and constraints* — what to reuse, where the code goes, and what this repo's renderer and versions actually support. Load the router for the graphics; obey this file for the wiring.\n\nIf the router skill is missing, install the pack:\n\n```sh\nnpx threejs-awesome-graphics-agent-skills@0.4.4 install --agent claude-code --scope user\n```\n\n## Never hand-roll a renderer\n\nLeumas already owns its 3D plumbing. Reuse it — this is golden rule 2, and the pack will not know about it.\n\n| Building | Use | Where |\n|---|---|---|\n| An r3f scene (declarative, JSX) | `SceneCanvas` — owns `<Canvas>`, the error boundary, and the reduced-motion poster fallback | `shared/packages/cinematic/src/scene/SceneCanvas.jsx` |\n| A raw-three viewer (imperative) | `createSceneRig(mount, { onFrame, … })` — renderer, camera, OrbitControls, RAF loop, ResizeObserver, disposal | `shared/packages/forge/src/hud/scene/sceneRig.js`, exported from `@leumas/forge` |\n| Model/mesh viewing (STL/OBJ/FBX/GLTF) | `@leumas/react-3d-viewer` | `shared/packages/react-3d-viewer/src/` |\n\n`@leumas/splats` is the reference for the raw-three path — `SplatsViewer.jsx` imports `createSceneRig` from `@leumas/forge` and adds only its point-cloud and fly-control layers. Copy that shape. A new `new THREE.WebGLRenderer(...)` plus a fresh `requestAnimationFrame` loop in a product is a bug, not a scene.\n\n## Where new 3D code lives\n\nApply the reusability test — *could a different product use this by itself?*\n\n- **Yes** → a shared package. Reusable scene primitives and splash/hero pieces go in `shared/packages/cinematic/src/`; generic viewers get their own package via the `scaffold-package` skill.\n- **No** → it stays local: `products/leumas-web/src/cinematic/scenes/` for one-off web scenes (see `BlackHole.jsx`, `Cosmos.jsx`, `FlowerOfLife.jsx`), or the owning Studio surface.\n\nSplash screens are a **`cinematic` mode** in `shared/packages/config-registry/src/modes.js`, CRUD'd through Studio → Imperium Configs — not a bespoke route. Generated textures/video belong in `shared/services/datacenter` under `/library/cinematic/`, consumed via `@leumas/assets-sdk`.\n\n## Renderer reality: WebGL, not WebGPU\n\nThe pack targets three `^0.184` and several of its skills assume three's **node/TSL + WebGPU** pipeline — `threejs-spectral-ocean` (WebGPU/TSL FFT), `threejs-shadow-systems` (TSL shadow nodes), `threejs-parallax-occlusion-mapping` (WebGPU + TSL), and `threejs-bloom` (bloom-node). Leumas renders **WebGL** through r3f/drei and raw three. Those four need translating, not copying. So:\n\n- Translate node-pipeline advice to WebGL — `EffectComposer` + `UnrealBloomPass`, or the CSS neon-glow approach `SceneCanvas.jsx` deliberately uses *instead of* a postprocessing pass (\"reads like bloom without a postprocessing pass\").\n- Do not introduce `three/webgpu`, `three/tsl`, or a `WebGPURenderer` without an explicit decision — it is a renderer migration, not an import.\n- `postprocessing`, `gsap`, and `lenis` are **not installed anywhere** in this repo, despite `cinematic-frontend-director` prescribing the latter two. Adding one is a dependency decision; say so rather than assuming it's there.\n\n## Versions\n\nRoot `package.json` pins `\"three\": \"0.180.0\"` as a pnpm override; individual packages declare anywhere from `^0.160` to `^0.180`. The override wins at install time. Before using an API the pack suggests, confirm it exists in 0.180 — the pack's own bloom reference tells you to verify the installed node API, and that advice applies doubly here.\n\n## Shaders follow the existing adapter convention\n\nThis repo already has the largest shader surface in it: **219 WebGL2 music-visualizer adapters** in `shared/engines/adapters/media/music/catalog/adapters/*GL.js`, plus 14 camera-effect shaders in `data/library-apps/Camera/adapters/`. Each declares `meta.ctxType: 'webgl2'` and compiles inline `#version 300 es` vertex/fragment sources. New GPU effects in those domains follow that contract — don't stand up a second shader host or a `.glsl` file convention that nothing else reads.\n\n## Loading and accessibility\n\n- three-flavoured modules must be `React.lazy`'d — a hard requirement for `@leumas/splats`, and the right default everywhere else. three + drei is a large chunk; it must not land in a first paint.\n- Honour `prefers-reduced-motion` and ship the poster fallback. `SceneCanvas` does both already — going around it means reimplementing both.\n- Target 60fps with a mobile fallback; the router's `$threejs-visual-validation` skill gives you a deterministic evidence set when a scene needs defending.\n\n## Licensing note\n\nThe pack is published as `MIT AND GPL-3.0-only`. 23 skills derive from MIT/Zlib sources; <!-- counts-ok: a third-party pack's contents, not this tree -->\n **`threejs-precipitation-surfaces`** (rain, puddles, snow accumulation) derives from a GPL-3.0 project, and that copyleft attaches to code derived from its references and examples. Leumas ships as a paid EXE and a white-label product — worth knowing before lifting code from that one skill into a shared package.\n\n## Related skills\n\n- `threejs-skill-router` — all graphics technique; start there for the visual system itself.\n- `cinematic-frontend-director` — creative direction, the cinematic arc, Higgsfield asset generation. It sets the taste; the router executes it.\n- `leumas-capabilities`, its `placement.md` lane — the full placement conventions this file summarizes for 3D.\n- `scaffold-package` — when a viewer or scene primitive earns its own `@leumas/*` package.\n",
  "source": {
    "path": ".claude/skills/threejs-leumas/SKILL.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 5998,
    "hash": "9521634ba921ea02d485f51127036432126178a9"
  },
  "urls": {
    "html": "/p/skills/threejs-leumas",
    "json": "/docs/skills/threejs-leumas.json",
    "md": "/docs/skills/threejs-leumas.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}