build-threejs-scroll-worlds

构建 Three.js 滚动世界

构建一个细节丰富的实时世界，并使用原生文档滚动作为确定性的指挥器。让渲染器、场景图和空间连续性始终保持运行，同时让摄像机取景、光照、雾效、动画、文案和交互焦点随着精心编排的章节推进。

其机制是一个持久运行的 Three.js 世界 + 一个标准化且可逆的滚动状态。如果移除其中任一项，体验就会坍塌成堆叠的分区，那么这项技能就适用。

确切的 Kage 演示展示了质量标准；它用于展示场景编排，并非必须采用的主题或布局。只有当用户要求的方向适合时，才使用其详尽的解剖说明：references/kage-anatomy.md。

正确判断请求应使用哪项技能

• 对于没有滚动叙事流程的单一交互场景，使用 threejs。
• 在实时 3D、预渲染视频和以 DOM 为先的叙事之间进行选择时，使用 scroll-world-storytelling。
• 对于由滚动控制播放进度的视频或图像序列，使用 scroll-scrubbed-visual-sequence。
• 对于以 DOM 为先的 GSAP/Lenis 编排，使用 cinematic-scroll-storytelling。
• 当物体必须保持真实的空间属性和交互能力，而滚动会让镜头在一个实时 WebGL 世界中的多个构图间移动时，使用这项技能。

不要把视频伪装成 Three.js。公开的 oso95/scroll-world 项目（审阅时的提交为 71cc36d）是很好的参考，尤其是在需求收集、场景台账、预算门槛、针对移动设备的构图、配置驱动的播放和接缝 QA 方面；但它的渲染器使用的是预生成视频链。这项技能吸收了其中的结构性优势，同时保留真实几何体、材质、光照、射线投射和摄像机控制。

阅读构建参考资料

构建新世界前，请阅读：

• references/world-bible.md，了解需求收集、美术指导、场景、材质、纹理和交互台账；
• references/realtime-architecture.md，了解场景图、指挥器、摄像机、加载、交互和生命周期模式；
• 优化和最终验证前，请阅读 references/quality-and-qa.md。

如果项目需要可移植的原生滚动指挥器，而非特定框架的实现，请复制 references/scroll-conductor.js。

从最终产出入手，而非套用模板

确定这个世界的用途：着陆页、作品集、博物馆章节、产品说明、游戏预告、编辑文章、数据叙事，或其他空间体验。不要把所有请求都硬套进「首屏主视觉 + CTA」布局。

只探明尚不明确的内容：

• 主题、受众和按顺序排列的故事节点；
• 美术指导和情绪曲线；
• 世界是连续的、由传送门连接的，还是由相邻场景构成的；
• 目标设备和可接受的最低硬件配置；
• 除滚动外，世界还需要具备多少交互性；
• 可用的模型、纹理、品牌素材、音频和文案；
• 初始加载和总下载预算。

如果用户提供了已批准的参考或可运行场景，请先检查，并将其中真实的几何体、材质、纹理、光照比例、摄像机参数和运动常数记录到台账中。不要用形容词取代测量得出的细节。

编写世界设定集，再开始编写代码

定义一套可复用的视觉规范：

• 尺度系统和单位约定；
• 轮廓语言和风格化程度；
• 调色板和各章节的强调色变化；
• 材质类别和磨损规则；
• 主光、补光、轮廓光、实用光和自发光的作用；
• 雾、霾、粒子、天气和后期处理；
• 字体排版、DOM 构图和近裁剪面前景规则；
• 摄像机、环境物体和交互的运动规范。

每个可见细节都必须服务于同一个世界。随机噪声、无关的纹理包、随意的粒子效果和一次性材质只会增加复杂度，无法增强整体协调性。

编写场景台账

大多数体验使用 4–8 个章节。将完整契约作为数据存储，而不是把阈值零散写在 CSS 和渲染循环中：

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"]
  }
];

为每个章节记录故事节拍、地标、摄像机终点、遮挡物、光照／雾效状态、激活动画片段、交互目标、DOM 节拍、前景处理、资源依赖项和响应式覆盖项。若某个章节仅在文案上有所不同，则予以拒绝。

构建一套持久的空间架构

只创建一次以下系统：

