/threejs-scroll-worlds

name: threejs-scroll-worlds
description: Build rich, scroll-controlled real-time Three.js experiences as one persistent 3D world whose camera, lighting, atmosphere, materials, objects, DOM story, and interactions evolve across authored chapters. Use for 3D scrollytelling, scroll-driven WebGL worlds, camera journeys, interactive portfolios, product stories, exhibitions, explainers, game or film microsites, spatial narratives, and multi-scene websites where native scroll should travel through one continuous place. Not limited to landing pages.
metadata:
  author: Meng To
  source: https://github.com/MengTo/skills/tree/a965851e27dc179e693fde1bee94457a64e1a7a5/agent-skills/web-design/build-threejs-scroll-worlds
  license: MIT

Build Three.js Scroll Worlds

Build one detailed real-time world and use native document scroll as its deterministic conductor. Keep the renderer, scene graph, and spatial continuity alive while camera composition, light, fog, animation, copy, and interaction focus move through authored chapters.

The mechanism is **one persistent Three.js world + one normalized reversible scroll state**. If removing either makes the experience collapse into stacked sections, this skill applies.

The exact [Kage demo](demo/index.html) proves the quality bar; it is staging, not a mandatory subject or layout. Use its detailed anatomy only when the requested direction benefits from it: [references/kage-anatomy.md](references/kage-anatomy.md).

Route the request correctly

• Use `threejs` for a single interactive scene with no scroll-authored journey.
• Use `scroll-world-storytelling` when deciding between real-time 3D, pre-rendered video, and DOM-first storytelling.
• Use `scroll-scrubbed-visual-sequence` for a video or image sequence whose time is scrubbed by scroll.
• Use `cinematic-scroll-storytelling` for DOM-first GSAP/Lenis choreography.
• Use this skill when objects must remain truly spatial and interactive while scroll moves through several compositions in one live WebGL world.

Do not disguise a video as Three.js. The public [oso95/scroll-world](https://github.com/oso95/scroll-world) project, reviewed at commit `71cc36d`, is a strong reference for intake, scene ledgers, budget gates, mobile-specific composition, config-driven playback, and seam QA, but its renderer is a pre-generated video chain. This skill adopts those structural strengths while retaining real geometry, materials, lighting, raycasting, and camera control.

Read the build references

Before implementing a new world, read:

• [references/world-bible.md](references/world-bible.md) for intake, art direction, scene, material, texture, and interaction ledgers;
• [references/realtime-architecture.md](references/realtime-architecture.md) for the scene graph, conductor, camera, loading, interaction, and lifecycle patterns;
• [references/quality-and-qa.md](references/quality-and-qa.md) before optimization and final verification.

Copy [references/scroll-conductor.js](references/scroll-conductor.js) when a project needs a portable native-scroll conductor rather than a framework-specific implementation.

Start with the output, not the template

Determine what the world is for: a landing page, portfolio, museum chapter, product explanation, game teaser, editorial essay, data story, or another spatial experience. Do not force every request into a hero-plus-CTA layout.

Discover only what is unknown:

• the subject, audience, and ordered story beats;
• the art direction and emotional arc;
• whether the world is continuous, portal-connected, or composed as adjacent sets;
• the target devices and minimum acceptable hardware;
• how interactive the world should be beyond scrolling;
• available models, textures, brand assets, audio, and copy;
• the initial-load and total-download budget.

If the user supplied an approved reference or working scene, inspect it first and carry its real geometry, materials, textures, light ratios, camera values, and motion constants into the ledger. Do not replace measured details with adjectives.

Write the world bible before code

Define one reusable visual grammar:

• scale system and unit convention;
• silhouette language and level of stylization;
• palette and per-chapter accent progression;
• material families and wear logic;
• key, fill, rim, practical, and emissive light roles;
• fog, haze, particles, weather, and post-processing;
• typography, DOM composition, and near-plane foreground rules;
• motion grammar for camera, ambient objects, and interactions.

Every visible detail must support the same world. Random noise, unrelated texture packs, arbitrary particle effects, and one-off materials create complexity without cohesion.

Author a scene ledger

Use 4–8 chapters for most experiences. Store the full contract as data rather than scattering thresholds through CSS and the render loop:

const chapters = [
  {
    id: "threshold",
    scrollWeight: 1.25,
    copy: {
      eyebrow: "Chapter 01",
      title: "Enter the archive",
      body: "A spatial collection revealed through motion."
    },
    camera: {
      position: [0, 3.8, 13.5],
      target: [0, 2.4, -8],
      fov: 38,
      mobile: { position: [0, 4.8, 18], fov: 46 }
    },
    world: {
      key: 1.0,
      practicals: 0.35,
      fog: 0.018,
      particles: 0.25,
      grade: "cold"
    },
    focus: ["gate", "lantern-left"],
    interactions: ["inspect-gate"],
    assets: ["gate-shell", "stone-1k", "mist-atlas"]
  }
];

For each chapter record the story beat, landmark, camera endpoint, occluders, light/fog state, active animation clips, interaction targets, DOM beat, foreground treatment, asset dependencies, and responsive override. Reject a chapter that differs only by copy.

Build one persistent spatial architecture

Create these systems once:

WebGL canvas
  worldRoot
    environment       sky, terrain, distant silhouettes
    architecture      persistent landmarks and paths