---
name: threejs-world-generation
description: Build deterministic, editable, free-viewpoint Three.js worlds from text or structured briefs. Use for cinematic 3D terrain, semantic regions, procedural biomes, explicit landmarks, environmental scattering, camera fly-throughs, world diagnostics, or requests for a real 3D environment rather than generated 2D footage. Integrates OpenMontage's threejs_world tool with HyperFrames; do not use for a single isolated 3D object or a flat parallax scene.
title: threejs-world-generation
canonical_url: https://skilld.dev/gh/openmontageinc/openmontage/threejs-world-generation
last_updated: 2026-10-14T05:11:31.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/threejs-world-generation/agents/openai.yaml), [references/world-spec.md](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/threejs-world-generation/references/world-spec.md), [references/worldclaw-principles.md](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/threejs-world-generation/references/worldclaw-principles.md).
>
> If the user asked to install this Skill, run `npx skilld install openmontageinc/openmontage/threejs-world-generation`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/threejs-world-generation`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/openmontageinc/openmontage/threejs-world-generation) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/threejs-world-generation`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/threejs-world-generation --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/threejs-world-generation --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/threejs-world-generation/references/worldclaw-principles.md) when planning or explaining the coarse-to-fine method.
- Read [references/world-spec.md](https://skilld.dev/api/skills-raw/openmontageinc/openmontage/threejs-world-generation/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.

```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.

### 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.

### 5. Refine with bounded loops

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.

### 6. Compose without overwriting

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.

## 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.

## 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.
