threejs-router

name: threejs-router description: Route Three.js and 3D WebGL work to focused upstream reference slices (CloudAI-X, freshtechbro, sickn33). Use when building, debugging, or polishing Three.js scenes — instrument panels, cockpit gauges, 3D data visualizations, hero scenes, GLTF model loading, PBR materials, shaders, geometry, lighting, postprocessing, OrbitControls, raycasting, or browser-based 3D games. NOT for 2D canvas particle backgrounds — use particle-pipeline instead. NOT for ECharts 3D — use echarts instead.

Three.js Router

Thin router over focused Three.js skill references hosted at skills.sh and GitHub. Do not load every reference by default — pick the smallest relevant set.

This skill does not pull upstream skill bodies into the repo to avoid context bloat. Open references/upstream-summaries.md for source inventory; the registry routes to specific URLs.

When to use this skill vs. siblings

If your task is the submarine hero, ocean-flow-bg.js, or any 2D canvas particle work — stop and use particle-pipeline. This skill won't help you there.

First step

Read references/registry.yaml and pick the smallest relevant route. Each route has a primary upstream source plus backup options.

For ordinary Three.js work:

1. Use threejs-fundamentals for scene/camera/renderer, Object3D hierarchy, resize, render loop.
2. Add exactly the technical slice you need: geometry, materials, textures, lighting, loaders, interaction, shaders, or postprocessing.
3. Add game references only for game loops, levels, collision, player controls.
4. Add design_webgl (freshtechbro) for polished editorial/portfolio scenes — distinct from simulations or games.

High-fidelity instrument panel route (cockpit gauges, engine telegraphs)

Read in order:

1. threejs-fundamentals — renderer, camera, resize, controls, pixel ratio
2. threejs-geometry — model one reusable gauge/control first
3. threejs-materials — PBR for brass, enamel, rubber, painted metal, glass
4. threejs-textures — generate or load dial faces, ticks, labels, roughness/normal/grime maps
5. threejs-lighting — build the scene around reflections, shadows, env light, readable highlights
6. threejs-postprocessing — bloom, vignette, tone mapping AFTER the base render is solid
7. threejs-interaction — pointer hover, drag, click, orbit, annotations, state changes

Use shaders only for effects standard materials can't handle (CRT scanlines, custom glass distortion, procedural patina, animated phosphor, unusual dial illumination).

Implementation biases

• Build one finished component before composing a full panel.
• Prefer canvas/SVG-generated textures for crisp dial faces and tiny labels (over 3D text geometry).
• Prefer MeshPhysicalMaterial for glass, clearcoat, metals, high-end surfaces.
• Use environment maps + shadow tuning before postprocessing.
• Use CSS/HTML/SVG overlays for explanatory callouts when 3D text would reduce legibility.
• Use InstancedMesh for repeated ticks, screws, lamps, rivets, buttons, grid marks.
• Keep the camera framing inspectable on desktop and mobile.

Verification

• Start the dev/static server, verify with browser or Playwright screenshots.
• For WebGL scenes specifically: sample canvas pixels or inspect WebGL context state to prove the canvas isn't blank.
• Check at least one desktop and one mobile viewport.
• Verify against the lessons we learned in ~/.claude/projects/.../memory/learning_threejs_force_layouts.md if doing force-directed layouts (d3-force-3d CDN fails silently; pre-compute in Python; LineBasicMaterial caps at 1px).

Source policy

This router summarizes upstream Three.js skills but does not vendor them. Reasons:

• Avoid context bloat — the full CloudAI-X family is ~9 skill bodies; loading them all eats context.
• Upstream authors maintain the canonical source.
• Routing logic and the high-fidelity-panel sequence (above) are our additions; the slices themselves stay upstream.

If you genuinely need a full upstream skill body, fetch it from the URL in references/registry.yaml. The freshtechbro skill — explicitly referenced in our submarine work — lives at https://www.skills.sh/freshtechbro/claudedesignskills/threejs-webgl.

Cross-references

• references/registry.yaml — routes + upstream sources
• references/upstream-summaries.md — one-paragraph summaries of each upstream skill
• particle-pipeline skill — for 2D canvas particle work (the actual submarine pipeline; this skill is NOT that)
• ~/.claude/projects/.../memory/learning_threejs_force_layouts.md — force-layout lessons