WebGL canvas
  worldRoot
    environment       sky, terrain, distant silhouettes
    architecture      persistent landmarks and paths
    chapterSets       local props grouped for culling and loading
    interactives      raycast targets and animation state
    atmosphere        fog volumes, particles, weather
    nearPlane3D       optional camera-relative depth accents

DOM above canvas
  semantic chapters  headings, copy, links, media, fallback order
  fixed interface    progress, chapter navigation, controls
  fixed cut-outs      optional alpha foregrounds at viewport edges

使用一个渲染器，通常也只使用一个场景。当透明效果、后期处理或交互隔离有此需要时，使用图层或渲染通道。不要为每个章节实例化一个渲染器，也不要在场景衔接处重建世界。

有意识地选择空间拓扑：

• 连续地理空间： 地标共享一个可导航空间；沉浸感最强，世界构建成本最高。
• 相连场景： 房间或岛屿通过隧道、门、雾带、地形褶皱或黑暗相连；最易于艺术指导和流式加载。
• 分层呈现： 同一地点随时间、尺度或状态变化；通过为材质、可见性和光照制作动画来实现，而不是移动到无关坐标。

使用遮挡、黑暗、浓密的大气、室内门槛或近景前景掠过，隐藏不可避免的不连续。绝不能让物体在开阔空间中明显瞬移。

为世界增添真实细节

几何体

• 先确立大型轮廓，再处理中型形态，最后添加小型点缀。密集散布的小道具无法弥补薄弱的轮廓。
• 让建筑边缘具有可信的厚度、倒角、接缝、封边、凹槽和接触点。薄如纸的屋顶和悬浮道具会立刻暴露虚假感。
• 使用模块化套件、实例化、合并静态网格和 LOD，而不是重复独特几何体。
• 通过精心设计的组合、缩放／旋转范围、贴花和材质变化来打破重复，而非依赖不受约束的随机性。
• 碰撞和射线检测代理应比渲染网格更简单。

材质和纹理

在有助于改善画面时，使用协调一致的 PBR 表面材质组合：

贴图	作用	常见问题
基础颜色	材质标识和大范围变化	烘焙的高光会与实时光照冲突
法线	细微的定向起伏	强度过高会显得像橡胶或箔纸
粗糙度	控制高光破碎和老化效果	数值平坦会让所有物体都像塑料
AO	让接触面和缝隙更有落地感	乘得过重会让接缝显脏
金属度	区分导体和电介质	到处使用灰色值会产生不自然的浑浊感
自发光	实用灯光、屏幕、符文	能替代光源，却不会照亮附近形体
Alpha／透射	植被、布料、玻璃、薄雾	排序、过度绘制和深度伪影

• 将颜色纹理设为 sRGB，并让法线、粗糙度、AO、金属度和数据纹理保持线性。
• 在摄像机可视范围内保持纹素密度一致。仅为确实会铺满画面的表面保留 2K–4K 贴图；大多数道具使用 512–1K 图集。
• 适当使用 KTX2／Basis 压缩、Meshopt／Draco 几何体压缩、图集、装饰条贴图、贴花以及烘焙 AO／光照。
• 仅为需要它的浅角度表面添加各向异性。将每张纹理都设为最大值会浪费带宽。
• 让磨损有因可循：暴露的边缘会被磨亮，凹处会积聚污垢，水会留下垂直痕迹或积水痕迹，路径会压低植被。均匀的污渍看起来像滤镜效果。
• 对植被，优先使用 Alpha 测试卡片或实例化低多边形组合，而不是透明混合平面。透明度过度绘制往往比几何体更耗费性能。

光照与氛围

• 从一个设定好的主光方向、克制的环境光／补光和实际发光源开始。只有在灯光能形成明显关系时才添加灯光。
• 尽可能烘焙静态反弹光和接触阴影。除非性能分析证明可以使用更多，否则将移动端的动态投影灯光控制在约 1–2 盏，桌面端控制在 2–4 盏。
• 用雾和薄雾区分纵深层次，而不只是让场景变暗。让焦点地标保持在对比度范围内。
• 调整发光几何体、辉光精灵、实际光照强度和泛光阈值，使灯具显得明亮，同时不让画面过曝。
• 在完成未处理画面的构图后再进行后期处理。泛光、暗角、颗粒、色差和景深不得掩盖材质或构图的不足。

