Assets

Author game-ready 3D assets for this game with Blender through the Metaloot CLI, then ship or stream them from the deployed game. Everything runs from the terminal.

Architecture:
- You, the local coding agent, are the asset author. Inspect the available Metaloot templates and starter library, write Blender Python (bpy), run it, inspect the artifacts, and iterate.
- Metaloot is the execution and delivery layer: it supplies versioned .blend templates, semantic starter assets, bounded headless Blender workers, validation, previews, inspection metadata, hosted GLBs, and downloadable .blend files.
- There is no remote prompt-to-3D agent. Do not expect a natural-language prompt to author arbitrary geometry.
- The older Tripo-backed "metaloot assets generate" text/image interface is legacy compatibility only and will be removed in a future release. Do not use it for new automation.

Prerequisites:
- The Metaloot CLI: npx @metaloot/cli or npm install -g @metaloot/cli
- A scoped API token with assets:read and assets:generate (ask the owner for one from https://metaloot.app/settings/api-tokens if it is not already available). Add assets:write when the workflow must publish, edit, rig, or animate assets. Export it as METALOOT_TOKEN:
  export METALOOT_TOKEN="mtl_api_…"
  metaloot whoami

Required discovery before authoring:
1. Check live worker capabilities:
   metaloot blender health
   metaloot blender capabilities
2. Read the versioned template registry:
   metaloot blender templates --json
3. Search the semantic starter library:
   metaloot blender library --json
   metaloot blender library material --json
   metaloot blender library dungeon --category Environment --json
4. Reuse an existing public asset when it already fits. Do not generate a near-duplicate unnecessarily.

Authoring:
1. Choose exactly one template. Prefer scene.blank.v1 when your script should own the complete scene. Use a specialized template only when its existing objects and structure are useful.
2. Choose only the starter assets the script will consume. Starters may be materials, models, base meshes, kitbash collections, Geometry Nodes groups, lighting rigs, HDRIs, or community packs. Preserve their provenance and license metadata.
3. Write a local Python file using bpy. The worker provides these globals:
   - bpy: the Blender Python API
   - request: the submitted job request
   - parameters: parsed --parameters and --param values
   - starter_assets: imported Blender data blocks keyed by semantic starter id
   - output_directory: the writable output directory
4. The script must work in Blender background mode without UI clicks or interactive editor state. Leave the scene ready for validation and export; Metaloot handles saving scene.blend, exporting model.glb, rendering preview.png, and writing inspection.json.
5. Submit the script:
   metaloot blender create \
     --name "Clockwork Gate" \
     --template scene.blank.v1 \
     --starter material.painted-metal \
     --script ./build_gate.py \
     --face-limit 8000 \
     --visibility private \
     --wait --json | sed -n '/^{/,$p' > asset.json
6. The JSON asset has id, slug, providerTaskId, status, modelUrl, and previewUrl. Keep both the Studio asset id and Blender job id.

Inspection and iteration:
- Inspect worker state and artifacts:
  metaloot blender status <job-id> --json
  metaloot blender artifacts <job-id> --json
  metaloot blender download <job-id> --artifact inspection.json --dir ./assets/inspection
  metaloot blender download <job-id> --artifact preview.png --dir ./assets/inspection
  metaloot blender download <job-id> --artifact scene.blend --dir ./assets/source
- Read inspection.json for object count, triangle count, armatures, bones, animations, starters, and warnings. Visually inspect preview.png. Do not treat a successful process exit as proof of asset quality.
- Revise an existing Blender-backed Studio asset with another bpy script:
  metaloot blender revise <asset-id> --name "Weathered Clockwork Gate" --script ./weather_gate.py --wait
- Worker-level actions are available for completed jobs:
  metaloot blender action <job-id> --action revise|render|inspect|export --script ./change.py --wait
- Jobs are asynchronous batch runs. Use --wait for a blocking agent loop, or jobs/status/cancel explicitly.

Animations (optional, for characters/creatures):
- Rig a finished model and retarget preset clips onto it:
  metaloot assets rig <asset-id> --presets idle,walk,run --wait
- Each finished preset is a hosted GLB (rigged model + that clip) at /api/assets/<id>/animation/<preset>; all presets share one skeleton, so load them into a single AnimationMixer and crossfade. In game code:
  import { getAsset, loadAnimationObjectUrl } from "@metaloot/sdk/assets";
  const asset = await getAsset("<asset-id>");        // has rigStatus + animations: { preset: { status, url } }
  const idleUrl = await loadAnimationObjectUrl(asset.id, "idle");

Managing and consuming Studio assets:
- metaloot assets list [--json]: your assets
- metaloot assets explore [--json]: public catalog
- metaloot assets files <pack-id> [--json]: hosted files in a curated pack
- metaloot assets publish <id> / unpublish <id>: change visibility
- metaloot assets update <id>: edit metadata

Getting the asset into the game:

A) Hosted asset (preferred when the asset is PUBLIC, i.e. generated with --visibility public): reference the hosted GLB by URL; no file ships with the game.
   - On a game deployed to <name>.metaloot.app, use the same-origin, edge-cached proxy (zero CORS concerns):
     /__metaloot/assets/<asset-id-or-slug>.glb
   - From any other origin, use the studio URL (public assets are served with Access-Control-Allow-Origin: *):
     https://studio.metaloot.app/api/assets/<asset-id-or-slug>/file
   - Or install @metaloot/sdk and use an engine adapter. Three.js integration handles the loader, scale, grounding, shadows, bounds, animation mixer, named actions, crossfades, and disposal:
     import { loadThreeAsset } from "@metaloot/sdk/three";
     const hero = await loadThreeAsset("<asset-id>", { scene, animations: "available", targetHeight: 1.8, shadows: true });
     hero.update(clock.getDelta());
     hero.play("run");
     Babylon.js games can use loadBabylonAsset from @metaloot/sdk/babylon.
   - Hosted URLs serve a game-ready LOD (~15k faces) automatically once the studio builds it, falling back to the full-res source until then. The SDK also exposes listAssets({ query, category, kind }) and getAsset(id) for discovering existing public assets before generating new ones.

