Troubleshooting

The failures that come up most, and what actually causes them. Most of these look like platform bugs and are not — they are a specific thing the game code is doing.

The game

Blank or white screen

Almost always one of three things, in order of likelihood:

  1. A src/ file was never written. The shell references script files that do not exist, so nothing boots. The runtime check is skipped for a shell with pending files, so this can slip through if the AI announced success early. Ask it to list the game's files and write the missing ones.
  2. Load order. A marker block or the harness ended up below the script tags, so GAME_CONFIG is undefined when the code runs. Everything must sit above the script tags.
  3. A script path with a leading slash — src="/src/core/engine.js" resolves to the site root and 404s.

Ask your AI to run a validation or a playtest screenshot: both return the real console errors rather than a guess.

Generated art never appears

⚠

Generating art loads it; it appears only if the code draws it. If the game still draws a placeholder rectangle for that thing, you paid for an image that is loaded and invisible — and a screenshot still looks like a normal game, which is why this goes unnoticed.

Ask the AI to list the game's assets and clear every hint it reports. The platform pushes this list back automatically at delivery time, so a well-behaved run should never hand you an undrawn asset.

A second cause: a defensive fallback on a marker line. If game.html contains window.GAME_ASSETS = window.GAME_ASSETS || {}; // __GI_ASSETS__, the server cannot rewrite that block at all and every subsequent generation silently fails to land. It must be the bare literal window.GAME_ASSETS = {}; // __GI_ASSETS__.

Art appears, but everything is a different size

The generator returns different amounts of empty padding each time — the same 512×512 canvas might be 63% fox or 41% bear. Drawing those raw makes one 1.5× the other. The game should draw through the platform's sprite helper, which measures actual content bounds and fits them to a design box. Ask the AI to switch to it.

The game is silent even though it has music

Three causes, and regenerating the audio fixes none of them:

  1. The code never plays it. Generation only puts the track in the audio table.
  2. Playback started before any user interaction. Browsers block that. It has to start on the first click or key press.
  3. A new audio object is created every frame, which clips the sound and eats memory.
⚠

Do not ask for the sound to be regenerated. It will not play any better, and it overwrites a take you already approved — at full price.

Art pops in after the loading bar finishes

The game hid its loading screen on the page load event, which fires long before the images have decoded. It should wait for the platform's assets-ready signal instead. There is a real progress count available, so the bar can show actual progress rather than an animation.

Background looks squashed

The image is being stretched to the canvas with independent X and Y scaling. It needs uniform scaling with a centre crop. Round faces going oval is the giveaway.

The Editor

The Inspector is empty or has only a couple of controls

The AI did not expose those values — they are still hardcoded in the game logic. Ask it to move them into the config and extend the schema. It is a free, code-only change, and every difficulty number in particular belongs there.

A slider moves but nothing happens

The game copied the config into local variables at startup instead of reading it every frame. Some values also need derived state rebuilt when they change — changing an enemy count does nothing unless the enemy pool is rebuilt. Both are one-line fixes for the AI.

Save says someone else already saved

Two people edited the same game. You get a banner that will not go away by itself, offering: reload their version, force yours over the top — it names the version that discards — or decide later. Nothing is merged automatically, because a tuned config is a set of values balanced against each other. Check the presence indicator before a long tuning session.

My asset swap disappeared

Swapped assets are staged and previewed locally, and only written into the game on Save. Leaving without saving discards them, exactly like slider changes.

The publish button does not seem to do anything

It did. Publishing opens a real browser and interaction-tests the game first, which takes about 15 seconds, and then the game sits in a moderation queue showing awaiting review. It is not public until a moderator approves it.

An editor link sends me to the play page

You have play-only access — either through a play-level share invitation, or as a team member with the player role. Ask the owner or a team admin for edit access.

Credits and plans

Generation stopped partway through

The active wallet ran out. Generation halts with a message rather than falling through to another wallet — that isolation is deliberate. Switch wallets, top up, or ask a team admin for a larger allowance. Everything that is not generation keeps working.

A tool says it needs Pro

Only 3D model generation, image-to-3D, 3D animation and textured primitives are plan-locked, because they run through an external provider. Everything on the platform's own hardware — 2D art, sprites, animation, Live2D, sound, music, voice — works on every plan and is limited only by credits.

The usage page shows spend with no game attached

That is design-phase work, concept art in particular. It is charged before the game exists to attach it to, so it cannot be attributed at the moment it happens. It is real spend on a real game.

A budget run reports it stayed on target but the balance says otherwise

Same cause. Concept art generated before the game was created is invisible to the budget tool, so a run can honestly report “5,000 of 5,000” while the true figure is higher. Ask your assistant to count design-phase art in the plan and to pass the game id once the game exists.

MCP connection

SymptomCause and fix
401, or a prompt to authenticate The header is missing or malformed. It must be Authorization: Bearer gi_… — with the space, and keeping the gi_ prefix. There is no OAuth fallback, so a client that cannot set headers cannot connect.
“MCP key required” No usable key reached the server. Check the header name, and check the key was not truncated when pasted.
No Gamentic tools offered The client has not reloaded its config. Restart it and confirm the server shows as connected in its MCP panel.
Tools vanish mid-task, then come back Normal. A server restart invalidates the session and clients transparently re-initialize. If it persists, restart the client.
Long tool calls time out Turn on Unstable connection mode in Agent Lab so game uploads go in resumable chunks instead of one long call.
“Game not found” on an id you can see Usually a permissions issue rather than a typo — the key belongs to an account without access to that game. Ids themselves are forgiving: quotes, backticks and a pasted editor URL are all accepted.
An edit was refused for asset loss The write would have removed images, audio or models already in the game. This is the guard working. If the removal is genuinely intended, the AI has to opt in explicitly — or use the delete tool, which snapshots first.
The AI says the assets it just wrote were changed back It submitted a whole-file rewrite from a stale copy, and the server's current assets won. The response lists what was preserved. It should not try to “fix” them; it should re-read the file first.

Content and visibility

I cannot see a game someone linked me

Either it is private and you were not invited, or it is rated mature. Mature games require an adult account with Allow mature content switched on in account settings — it is off by default, and logged-out visitors never see mature content.

Sign-up asks for an invite code

Registration is gated during the public beta. That is the gate rather than an error in what you typed.

Still stuck

Every page of the site has a Report a bug / share an idea button in the corner, which attaches the context automatically. From inside the Editor, screenshotting the running game and drawing on it is the fastest way to describe anything visual.