在 references/world-bible.md 中的台账里记录详细的表面与灯光规划。

将原生滚动映射为确定性状态

只有在字体和关键媒体资源加载稳定后，才测量稳定的章节锚点。将 scrollY 转换为小数章节值，例如 2.35。

分别保留以下数值：

rig.target = progressFromScroll(scrollY);       // exact reproducible story state
rig.smooth = reduceMotion
  ? rig.target
  : damp(rig.smooth, rig.target, 5.2, dt);      // cinematic render state

导航、URL、无障碍、前景所有权和交互门控使用精确进度。摄像机和视觉插值仅使用平滑进度。同一滚动位置在正向、反向、快速跳转后以及重新加载后，都必须还原为相同状态。

使用 references/scroll-conductor.js 作为基准实现。以原生滚动作为事实来源；绝不要将滚轮增量累加到故事位置中。

将摄像机设计为电影摄影

在进行插值之前，先为桌面端和移动端构建每个章节终点的构图。

• 存储位置、目标、FOV、可选的滚转、镜头偏移和响应式覆盖设置。
• 使用 Catmull–Rom 曲线实现宽阔、连续的移动，使用分段插值实现刻意的转向。
• 检查曲线是否穿墙、穿过地面、目标翻转、速度突变或意外近距离掠过。
• 按章节进度而非曲线原始弧长进行参数化，让故事节奏保持在预期之内。
• 使用 scrollWeight 延长重要视图的停留时间；不要为了放慢某个章节而扭曲摄像机路径。
• 只有在基础构图有效后，才添加克制的指针视差。限制其幅度，并在需要精确控制的转场附近逐渐减弱。
• 对于高视口，设计拉远／FOV 覆盖设置，而不是接受随意的居中裁切。

摄像机运动必须展现新的空间关系：靠近、揭示、穿行、尺度变化、审视、地平线、离开。六次对准同一中心的推轨移动，并不等于六个场景。

使用同一导演器插值世界状态

每帧只解析一次相邻章节，并插值它们声明的值：

const { a, b, t } = segmentState(rig.smooth);
moon.scale.setScalar(lerp(a.world.moon, b.world.moon, t));
key.intensity = lerp(a.world.key, b.world.key, t);
scene.fog.density = lerp(a.world.fog, b.world.fog, t);

优先采用连续的物理变化：遮挡、材质混合、动画混合器权重、光照、雾、缩放和变换。替换资源时，只在被遮挡或大气密度较高的区间内交叉淡化，并在转场完成前保持两种状态都已加载。

添加交互，但不要与滚动争夺控制权

滚动负责大范围移动。指针、触控和键盘交互负责局部响应。

• 对命名的代理网格进行射线投射，而不是检测每个装饰性三角形。
• 为每个可交互对象定义 idle、hover、focused、active 和 unavailable 状态。
• 让悬停为灯光预热、改变材质响应、显示标签或触发短暂动画；不要让滚动相机偏离既定路径。
• 用户拖动控件或激活热点时，暂停或减弱指针视差。
• 根据精确的章节可见性和深度来控制交互；隐藏的对象不得捕获事件。
• 在文档顺序中，为每个必要的热点配备对应的 DOM 按钮或链接。提供可见的焦点状态，并让其状态与 3D 对象同步。
• 在触控设备上，如果误触的代价较高，则采用先轻触聚焦、再轻触激活的方式。DOM 代理中的点击目标至少为 44 CSS px。
• 将装饰性粒子轨迹和光标效果设为可选；适用时使其相对于相机定位，并在粗指针设备或启用减少动态效果时禁用。

实施前先编写交互矩阵；使用 references/world-bible.md 中的模式。

保持 DOM 内容语义清晰

将标题、正文、链接、控件和页脚保留在画布上方或旁边的真实 HTML 中。3D 世界营造空间；DOM 承载含义和备用顺序。

