Back to Details

threejs-world-generation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Three.js World Generation

Three.js世界生成

For production meshes and Blender assembly, also read 
3d-asset-generation
. Three.js remains the semantic interactive/blockout renderer; Blender is the production renderer when the brief calls for dense reference-grade scenery.
The production handoff must include target dimensions for imported assets, semantic scatter exclusion zones, terrain-following water/path geometry, landmark visibility policy, camera clearance, and global/regional/walk review frames. These are world-spec contracts, not manual Blender cleanup notes.
Create a persistent scene graph, not a sequence of unrelated 2D shots. Preserve the user's explicit constraints, infer missing construction details separately, establish the global terrain first, and refine selected regions without disturbing the world-wide spatial contract.
如需了解生产级网格和Blender装配相关内容，还请参阅
3d-asset-generation
。Three.js仍是语义化交互式/框架渲染器；当需求中要求高密度参考级场景时，Blender作为生产级渲染器使用。
生产交付必须包含导入资产的目标尺寸、语义散射排除区域、贴合地形的水域/路径几何结构、地标可见性规则、相机净空高度，以及全局/区域/步行视角的审核帧。这些是世界规格约定，而非手动Blender清理说明。
创建持久化场景图，而非一系列无关的2D镜头。保留用户明确的约束条件，单独推断缺失的构建细节，先建立全局地形，在不破坏全局空间约定的前提下细化选定区域。

Choose the fidelity tier explicitly

明确选择保真度层级

  • blockout
    : procedural primitives, vertex colors, semantic/layout validation, fast iteration. Never call this production-quality, reference-grade, or visually equivalent to WorldClaw.
  • production
    : licensed local GLTF/GLB catalogs, a minimum eight-model palette across four semantic categories, three PBR terrain layers, asset provenance, walk-level repetition review, and no primitive landmark fallback.
For a hero video or any reference showing populated textured environments, use 
production
. If its catalog/material/provider requirements cannot be met, stop at preflight or the asset gate. Do not render a blockout as the final deliverable.
  • blockout
    ：程序化图元、顶点颜色、语义/布局验证、快速迭代。切勿将此层级称为生产级、参考级或视觉效果等同于WorldClaw。
  • production
    ：授权本地GLTF/GLB资源库，四个语义类别中至少包含八种模型的调色板、三层PBR地形图层、资产来源、步行级重复审核，且无图元地标 fallback。
对于英雄视频或任何展示带纹理有人群环境的参考内容，请使用
production
层级。若无法满足其资源库/材质/供应商要求，请在预检或资产关卡处停止。切勿将框架渲染结果作为最终交付物。

Read first

必读内容

  • Read references/worldclaw-principles.md when planning or explaining the coarse-to-fine method.
  • Read references/world-spec.md before authoring a 
    world_spec
    or calling 
    threejs_world
    .
  • Read 
    hyperframes-core
    , 
    hyperframes-animation
    , and 
    hyperframes-animation/adapters/three.md
    before editing the emitted workspace.
  • Read 
    threejs-loaders
    , 
    threejs-materials
    , 
    threejs-textures
    , 
    threejs-lighting
    , and 
    threejs-postprocessing
    for production-tier work.
  • 当规划或解释从粗到细的方法时，请阅读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
    。

Route the request

请求路由

  • Use the 
    animation
    pipeline for design-led, explanatory, abstract, or music-led world films.
  • Use the 
    cinematic
    pipeline for trailer-like mood, dramatic reveals, or source-plus-world edits.
  • Choose HyperFrames when the deliverable is the code-native Three.js world. Choose Blender for reference-grade hero rendering and FFmpeg only to package Blender's numbered frames and approved audio. Record that choice at proposal; do not silently switch after approval.
  • Keep this as a capability inside existing pipelines. Do not create a new pipeline merely because a scene is 3D.
  • 对于设计主导、说明性、抽象或音乐主导的世界影片，请使用
    animation
    流水线。
  • 对于类似预告片的氛围、戏剧性展示或源素材+世界编辑，请使用
    cinematic
    流水线。
  • 当交付物为代码原生的Three.js世界时，选择HyperFrames。对于参考级英雄渲染选择Blender，仅使用FFmpeg打包Blender的编号帧和已批准的音频。在提案阶段记录该选择，获得批准后切勿擅自切换。
  • 将此功能保留在现有流水线中。切勿仅因为场景是3D就创建新流水线。

