threejs-world-generation

어떤 스킬인가요?

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.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

interface:
  display_name: "Three.js World Generation"
  short_description: "Build semantic, editable cinematic 3D worlds"
  default_prompt: "Use $threejs-world-generation to turn this world brief into a deterministic, editable Three.js world and camera sequence."

# `threejs_world` specification

Use normalized region coordinates in `[-1, 1]`; the tool converts them to world space. Positions for landmarks and cameras are world-space `[x, y, z]` values.

## Minimal shape

```json
{
  "version": "1.0",
  "title": "The Luminous Divide",
  "seed": 2048,
  "explicit_constraints": ["a volcanic rift divides a living valley"],
  "inferred_details": ["three semantic regions", "dawn atmosphere"],
  "world": {
    "size": 120,
    "resolution": 160,
    "elevation_scale": 18,
    "water_level": -1.5
  },
  "atmosphere": {
    "sky_color": "#07111f",
    "fog_color": "#13263a",
    "fog_density": 0.009,
    "sun_color": "#ffd7a3",
    "sun_intensity": 3.2,
    "sun_position": [45, 70, 20]
  },
  "terrain_materials": [
    {
      "id": "mossy-ground",
      "regions": ["ember-rift"],
      "base_color": "assets/materials/mossy-ground/diffuse.jpg",
      "normal": "assets/materials/mossy-ground/normal.jpg",
      "roughness": "assets/materials/mossy-ground/roughness.jpg",
      "meters_per_repeat": 7
    }
  ],
  "asset_palette": [
    {
      "id": "rift-tree-a",
      "catalog_id": "kenney-nature-kit",
      "model_id": "tree-pine-a",
      "category": "tree",
      "region_id": "ember-rift",
      "count": 80,
      "scale_range": [0.8, 1.5]
    }
  ],
  "regions": [
    {
      "id": "ember-rift",
      "label": "Ember Rift",
      "center": [-0.35, 0.12],
      "radius": 0.58,
      "base_elevation": 0.3,
      "amplitude": 1.0,
      "frequency": 1.4,
      "landform": "ridge",
      "blend_width": 0.2,
      "color": "#5b271f",
      "accent_color": "#ff6b2c",
      "scatter": {"rock": 90, "crystal": 22, "tree": 0}
    }
  ],
  "landmarks": [
    {
      "id": "rift-gate",
      "type": "arch",
      "region_id": "ember-rift",
      "position": [-24, 0, 8],
      "scale": 5.5,
      "color": "#2a2020",
      "accent_color": "#ff7a35"
    }
  ],
  "camera_path": [
    {"time": 0, "position": [72, 42, 72], "target": [0, 3, 0], "fov": 46},
    {"time": 60, "position": [-54, 13, -32], "target": [-12, 4, 5], "fov": 40}
  ]
}
```

## Regions

Required: `id`, `center`, `radius`, `color`.

Useful fields:

- `label`: human-facing diagnostic label.
- `base_elevation`: normalized vertical offset before `elevation_scale`.
- `amplitude`: relief contribution.
- `frequency`: macro noise frequency.
- `landform`: `plain`, `peak`, `ridge`, `dune`, `terrace`, `basin`, or `canyon`.
- `blend_width`: softness of the semantic boundary.
- `accent_color`: used by semantic and environmental details.
- `scatter`: counts for `tree`, `rock`, and `crystal` prototypes.
- `slope_limit`: maximum accepted slope proxy for scattered instances.

Region weights are normalized at every terrain sample. The fallback region must still cover the full domain, so avoid tiny isolated regions with no broad neighbor.

## Landmarks

Supported procedural types: `monolith`, `arch`, `tower`, `ruin`, `crystal`, `settlement`, and `ring`.

Each landmark is placed at sampled terrain height. `position[1]` is an additional vertical offset, not an absolute Y coordinate. Keep IDs stable through refinement so review notes remain addressable.

## Camera path

