Tooling

Building with Agents

The entire Metaloot loop — generate assets, write the game, deploy, add auth and multiplayer — runs non-interactively, so a coding agent can do all of it. This page is the setup that makes agent runs smooth, and a prompt-sized summary you can paste into one.

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 start paid generation jobs. Details in API Tokens.

Machine-Readable Everything#

  • --json on assets generate, list, explore, files, status, rig prints a JSON object last on stdout, after the human-readable lines.
  • All commands exit non-zero on failure, so shell chains (&&) short-circuit correctly.
  • --wait turns async generation and rigging into blocking calls — no polling loop to write.
# A full agent-friendly pipeline:
metaloot assets generate --prompt "low-poly treasure chest" \
  --name "Treasure Chest" --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

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: `metaloot assets generate --prompt "…" --name "…" --visibility public
--wait --json` creates a hosted GLB (JSON printed last on stdout). Load it 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`.

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.