• 仅在有助于节奏时按词显示醒目标题；保留完整的无障碍标签。
• 将眉题、标题、正文、媒体、证明内容和 CTA 作为独立节拍依次显示。
• 在相机进行最大幅度移动时，保持阅读区块稳定。
• 可选择使用固定的 alpha 遮罩作为近裁剪面场景元素，而非将其作为每种设计的必要部分。使用时，在激活期间保持完全不透明，并在控制权变更后淡出或模糊。

渐进式加载

在加载完整旅程前，先确保首个创作帧完整呈现。

1. 内联或预加载关键外壳、相机、首个场景几何体、最小环境和备用海报。
2. 在下一个章节即将进入视野前加载它；提前预取一到两个章节。
3. 在主交互路径之外解码纹理，并且仅在章节所需资源就绪后显示该章节。
4. 如果 WebGL、模型或纹理加载失败，则继续显示经过设计的海报和语义化 DOM。
5. 根据所需资源大小或已完成的资源组报告有意义的进度，而不是使用随意设定的计时器。

不要把 40 MB 的世界藏在装饰性百分比后面。在资源清单中记录加载计划。

设定可测量的性能预算

从以下预算开始，然后在实际目标设备上进行性能分析：

预算	移动设备目标	桌面设备目标
DPR 上限	1.25–1.5	1.5–2
可见三角形数	150k–300k	500k–1.2m
绘制调用数	50–90	90–160
投射阴影的灯光数	1–2	2–4
同时混合的全屏图层数	2	3
关键初始传输量	3–6 MB	5–10 MB
稳定帧耗时	理想情况 ≤16.7 ms，备用情况 ≤25 ms	≤16.7 ms

这些只是起始范围，并非成功保证。测量 CPU、GPU、纹理内存、着色器编译、长任务和首个可交互帧。

• 遇到卡顿后，将 dt 限制在接近 1/30 秒。
• 当 document.hidden 为真或体验不可见时暂停。
• 使用质量调节器，优先降低 DPR 和可选效果，而不是删除创作中设计的地标。
• 仅在相关时渲染辅助相机、反射、布料模拟和耗费资源的粒子。
• 在拆卸时释放几何体、材质、纹理、渲染目标、观察器、事件、动画混合器和 RAF。

尊重动效、无障碍访问和故障处理

• 保留原生的可逆滚动；不要拦截滚轮，也不要强制使用自定义滚动条。
• 对于减少动态效果的设置，将摄像机／状态切换到最近的已组合章节，停止环境循环效果和交错／模糊效果，并保留完整、有序的 DOM 故事。
• 保留真实的标题层级、地标、链接、表单控件、可见焦点和可访问的页脚。
• WebGL 不可用时，提供组合海报或章节静帧。
• 当场景在文案背后变化时，保持对比度；使用精心设计的遮罩或局部对比度管理，不要用不透明层覆盖整个场景。

验证完整体验流程

遵循 references/quality-and-qa.md。至少验证以下内容：

• 在 1440×900、768×1024 和 390×844 尺寸下检查每个摄像机端点；
• 缓慢、快速、反向滚动，拖动滚动条，锚点导航，重新加载时停留在页面深处，以及在章节之间调整尺寸；
• 材质比例、UV、纹理色彩空间、粗糙度响应、接触贴合、阴影稳定性、雾深度和后期处理；
• 悬停、焦点、轻触、激活、章节门控，以及滚动离开后再返回时交互的恢复情况；
• 首次加载海报、渐进式章节加载、资源加载失败、上下文丢失、隐藏标签页恢复和拆除；
• 减少动态效果、WebGL 回退、键盘顺序、可读的 DOM、可访问的页脚和干净的控制台；
• 目标设备的帧耗时、绘制调用次数、三角形数量、纹理内存、传输大小和着色器编译情况。

使用 Codex 浏览器进行视觉和交互验证。构建／DOM 检查不能证明视觉效果正确。

交付

返回：

• 世界设定手册和美术指导常量；
• 章节、摄像机、材质／纹理、交互、资源和性能台账；
• 图层和场景图映射；
• 可运行的体验和本地运行时资源；
• 来自代表性章节的桌面端、平板端和移动端验证材料；
• 测得的性能和加载结果；
• 回退／减少动态效果的验证材料；
• 明确说明尚存的视觉、交互或设备适配问题。

除非用户明确要求修改参考本身，否则保持捆绑的 Kage 演示不变。