B) Private/local development: pass the scoped token to the SDK only in local development. The assets:read scope can load public assets plus private assets owned by the token's user, with CORS from localhost:
   const hero = await loadThreeAsset("<private-asset-id>", { scene, token: import.meta.env.VITE_METALOOT_TOKEN });
   Never commit that environment file or include the token in a deployed browser bundle.

C) Download and ship (recommended for PRIVATE assets before production):
   1. Download the GLB into a folder that ships with the deployed site:
      metaloot assets download <asset-id> --dir public/assets
      The file is saved as <slug>.glb (slug comes from the asset JSON). For Vite games use public/ so the build copies it into dist/; for static games deployed with --dir ., any non-dot folder works.
   2. Load the GLB with the game's existing 3D stack, e.g. three.js:
      new GLTFLoader().load("/assets/<slug>.glb", (gltf) => scene.add(gltf.scene));

Deploying:
- metaloot deploy builds the game and publishes it at https://<name>.metaloot.app (auth and multiplayer are provisioned automatically). METALOOT_TOKEN authenticates this too.
- Every CLI command exits non-zero on failure (including --wait when a generation fails), so plain && chaining is safe.

Verify end-to-end: after deploy, fetch the asset URL the game uses — https://<name>.metaloot.app/__metaloot/assets/<asset-id>.glb for hosted assets, or https://<name>.metaloot.app/assets/<slug>.glb for downloaded ones — confirm it returns the model (Content-Type: model/gltf-binary), then confirm the game renders it.

Docs: https://metaloot.app/docs/assets and https://metaloot.app/docs/cli.