Blueprint files

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

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, or get machine-readable limits and a JSON schema without a network connection:

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:

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:

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.