threejs-world-generation

Three.js 世界生成

对于生产级网格和 Blender 组装，也请阅读 3d-asset-generation。 Three.js 仍是语义化交互式/白模渲染器；当需求要求打造参考级的高密度场景时，Blender 是生产级渲染器。

生产交接内容必须包括导入资源的目标尺寸、语义化散布排除区、贴合地形的水体/路径几何、地标可见性策略、摄像机净空，以及全局/区域/步行视角审查帧。这些是世界规格契约，不是手动清理 Blender 的备注。

创建持久化场景图，而不是一系列互不相关的 2D 镜头。保留用户明确提出的约束，单独推断缺失的构建细节，先建立全局地形，再完善选定区域，同时不破坏整个世界的空间契约。

明确选择保真度等级

• blockout：程序化基本体、顶点颜色、语义/布局验证、快速迭代。绝不可称为生产级、参考级，或在视觉上等同于 WorldClaw。
• production：获授权的本地 GLTF/GLB 资源库，至少包含 8 个模型，覆盖 4 个语义类别，三层 PBR 地形图层、资源来源信息、步行视角重复度审查，且不得以基本体替代地标。

对于英雄视频或任何展示丰富纹理环境的参考图，请使用 production。如果无法满足其资源库/材质/提供方要求，请在预检或资源关卡处停止。不要将白模作为最终交付物渲染。

首先阅读

• 规划或说明由粗到精的方法时，请阅读 references/worldclaw-principles.md。
• 编写 world_spec 或调用 threejs_world 前，请阅读 references/world-spec.md。
• 编辑输出的工作区前，请阅读 hyperframes-core、hyperframes-animation 和 hyperframes-animation/adapters/three.md。
• 进行生产级工作时，请阅读 threejs-loaders、threejs-materials、threejs-textures、threejs-lighting 和 threejs-postprocessing。

路由请求

• 对于以设计、讲解、抽象或音乐为主导的世界影片，使用 animation 流程。
• 对于预告片风格、情绪戏剧化、揭示感强烈或源素材与世界场景剪辑类内容，使用 cinematic 流程。
• 如果交付物是代码原生的 Three.js 世界，请选择 HyperFrames。对于参考级英雄场景渲染，请选择 Blender；FFmpeg 仅用于打包 Blender 的编号帧和获批音频。在提案阶段记录此选择；获批后不得擅自切换。
• 将其作为现有流程中的一项能力。不要仅仅因为场景是 3D 就创建新流程。

工作流

1. 区分意图与补全内容

规划前记录两个列表：

• explicit_constraints：仅包含用户提供的事实。
• inferred_details：为使世界可执行而补充的比例、区域覆盖范围、地形算子、密度、调色板优化和摄像机细节。

绝不要把推断出的地标、生物群系或故事节拍混入明确约束列表。

2. 全局规划

编写一个共享的 world_spec，其中包含：

• 世界比例、地形分辨率、高程范围和种子；
• 语义区域及其归一化中心、半径、地貌算子、调色板和散布配方；
• 所有区域共享的大气效果和照明；
• 具有稳定 ID 和世界空间位置的明确地标；
• 完整的摄像机路径，包括时间、位置、目标和视场角。

优先设置 3-7 个区域。每个区域都必须展现独特的轮廓、表面观感或功能角色。

3. 构建地形基础

用于生产时，先调用 threejs_asset_catalog，将权利合规的资源目录安装到 projects/<id>/assets/3d/catalogs/<catalog-id>/。在资源清单中记录来源、许可证、归档哈希、模型清单以及每个选用的模型。然后调用 threejs_world，并传入 quality_tier: "production" 和已安装的资源目录路径。

from tools.graphics.threejs_world import ThreeJSWorld

result = ThreeJSWorld().execute({
    "operation": "build",
    "world_spec": world_spec,
    "output_path": "projects/<id>/hyperframes",
    "duration_seconds": 60,
    "render_mode": "cinematic",
    "quality_tier": "production",
    "asset_catalog_paths": ["projects/<id>/assets/3d/catalogs/kenney-nature-kit"],
})

将 world.json、world-spec.js、world-runtime.js 和 world-report.json 视为可编辑资源。在资源验收门通过前，不要将它们压平为视频。

4. 分区域检查

如果在电影级材质渲染中难以发现空间问题，请使用 render_mode: "semantic" 或 "wireframe" 构建第二轮渲染。从全局、区域和步行视角检查快照。

维护一个包含稳定主题的待处理问题队列：

• 地形过渡或轮廓；
• 地标比例、姿态或接触；
• 散布密度、坡度筛选或重复；
• 材质对比度和氛围；
• 摄像机净空、裁切或构图不足。

尽可能只修复受影响的区域或对象。保留种子、区域 ID、摄像机时间和无关参数。

5. 通过有界循环进行优化

最多执行三轮渲染引导的优化：

1. 构建工作区；
2. 运行统一的 HyperFrames check 验收门，并为有代表性的时间点生成快照；
3. 检查帧并更新待处理问题队列；
4. 修改范围最小且相关的规范字段；
5. 使用相同种子重新构建并进行比较。

当不再存在重大问题或达到迭代预算时停止。应报告剩余限制，而不是用叠加层掩盖它们。

6. 合成时不覆盖内容

用于浏览器原生交付时，设置 render_runtime: "hyperframes" 和 composition_mode: "atelier"；video_compose 必须保留已创作的工作区。用于参考级视频时，使用 resume: true 渲染 Blender PNG 序列，然后将 render_runtime: "ffmpeg" 设为用于打包。保留世界规范和 .blend，作为可编辑的事实来源。

质量验收门

• 地形连续，区域边界融合自然，没有明显接缝。
• 每个地标都与其支撑表面接触，并保持在世界边界内。
• 散布遵循区域亲和性、坡度限制和确定性种子行为。
• 全局、区域和步行视角的画面都呈现为同一个连续世界。
• 摄像机路径始终高于地形、避免裁切，并至少包含一个能确立尺度的揭示镜头。
• 渲染后世界源文件仍可编辑：区域、地标、摄像机关键帧和调色板都有稳定 ID 或字段。
• 交付前须通过 HyperFrames check 和渲染后审查。仅在支持较旧运行时时使用旧版 validate 或 inspect 操作。
• 生产级精美帧的前景、中景和背景都包含带纹理的资源；任何主要对象都不能看起来像未贴图的盒子、圆锥体、八面体或十二面体。
• 生产要求至少包含四种语义资源类别、八个不同模型、三层 PBR 地形、每个对摄像机至关重要的区域各进行一次区域构图审查，并明确记录重复和接触情况。

适用范围

• 生产级资源目录路径能显著改善几何形体和表面丰富度，但仍无法复现 WorldClaw 的 GPT-Image-2、SAM3、SAM3D、Hunyuan3D、BlenderMCP 或四张 H20 的实现。
• 除非其他工具明确添加相关功能，否则不要声称支持可动资源、游戏物理、导航网格或交互逻辑。
• 不要使用非确定性随机数、挂钟动画、远程模型或渲染时获取资源。
• 不要删除较低层级的 threejs-* 技能。扩展此运行时时，应将它们用作子系统参考。