- Provide at least two keys.
- First key time must be `0`; last key should match the requested duration.
- Keep keys ordered and inside the duration.
- The runtime interpolates position, target, and FOV with smoothstep easing.
- Add higher keys for regional and walk-level passes; do not attempt to encode cuts with teleporting adjacent keys.
- Keep the camera at least `2` world units above sampled terrain unless a deliberate ground skim is reviewed.

## Render modes

- `cinematic`: PBR vertex colors, fog, water, shadows, overlays.
- `semantic`: saturated region colors and labels for layout diagnosis.
- `wireframe`: terrain topology and explicit scene nodes for geometry diagnosis.

## Tool outputs

`operation: "build"` writes:

- `index.html`: HyperFrames composition root.
- `world.json`: normalized editable specification.
- `world-spec.js`: browser-loadable specification.
- `world-runtime.js`: deterministic Three.js scene construction.
- `world.css`: full-frame canvas and production overlays.
- `world-report.json`: validation, performance estimate, and warnings.
- `hyperframes.json`: local registry configuration.

Production builds additionally write `asset-catalog-index.json` and `asset-catalog.js`, and copy the selected catalogs into `assets/models/` so rendering never depends on a remote model fetch.

`operation: "validate"` performs specification checks without writing a workspace.

# WorldClaw principles adapted for OpenMontage

Source: [WorldClaw: Agentic 3D Open-World Generation at Scale](https://arxiv.org/html/2608.05248v1), Guo et al., arXiv:2608.05248v1 (2026).

WorldClaw's public repository currently contains the paper and assets, not the executable generation stack. OpenMontage therefore adopts the architectural ideas, not private code or model weights.

## Transferable architecture

1. **Intent extraction precedes completion.** Keep user-stated facts separate from inferred construction parameters.
2. **Shared structured intermediates coordinate agents.** A world spec carries regions, terrain, objects, appearance, and spatial relations across stages.
3. **Global constraints precede local detail.** Establish semantic layout, scale, terrain, atmosphere, and major relationships once.
4. **Terrain is the spatial contract.** Use the same region weights for height, palette, scattering, and later placement.
5. **Reusable environmental prototypes differ from functional landmarks.** Scatter rocks, vegetation, and crystals globally; place named structures explicitly.
6. **Local development is selective.** Spend detail and iteration on regions that matter to the camera path or delivery promise.
7. **Objects stay independent.** Stable IDs and transforms preserve editability and replacement.
8. **Placement is contact-aware.** Sample terrain height and slope, reject implausible candidates, align instances, and diagnose floating or penetration.
9. **Refinement is render-guided and bounded.** Use global, regional, walk, semantic, and wireframe views; change the narrowest responsible parameters.
10. **Executable representations improve reuse.** Code-native terrain, materials, placement, and camera paths remain parameterized and animatable.

## Local mapping

| WorldClaw concept | OpenMontage implementation |
|---|---|
| Structured scene specification | `world_spec` JSON and tool schema |
| Semantic layout map | Continuous normalized region-weight field |
| Region-aware height field | Weighted procedural landform operators |
| Terrain materials | Blockout: vertex colors. Production: catalogued PBR texture layers |
| Reusable terrain assets | Blockout: primitives. Production: licensed textured GLTF/GLB palettes |
| Regional objects | Stable explicit scene nodes; production forbids primitive landmark fallback |
| Blender refinement agents | HyperFrames snapshots plus agent issue queue |
| Free-viewpoint render | Deterministic Three.js camera path responding to `hf-seek` |
| Editable textured meshes | Editable code-native geometry, materials, regions, and transforms |

## Deliberate scope differences

- No single-view object reconstruction, segmentation, or generated PBR texture maps.
- No Blender or Unreal dependency in the current runnable path; this limits reconstruction and offline-render fidelity.
- No claim of photoreal asset diversity comparable to large generative 3D models.
- Stronger portability and determinism for browser-rendered OpenMontage video work.

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

# 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](references/worldclaw-principles.md) when planning or explaining the coarse-to-fine method.
- Read [references/world-spec.md](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.