Tooling

Building with Agents

The entire Metaloot loop — author assets through Blender, write the game, deploy, add auth and multiplayer — runs non-interactively, so a coding agent can do all of it. For 3D work, the local agent is the creative operator: it writes bpy scripts while Metaloot supplies templates, starter assets, and bounded headless Blender execution.

Setup: a Scoped Token#

Give the agent its own credentials instead of your interactive login. Create a token with the Game builder preset (assets:read, games:read, games:write, deployments:write) at metaloot.app/settings/api-tokens and export it in the agent's environment:

export METALOOT_TOKEN="mtl_api_…"

Every metaloot command picks it up — no browser, no stored state. Add assets:generate to the token only if the agent should submit Blender or legacy provider jobs. Details in API Tokens.

Machine-Readable Everything#

--json on blender templates, library, create, status and the asset-management commands prints machine-readable state for discovery and orchestration.
All commands exit non-zero on failure, so shell chains (&&) short-circuit correctly.
--wait turns asynchronous Blender jobs and rigging into blocking calls — no polling loop to write.

# A full agent-friendly pipeline:
metaloot blender templates --json
metaloot blender library material --json

# The agent authors build_chest.py with bpy, then submits it:
metaloot blender create --name "Treasure Chest" \
  --template scene.blank.v1 \
  --starter material.painted-metal \
  --script ./build_chest.py \
  --visibility public --wait --json | sed -n '/^{/,$p' > asset.json

ASSET_ID=$(node -p "JSON.parse(require('fs').readFileSync('asset.json','utf8')).asset.id")

metaloot deploy --dir dist   # exit code tells the agent whether it shipped

The older metaloot assets generate text/image interface is backed by Tripo. It is retained for compatibility, is not recommended for new agent workflows, and will be removed in a future release.

Pre-Filled Integration Prompts#

Published games get an integration prompt in their settings page (/game/<id>/settings) with the real client ID and redirect URI baked in — paste it into your agent and it wires up @metaloot/auth end to end. Generic versions with placeholder values live on the Authentication, Multiplayer, and Assets pages — look for the "Agent Instructions" card with the copy button.

A Summary to Paste into Your Agent#

You are building a browser game on the Metaloot platform.

Environment: METALOOT_TOKEN is set (scoped API token). Node 20+.

Deploy: `npx @metaloot/cli deploy --dir <build-folder>` publishes the folder
(must contain index.html) to https://<slug>.metaloot.app. It writes
metaloot.json (commit it). Re-deploying is atomic and takes seconds.

Auth: on the deployed domain, `await window.metaloot.session` returns
{ signedIn, user } — user.id is the stable player id. window.metaloot.signIn()
starts sign-in. Suppress the injected widget with
<meta name="metaloot-auth-widget" content="off" />.

Multiplayer: import { joinRoom } from "/__metaloot/multiplayer.js";
const room = await joinRoom("lobby"); room.on("join"|"leave"|"message"|"state", …);
room.send(data); room.setState(key, value). Limits: 32 players/room,
32 KB/message. joinRoom throws MetalootAuthRequiredError when signed out —
call error.signIn().

Assets: prefer the agent-driven Blender workflow. Discover available starting
points with `metaloot blender templates --json` and
`metaloot blender library --json`. Write a local bpy script, then run:
`metaloot blender create --name "…" --template scene.blank.v1
--starter <semantic-id> --script ./asset.py --visibility public --wait --json`.
Metaloot runs the script on a bounded headless Blender worker and returns a
hosted GLB, preview, inspection.json, and scene.blend. There is no remote
prompt-to-3D agent; the local coding agent authors the asset. Load the result
with `npm i @metaloot/sdk`:
  import { loadAssetObjectUrl } from "@metaloot/sdk";
  const url = await loadAssetObjectUrl("<asset-id>");
Or download files: `metaloot assets download <id> --dir public/assets`.
The legacy Tripo-backed `metaloot assets generate` interface is planned for
removal; do not use it for new automation.

Docs index for browsing: https://www.metaloot.app/docs

These docs pages themselves are written to be agent-readable — an agent pointed at https://www.metaloot.app/docs can navigate every page from the sidebar links.