AI assistant

An AI client that speaks MCP can edit the level open in the editor while you watch. Each AI batch is one undo step, and the AI cannot publish, delete files or write over another level

The game on Windows, Linux and Mac ships an MCP server for this. The AI edits through the same operations you do, so every change appears in the viewport at once and lands in the history like your own

Any client that speaks MCP works, such as a chat app or a coding assistant. Nothing in the game is tied to one AI

Connecting a client

1. Open Settings → Game Editor → AI Agent (MCP)
2. Tick Allow AI Connections. The status line under the settings shows the port the editor listens on
3. Press Copy Client Config. The clipboard now holds the client config with both paths filled in
4. Paste it into the MCP server settings of your client
5. Open a level in the editor, or ask the AI to open the editor or a level itself

The copied config looks like this:

{ "mcpServers": { "bullet-hero": { "command": "<path to BH.MCP>", "args": ["--endpoint", "<path to endpoint.json>"] } } }

The server file BH.MCP lives beside the game:

Only this computer can connect, and only one client at a time. Phones and tablets have no MCP section: the assistant is desktop only

Several copies of the game may run at once. The AI works in the last one started until you ask it to switch, and it can list them all. Each copy still takes one client. For several copies, keep Port at 0, since two copies cannot listen on one port

What the AI can and cannot do

The AI can do almost everything you can:

• read the level: the hierarchy, objects, keyframes, events and resources
• create, change and delete objects, keyframes, markers, checkpoints, audio tracks and the beat grid
• run generators, pack and place prefabs, work inside Prefab Mode
• import a texture, font or audio file into the level
• fill in the attribution record of a texture, font or audio file after importing it: title, description, link, sources and authors - The resource record
• use the game's own preset themes, fonts and interface sounds. resources_list marks them as the game's, and they need no import. The game ships no preset effects: an effect the AI places is one the level already holds or a new one it creates
• draw any outline as a level shape from its corners, colour a shape with a gradient, set a text's font and alignment, create and edit the level's themes
• undo and redo, save the open level, open another level, create a new one
• start and pause playback, as your play button does
• move the game to another screen, such as the editor, a level or the settings, with the same arguments a launch takes - Launch arguments
• start the game when it is not running, if the server lies beside the installed game and MCP is already on

A run started this way counts in your statistics like any other, so the AI starts one only when you ask it to

It cannot:

• publish to Steam Workshop
• delete a level or any file
• write over another level or another file. An import whose file name is already taken is refused
• open a level that is read-only, or a protected level whose password you have not entered in this session
• open another level while the open one has unsaved changes

One AI batch is one step in history. It shows on the History tab as AI Batch with the AI's own caption. One Ctrl+Z removes the whole batch. More on history - Level settings › History

The AI never puts two objects on one layer while both play. If a batch would, it lifts the later object to the next free layer in the same step and says so. Prefab content is the exception: it may share layers with the rest of the level

The first AI batch that changes a level sets its AI Generation to Generated by AI, inside the same step. Undoing the batch reverts it. More - Metadata and sharing a level › AI generation

You have priority

The AI never fights you for the editor:

• while you drag a gizmo handle or scrub the timeline, the AI's edits are refused, and it waits and tries again
• the AI takes the playhead only while you are idle: not playing, not dragging, not typing, not saving
• the editor starts playing a level as it opens, so the AI may pause it to look at frames. A level the AI opens or creates itself stays paused. If you are watching playback on purpose, the AI asks before pausing
• if you touch the editor while the AI is looking at a frame, the AI stops at once. The playhead stays where you put it
• while a walk through history runs, the AI cannot edit either

While a client is connected, the viewport shows AI in its top right corner, under the search buttons. Its colour is the state: green - connected, amber - the AI is working, red - the AI's last call ended in an error. After the client disconnects, the badge stays for 30 seconds, so an AI that reconnects for every step does not blink. It hides together with the viewport tools. Hover over it to read the state in words: AI connected, and while the AI works, the caption of what it is doing. The cross beside it disconnects the client and refuses it, and the badge goes away

A stop is not saved. Turning Allow AI Connections off and on again or restarting the game clears it

What the AI sees

The AI looks at the level in two ways:

• a schematic. A picture of any frame, computed off screen. It does not move the playhead. It shows shapes and hitboxes, but no texts and no effects
• a capture. Real pixels, exactly as the level draws, taken through your playhead. For a moment the playhead jumps to that frame and the editor's overlays hide. Then the playhead returns to where you left it, unless Playhead Follows the AI is on. The picture is framed by the level camera, not by the editor camera. For a close look at a detail, the AI can frame a rect of the world instead. The level does not change

A still of an effect after a jump is close to what continuous play shows, but not always identical

The AI cannot hear the music. It turns the track into numbers: tempo, beats, bars, sections, how loud each band is. This is an estimate with a confidence, and it can be off, for example by half or double the tempo. The beat grid you set in the level is trusted over the AI's estimate. A beat grid the AI proposes from the analysis rounds a tempo within 0.01 % of a whole number to that number, and its offset is always shorter than one bar. A proposal over part of the track takes that part's own tempo, so a track whose tempo changes gets one segment per tempo

So when timing matters, the AI may ask you to listen. It plays a range of up to 45 seconds in the editor, and this also moves the playhead. Touch the editor, and playback stops where it is

While the editor's sound is muted, the AI does not play anything and asks you to turn the sound on

The AI's own actions make no interface sounds: an undo, a save or a refusal it causes is silent. Only what it plays on purpose is heard

The ai folder

The AI keeps its memory of the level in the ai folder inside the level folder. The next session, with any client, reads it first and continues where the last one stopped

What lies there:

• CONTEXT.md - the brief, the music, the section plan, decisions, your remarks and open questions
• other files the AI decides to keep, .md or .json only
• manifest.json - whether the folder travels with the level. The AI cannot change it

The folder appears only when the AI first has something to write. One file holds up to 256 KB, the whole folder up to 1 MB. These are plain text files: you can read, edit or delete them yourself

The folder travels with the level by default: in an exported archive and in a Steam Workshop upload. To keep it at home, clear Share AI context with this level on the Metadata tab of the level settings. The checkbox appears once the folder exists. It is saved to a file at once, so Ctrl+Z does not revert it either

An export mode with a password never carries the folder, whatever the checkbox says. More - Export and protection › Export level

A copy of the level on this device takes the folder along, since a copy is not sharing

Settings

All of them are in Settings → Game Editor → AI Agent (MCP) and are kept on this device only:

• Allow AI Connections - whether a client can connect at all. Off by default
• Port - the port the editor listens on. 0 picks a free one on every start
• Playhead Follows the AI - on: after a capture the playhead stays on the frame the AI looked at, paused
• Reveal AI Edits - after each AI edit, selects and pings what it created or changed
• AI Operation Delay, seconds - how long the editor waits between two AI operations, so you can follow them. 0 applies each at once

Every setting and its default - Editor settings › AI agent

Next: Not losing your work, Export and protection