Workflow

工作流程

1. Separate intent from completion

1. 区分意图与实现

Record two lists before planning:
  • explicit_constraints
    : only facts the user supplied.
  • inferred_details
    : scale, region coverage, terrain operators, densities, palette refinements, and camera details added to make the world executable.
Never smuggle an inferred landmark, biome, or story beat into the explicit list.
规划前记录两个列表：
  • explicit_constraints
    ：仅包含用户提供的事实。
  • inferred_details
    ：为使世界可执行而添加的比例、区域覆盖范围、地形操作器、密度、调色板优化和相机细节。
切勿将推断出的地标、生物群系或故事节拍混入明确约束列表。

2. Plan globally

2. 全局规划

Author one shared 
world_spec
containing:
  • world scale, terrain resolution, elevation range, and seed;
  • semantic regions with normalized centers, radii, landform operators, palette, and scatter recipes;
  • atmosphere and lighting shared across all regions;
  • explicit landmarks with stable IDs and world-space placement;
  • a complete camera path with time, position, target, and field of view.
Prefer 3-7 regions. Each region must contribute a distinct silhouette, surface read, or functional role.
编写一个共享的
world_spec
，包含：
  • 世界比例、地形分辨率、海拔范围和种子；
  • 带归一化中心、半径、地形操作器、调色板和散射规则的语义区域；
  • 所有区域共享的大气和光照；
  • 带稳定ID和世界空间位置的明确地标；
  • 包含时间、位置、目标和视野的完整相机路径。
优先选择3-7个区域。每个区域必须提供独特的轮廓、表面呈现或功能角色。

3. Build the terrain foundation

3. 构建地形基础

For production, first call 
threejs_asset_catalog
to install rights-safe catalogs under 
projects/<id>/assets/3d/catalogs/<catalog-id>/
. Record source, license, archive hash, model inventory, and every selected model in the asset manifest. Then call 
threejs_world
with 
quality_tier: "production"
and the installed catalog paths.
python
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"],
})
Treat 
world.json
, 
world-spec.js
, 
world-runtime.js
, and 
world-report.json
as editable assets. Do not flatten them into a video until the assets gate is approved.
对于生产级内容，首先调用
threejs_asset_catalog
，在
projects/<id>/assets/3d/catalogs/<catalog-id>/
下安装版权安全的资源库。在资产清单中记录来源、许可证、归档哈希、模型清单以及每个选定的模型。然后调用
threejs_world
，设置
quality_tier: "production"
和已安装的资源库路径。
python
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. Inspect regionally

4. 区域检查

Build a second pass with 
render_mode: "semantic"
or 
"wireframe"
when spatial problems are hard to see in the cinematic material pass. Inspect snapshots from global, regional, and walk-level viewpoints.
Maintain an issue queue with stable subjects:
  • terrain transition or silhouette;
  • landmark scale, pose, or contact;
  • scatter density, slope rejection, or repetition;
  • material contrast and atmosphere;
  • camera clearance, clipping, or weak framing.
Fix only the affected region or object when possible. Preserve the seed, region IDs, camera times, and unrelated parameters.
当空间问题在影视级材质渲染中难以察觉时，使用
render_mode: "semantic"
或
"wireframe"
进行第二轮构建。从全局、区域和步行视角检查快照。
维护一个包含稳定主题的问题队列：
  • 地形过渡或轮廓；
  • 地标比例、姿态或接触情况；
  • 散射密度、坡度限制或重复情况；
  • 材质对比度和大气效果；
  • 相机净空高度、裁剪或构图薄弱问题。
尽可能仅修复受影响的区域或对象。保留种子、区域ID、相机时间和无关参数。

5. Refine with bounded loops

5. 有限循环细化

Run at most three render-guided refinement rounds:
  1. build the workspace;
  2. run the unified HyperFrames 
    check
    gate and snapshot representative times;
  3. inspect frames and update the issue queue;
  4. change the narrowest relevant spec fields;
  5. rebuild with the same seed and compare.
