# Blueprint files

Build voxel items locally, save iterations and publish on behalf of your account.

Blueprints work through the same `eggox` CLI and `eggox mcp` as games. The editor does not have to be open. An agent can generate thousands of voxels with a local script and push the whole model in one request.

## Start with your account

```sh
eggox login
eggox blueprints
# A blank blueprint you took in Eggox (free; the CLI never creates them):
eggox blueprint pull bp_YOUR_ID chair.json
```

Login asks for **creator access**, including permanent publishing. It never spends Voxels: take blank blueprints (free) and publish iterations (priced in Voxels by size) in Eggox itself. Old games-only and editor tokens retain their original permissions. Run `eggox login` once more to grant the new access. Every request checks ownership. `--server https://staging.eggox.net` selects staging; files remember their server and cannot accidentally be pushed to another server.

## Generate and push

`chair.json` is an ordinary JSON file. Generate its palette and complete frames with any local program. Read the [frame contract](/studio/frames), or get machine-readable limits and a JSON schema without a network connection:

```sh
eggox blueprint schema > blueprint-schema.json
eggox blueprint check chair.json
eggox blueprint check chair.json --remote
eggox blueprint push chair.json
```

`check` validates locally without authentication. `--remote` also runs authoritative server checks without saving. `push` consumes the selected empty blueprint on its first save, turning it into prototype v1. Later pushes create new draft iterations in the same lineage. It writes the returned id and revision back to your file, so the next push continues from that iteration. Previous versions remain available:

```sh
eggox blueprint history bp_YOUR_ID
eggox blueprints
```

A push checks whether a newer iteration or publication exists. If the editor or another tool saved in the meantime, pull the latest id into a **different filename** and reconcile your changes. `--force` explicitly allows branching from an older file into the next iteration. Pull also refuses to overwrite an existing file without `--force`.

## One design, one blueprint

Every save checks each frame, whether it comes from the Studio or from `push`. If a frame is exactly the same as a frame of somebody else's blueprint (the visible outside and its colours; filling the inside differently does not count), the save is refused with `design_taken` and nothing is saved. The Studio names the frame. Frames unchanged from a starter character, and nearly empty frames, are free for everyone, and your own blueprint never clashes with itself, so pushing new iterations of your own lineage is fine.

## Finish in the editor

The bag refreshes when the CLI saves. Open the latest prototype from your bag, preview its rotations and animations, then make the final touches. Save before pulling back to disk. An already open editor keeps its unsaved canvas; close and reopen the latest prototype to load the CLI's version. The editor's Window menu includes a **CLI** panel with commands for the open item.

The old in-editor AI LINK is gone. Use `eggox mcp` for agents.

## Publish in Eggox, then mint

Pushing saves a draft, and drafts are free. Publishing permanently freezes an iteration so it can go out into the world, and it costs Voxels: 1 per 2,500 visible voxels across the iteration's distinct frames, at least 1 and at most 100. Tools never spend, so publishing happens in Eggox: open the design's Versions window, where the key shows the price. `POST /api/dev/blueprints/:id/publish` answers 402 `costs_voxels`.

Minting is free:

```sh
eggox blueprint mint pt_PUBLISHED_ID 25
```

The economy permits **one mint event per lineage**: the count (1 through 10,000,000) is the design's whole supply, for good. Iterating after minting still creates drafts, and each published iteration can be shown on the editions already out, but there is no second supply. The MCP tool `eggox_blueprint_mint` does the same for a user who asked, with the count they chose. Pushing a file never publishes or mints.

## HTTP integration

Use `Authorization: Bearer <creator-access-token>` on the main server, never the public docs host. JSON requests and responses:

| Method and route | Result |
| --- | --- |
| `GET /api/dev/blueprints` | Your empty blueprints and the latest item per owned lineage |
| `GET /api/dev/blueprints/:id` | Item, revision, latest id, and complete source with metadata |
| `GET /api/dev/blueprints/:id/history` | Owned lineage's iterations |
| `POST /api/dev/blueprints/check` | Validate an upload without saving |
| `PUT /api/dev/blueprints/:id` | Save an iteration, return item and revision |
| `POST /api/dev/blueprints/:id/publish` | 402 `costs_voxels`: publish in Eggox |
| `POST /api/dev/blueprints/:id/mint` | `{count}`: strike the editions of a published iteration, once (409 `not_published` / `already_minted`, 422 `bad_count`) |

`check` and `PUT` accept `display_name`, `item_type`, `voxel_source_b64` (schema-3 binary, below), and optional `collision_height`, `behavior`, `zones`, `skeleton`, `voxel_binding_b64`. `PUT` additionally requires the pulled `revision`, or explicit `force: true`. Omitted metadata is not a partial patch: send the full authoring document. Do not send the local sparse JSON frames directly to these routes; the CLI's exported `encodeBlueprint` compiles them.

There is no route that spends Voxels: publishing and buying happen in the game.

Responses use 401 for missing/expired/wrong-scope tokens, 404 for inaccessible ids, 409 for stale revisions, 422 for invalid content, and 429 for rate limits. A save refused by the design lock carries the error `design_taken`. A timed-out mutation may have completed: inspect `blueprints`, `history` or the bag before retrying a push or publish.