AGENT SKILL

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.

License 许可
MIT
最近更新
2026-11-11
Stars
★ 3
Forks
0

01 前言 Front Matter

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.

02 资源文件 2

03 SKILL.md 正文

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.

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.

04 同仓库更多 Skills

mdnaimul22
mdnaimul22/human-skills

system-lifecycle-designer

Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.

★ 3
mdnaimul22
mdnaimul22/human-skills

style-sampling

Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video.

★ 3
mdnaimul22
mdnaimul22/human-skills

reverse-any-video

Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.

★ 3
mdnaimul22
mdnaimul22/human-skills

typescript-patterns

TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.

★ 3
mdnaimul22
mdnaimul22/human-skills

test-collaboration

Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.

★ 3
mdnaimul22
mdnaimul22/human-skills

story-lifecycle

Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.

★ 3