Stop when no substantial issue remains or the iteration budget is reached. Report residual limitations rather than disguising them with overlays.
最多运行三轮渲染引导的细化循环：
  1. 构建工作区；
  2. 运行统一的HyperFrames 
    check
    关卡并拍摄代表性时间点的快照；
  3. 检查帧并更新问题队列；
  4. 修改最窄范围的相关规格字段；
  5. 使用相同种子重新构建并对比。
当无重大问题剩余或达到迭代预算时停止。如实报告剩余限制，而非用叠加层掩盖。

6. Compose without overwriting

6. 合成时避免覆盖

For browser-native delivery, set 
render_runtime: "hyperframes"
and 
composition_mode: "atelier"
; 
video_compose
must preserve the authored workspace. For reference-grade video, render a Blender PNG sequence with 
resume: true
, then set 
render_runtime: "ffmpeg"
for packaging. Preserve the world spec and 
.blend
as the editable source of truth.
对于浏览器原生交付，设置
render_runtime: "hyperframes"
和
composition_mode: "atelier"
；
video_compose
必须保留已编写的工作区。对于参考级视频，使用
resume: true
渲染Blender PNG序列，然后设置
render_runtime: "ffmpeg"
进行打包。保留世界规格和
.blend
文件作为可编辑的事实来源。

Quality gates

质量关卡

  • Terrain is continuous and region boundaries blend without obvious seams.
  • Every landmark touches its support surface and remains inside world bounds.
  • Scatter respects region affinity, slope limits, and deterministic seed behavior.
  • Global, regional, and walk-level frames all read as the same continuous world.
  • Camera paths remain above terrain, avoid clipping, and provide at least one scale-establishing reveal.
  • World source remains editable after render: regions, landmarks, camera keys, and palette have stable IDs or fields.
  • HyperFrames 
    check
    and post-render review pass before delivery. Use the legacy 
    validate
    or 
    inspect
    operations only when supporting an older runtime.
  • Production beauty frames contain textured assets at foreground, midground, and background depths; no dominant object may read as an untextured box, cone, octahedron, or dodecahedron.
  • Production requires at least four semantic asset categories, eight distinct models, three PBR terrain layers, one regional composition review per camera-critical region, and explicit repetition/contact findings.
  • 地形连续，区域边界融合无明显接缝。
  • 每个地标都接触其支撑表面且保持在世界边界内。
  • 散射遵循区域关联性、坡度限制和确定性种子行为。
  • 全局、区域和步行视角的帧都呈现为同一个连续世界。
  • 相机路径保持在地形上方，避免裁剪，并至少提供一个确立比例的展示镜头。
  • 渲染后世界源仍可编辑：区域、地标、相机关键帧和调色板具有稳定ID或字段。
  • 交付前需通过HyperFrames 
    check
    和渲染后审核。仅在支持旧版运行时才使用遗留的
    validate
    或
    inspect
    操作。
  • 生产级美化帧包含前景、中景和背景深度的带纹理资产；任何主导对象不得呈现为无纹理的立方体、圆锥体、八面体或十二面体。
  • 生产级要求至少四个语义资产类别、八种不同模型、三层PBR地形图层、每个相机关键区域一次区域合成审核，以及明确的重复/接触检查结果。

Boundaries

边界限制

  • The production catalog path materially improves geometry and surface richness, but it still does not reproduce WorldClaw's GPT-Image-2, SAM3, SAM3D, Hunyuan3D, BlenderMCP, or four-H20 implementation.
  • Do not claim articulated assets, game physics, navigation meshes, or interaction logic unless another tool explicitly adds them.
  • Do not use unseeded randomness, wall-clock animation, remote models, or render-time asset fetches.
  • Do not delete the lower-level 
    threejs-*
    skills. They are the subsystem references used when extending this runtime.
  • 生产级资源库路径确实提升了几何和表面丰富度，但仍无法复现WorldClaw的GPT-Image-2、SAM3、SAM3D、Hunyuan3D、BlenderMCP或四H20实现。
  • 除非有其他工具明确添加，否则请勿声称有关节资产、游戏物理、导航网格或交互逻辑。
  • 请勿使用无种子随机性、基于时钟的动画、远程模型或渲染时资产获取。
  • 请勿删除底层的
    threejs-*
    技能。它们是扩展此运行时所需的子系统参考。