Building over MCP
How the tools expect to be used. Your assistant discovers most of this from the server itself — this page is for you, so you can tell when a run is going well and steer when it is not.
Not connected yet? Start with Quick start: connect your AI. For the exact tool list, see the tool reference.
What the connection gives you
Your assistant keeps its own model, its own context and its own billing. Gamentic contributes the tools, the storage, the generation hardware, the validation and the Editor. Because the built-in web agent connects to the very same endpoint as an external client, everything is enforced identically — metering, plan gates, ownership checks, cover generation, convention validation. There is one policy path, not a privileged internal one.
The build workflow
The server hands the AI its own instructions, and a correct run follows this order.
-
Read the rules — free
get_conventionreturns the marker convention, your active module settings, the price list and your wallet state.get_skillreturns knowledge packs; mechanics and balance are mandatory, screens are mandatory for every game, and a matching genre blueprint should be read instead of inventing mechanics. -
Get the brief — free
new_game_briefreturns a form URL to hand you, thenwait_for_brieflong-polls for your answers. Several polling rounds are normal. -
Design the cast — costs images
concept_art, shown to you for approval before any code exists. -
Create the shell — free
create_gamewith a 60–120 linegame.html: the marker blocks, the harness, the canvas, and one script tag per planned file in dependency order. The response lists the files that do not exist yet. -
Fill in the files — free
write_game_filefor each one. When the last pending file lands, the server runs the real headless-browser test and reportsruntime: passedor the exact errors. -
Generate and wire the assets — costs credits
Art, sound, music. Each result carries a hint if the asset is not drawn anywhere yet.
-
Self-check — free
list_assetsto clear any undrawn art or unplayed audio,playtest_screenshotto look at the result, then hand over an editor link.
Why shell-first matters
Writing the whole game as one HTML string and splitting it afterwards is a rewrite of code you already paid for. Worse, a single-file game hits a ceiling: every later change pushes the entire source through the context window, so the AI starts breaking things it can no longer see. Built shell-first, each change reads and writes a couple of kilobytes instead of a couple of hundred.
A genuine one-screen toy — well under 1,500 lines, no levels, one enemy type — can go in as
a single create_game. Anything with multiple levels, multiple enemy types or a story mode
should not.
A shell whose files are missing is a white screen. The runtime check is skipped for a shell with unwritten files, so nothing is verified until the last one lands. If your assistant announces the game is ready while files are still pending, that claim has not been tested.
Editing: pick the tool by the size of the change
This is the single biggest determinant of how fast and how cheap iteration is on an existing game.
| Change | Path |
|---|---|
| A value only | bake_config |
Behaviour inside one src/ file | list_game_files → read_game_file → edit_game_file — by far the cheapest |
| Something in the shell (markers, script order, boot) | search_game_source → edit_game |
| A new system, character or scene | write_game_file, then edit_game to add its script tag |
| Story or dialogue content | read_data / write_data — never find-and-replace |
| Full rewrite | update_game, or chunked upload |
Watch for get_game being used as a search tool. Once assets exist, a game is
megabytes. Pulling the whole thing to find one function is slow and pushes everything else out of
context. list_game_files and search_game_source exist precisely so that
never has to happen.
Protections you will run into
Several server-side rules exist because of real incidents. They will occasionally reject something your assistant tried, and the rejection is usually correct.
| Rule | What it does |
|---|---|
| Asset-loss guard | Any write that would shrink the set of images, audio or models is refused unless the caller explicitly opts in. Introduced after an edit reduced 26 assets to one. |
| Server assets win | When the AI submits a whole-file rewrite from a stale copy, the asset blocks are merged key by key with the server's current version winning, and the response says which were preserved — so the model does not try to “fix” them back. |
| Re-read before injecting | Generation takes seconds to minutes. Tools re-read the game immediately before injecting, so a slow job cannot overwrite what you changed meanwhile. |
| All-or-nothing edits | An edit is applied, validated, syntax-checked and asset-checked before it is stored. Any failure means nothing changed. |
| Runtime gate | Submissions are run in a real browser. Broken games are rejected, not stored and handed over. |
Async jobs
Music, sprite animation, animated CG, Live2D rigs and all 3D work run as background jobs. The tool
returns a task id immediately; check_job (also registered as
check_model_3d) polls it. Interrupted sprite jobs resume from saved state rather than
re-spending video credits.
You will see your assistant start several jobs and poll them together. That is correct — it should not block on one.
Budgets
Give a budget as a design input, not a spend meter: “make me a 5,000-credit game”.
With Budget mode wired in, a good run prices the scope, tells you what you get and what you do not,
and asks before spending. budget_status then reports the ledger for that game grouped by
tool, plus recent spend not yet bound to any game, plus a pace verdict.
Concept art generated before the game exists cannot be attributed to it. Design-first passes
happen before create_game, so that spend is invisible to budget_status. A
careful assistant counts it in the plan and passes the game id to concept_art once the
game exists. If a run reports “5,000 of 5,000 spent”, the true figure may be higher.
Wallets
get_convention reports which wallet is active and what every wallet holds. Generation
bills only the active one, and stops rather than falling through to another. If a tool reports it ran
out, your assistant should relay that and let you decide — switching wallets with
set_active_wallet is your call, not its own.
The editor request loop
This is the loop that makes an external assistant a first-class citizen of the Editor. When you circle something in the running game and describe it, that becomes a request your assistant can pick up.
| Tool | Model |
|---|---|
read_edit_requests | Pull. Returns the text, the action, the entity, the current config and up to two screenshots as real images. |
wait_for_edit_request | Push. Long-polls for about 50 seconds with a heartbeat, so the Editor can show “an AI is listening”. |
finish_edit_request | Required when done. Your note appears live in the Editor. |
Self-improvement
With the Self-learning module on, an assistant calls submit_feedback at the end of a
build with one concrete, reusable lesson — a gotcha and its fix, a number that worked, an API
quirk. Those notes are appended to the matching get_skill response for later builds, so
the engine improves with use. list_learned shows what has accumulated.
Unstable connections
One giant create_game is the most vulnerable call there is — if it drops, the whole
game is regenerated. With Unstable connection mode on, uploads go through
begin_game_upload, append_game_html and commit_game in numbered
chunks. Re-sending the same chunk after a drop is safe, and the server says which chunk it expects if
one is skipped.
Chunked upload is for initial creation and full rewrites only. Everyday changes use the edit tools.
Steering a run
| Say this | To get |
|---|---|
| “Read the convention and the relevant skills first.” | Mechanics taken from a proven blueprint rather than invented. Free, and the highest-leverage instruction there is. |
| “Price it before you spend.” | A scope and a subtotal you can approve or cut. |
| “Build shell-first, one file per entity.” | A game that stays cheap to change. |
| “Use character sprite for every extra pose.” | One character throughout, instead of a new person per image. |
“Check list_assets before you tell me it is done.” | No paid-for art sitting invisible in the game. |
| “Don't touch the numbers — expose them.” | Tunables in the config and the schema, so you can adjust them yourself for free. |