Threejs World Generation

Three.js World Generation

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.

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.

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.

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.

Workflow

1. Separate intent from completion

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.

2. Plan globally

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.

3. Build the terrain foundation

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.

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.

4. Inspect regionally

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.