/worldlabs

name: worldlabs
description: Generate photorealistic 3D worlds and environments with the World Labs Marble API — Gaussian Splat scenes from text prompts or reference images. Use when the user says "generate a 3D world", "create an environment", "make a 3D scene", or "use World Labs". Requires WLT_API_KEY environment variable.
argument-hint: "[prompt or 'image path/url']"
license: MIT
compatibility: Requires WLT_API_KEY environment variable and internet access for World Labs API calls.
metadata:
  author: OpusGameLabs
  version: 1.4.0
  tags: [game, 3d, worldlabs, environment, gaussian-splat, generation, spark, spark-2]

World Labs — 3D World/Environment Generation

Generate photorealistic 3D environments from text prompts or images using the World Labs Marble API. Outputs Gaussian Splat scenes (SPZ) rendered via SparkJS in Three.js, plus collider meshes (GLB) for physics.

When to Use

• **Environment/level generation** — create entire 3D worlds (rooms, landscapes, buildings) from reference images or text
• **Complementary to Meshy AI** — Meshy generates individual models/characters; World Labs generates the environments they exist in
• **Photorealistic scenes** — Gaussian Splats produce photorealistic quality vs mesh-based environments

Input Priority

**Image-first** — always prefer image input over text:

1. **Image mode (default)** — if the user has a reference image, concept art, screenshot, or photo, use `--mode image`. This produces the most faithful results because the AI can match the exact visual style, layout, lighting, and mood. 2. **Text mode (fallback)** — only use `--mode text` when no reference image is available. The API auto-expands short prompts into rich scene descriptions, but results are less predictable than image-driven generation.

When the game-creator pipeline runs, **ask the user for a reference image first**:

> I can generate a photorealistic 3D environment for your game using World Labs. > Do you have a reference image (photo, concept art, screenshot) for the environment? > - **Yes** → provide the file path or URL > - **No** → I'll generate from a text description instead

Tech Stack

| Component | Technology | |-----------|-----------| | API | World Labs Marble API (`https://api.worldlabs.ai/marble/v1`) | | Auth | `WLT-Api-Key` header | | Output: Visual | Gaussian Splat (`.spz`) — 100k, 500k, full resolution tiers | | Output: Physics | Collider mesh (`.glb`) — for collision detection | | Output: Skybox | Panorama image (`.jpg`/`.png`) | | Browser Renderer | SparkJS 2.x (`@sparkjsdev/spark`) — `SparkRenderer` + `SplatMesh`, Three.js compatible | | CLI Script | `scripts/worldlabs-generate.mjs` (zero dependencies) |

Environment Variable

Before prompting the user, check if the key already exists: `test -f .env && grep -q '^WORLDLABS_API_KEY=.' .env && echo "found"` If found, export it with `set -a; . .env; set +a` and skip the prompt.

If not set, ask the user:

> I'll generate a photorealistic 3D environment with World Labs. You can get a free API key: > 1. Sign up at https://platform.worldlabs.ai > 2. Go to API Keys > 3. Create a new key > > Paste your key below like: `WORLDLABS_API_KEY=your-key-here` > (It will be saved to .env and redacted from this conversation automatically.) > > Or type "skip" to use basic geometry instead.

CLI Script Usage

# Text to 3D world
WORLDLABS_API_KEY=<key> node scripts/worldlabs-generate.mjs \
  --mode text --prompt "a medieval tavern with wooden beams and a roaring fireplace" \
  --output public/assets/worlds/ --slug tavern

# Image to 3D world (local file or URL)
WORLDLABS_API_KEY=<key> node scripts/worldlabs-generate.mjs \
  --mode image --image ./reference-photo.jpg \
  --output public/assets/worlds/ --slug my-world

# Check generation status
WORLDLABS_API_KEY=<key> node scripts/worldlabs-generate.mjs \
  --mode status --operation-id <op-id>

# Download assets from existing world
WORLDLABS_API_KEY=<key> node scripts/worldlabs-generate.mjs \
  --mode get --world-id <id> --output public/assets/worlds/ --slug my-world

# List your worlds
WORLDLABS_API_KEY=<key> node scripts/worldlabs-generate.mjs --mode list

Output Files

public/assets/worlds/
  tavern.spz              # Gaussian Splat (full resolution)
  tavern-500k.spz         # Gaussian Splat (500k, medium quality)
  tavern-100k.spz         # Gaussian Splat (100k, lightweight/mobile)
  tavern-collider.glb     # Collider mesh for physics (GLB)
  tavern-pano.jpg         # Panorama image (skybox)
  tavern.meta.json        # Metadata: world ID, prompt, timestamps, asset URLs

Integration with Three.js Games

**Tested & working** — see `examples/worldlabs-arcade/` for a complete runnable demo.

Install SparkJS 2.0

npm install @sparkjsdev/spark@^2.0.0

**Package**: `@sparkjsdev/spark` — high-performance Gaussian Splat renderer for Three.js. Pin to `^2.0.0`; the 0.x line has a different API (no `SparkRenderer`) and will not match the snippets below. Supports SPZ, PLY, SOGS, KSPLAT, SPLAT formats (auto-detected by extension).

**Three.js peer version**: Spark 2.0 declares `three@^0.180.0` as its peer dependency. Three treats every 0.x minor as potentially breaking, so `three@^0.181` or newer triggers an `ERESOLVE` peer-dep error on `npm install`. Pin `three` to `^0.180.0` in your project's `package.json` — this is what the `threejs-3d` template and the `worldlabs-arcade` example both use.

**No bundler?** Use the CDN importmap instead of npm:

<script type="importmap">{
  "imports": {
    "three": "https://cdnjs.cloudflare.com/ajax/libs/three.js/0.180.0/three.module.js",
    "@sparkjsdev/spark": "https://sparkjs.dev/releases/spark/2.0.0/spark.module.js"
  }
}</script>

**WebGLRenderer config**: Create it with `antialias: false`. Spark's splat shader provides its own anti-aliasing, and enabling MSAA on top wastes GPU for no visual gain:

const renderer = new THREE.WebGLRenderer({ antialias: