bevy_fairy
Let a coding agent look inside a running Bevy game, drive it, and ask the person playing it for help — without touching your desktop.
接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令? 两种安装方式的区别
bevy_fairy is two things in one crate:
bevy-fairy, which gives an agent such as
Claude Code tools to read the game's state, run the game's own commands, capture what it shows,
and inject input.coding agent ──MCP over stdio──▶ bevy-fairy ──BRP over HTTP :15702──▶ your game + DebuggerPlugin
│
guide card on screen ▼
the person at the keyboard
[!NOTE] This crate was written by an AI agent working from a human's direction. It is tested against a fixture game and used against a real one, but it has had no line-by-line human audit.
A scripted tour. Every reply is the real server's output; every picture is the game frame its
screenshot tool returned. The game runs at 10 fps here so the planted bug — the spinner stops at
frame 120 — happens mid-tour.

A real agent session. Claude, with no tools but these, told that something in the game which
should spin forever stops, and asked what it is, which of its values stops changing, and on what
frame. The script runs that question as the spinner_stops eval up to three times and draws the
first session that passes; it never draws one that failed.

Both are recorded from examples/demo_game.rs
by python3 scripts/record_demo.py all.
An agent that debugs a game by reading source code is guessing. It needs to see the game's actual state, change it, and check what happened. The obvious way to do that, OS screenshots and OS input, needs the game window in front: on the game this was built for, a capture with the window focused had 7,188 distinct colours, and with another app in front it had one. Synthetic OS keystrokes go to whichever window has focus, which is often the one you are typing in.
So nothing here touches the operating system. Captures come from the game's own pixels, input is
written into Bevy's own input streams, and tests/plugin_leaf.rs fails the build if the plugin's
dependency graph ever gains something that could synthesise an OS event.
It cannot see frame time, CPU or memory: BRP does not report them, and the tools say so rather than make up a number.
This takes a game you already have and an agent that speaks MCP, such as Claude Code.
1. Add the plugin to your game.
# Cargo.toml
[dependencies]
bevy = "0.20"
bevy_fairy = { version = "0.2", default-features = false, features = ["plugin"] }
use bevy::prelude::*;
use bevy::remote::http::RemoteHttpPlugin;
use bevy_fairy::DebuggerPlugin;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(DebuggerPlugin::default()) // registers the bevy_fairy/* methods
.add_plugins(RemoteHttpPlugin::default()) // serves them on port 15702
.run();
}
Run the game, then check it answers:
curl -s localhost:15702 -d '{"jsonrpc":"2.0","id":1,"method":"bevy_fairy/status"}'
# {"jsonrpc":"2.0","id":1,"result":{..., "ready":true, ...}}
2. Install the server.
cargo install bevy_fairy --no-default-features --features server
bevy-fairy --version
# bevy-fairy 0.2.2
3. Register it with your agent. For Claude Code, from your project directory:
claude mcp add bevy-fairy -- bevy-fairy --stdio
For Claude Desktop or a project .mcp.json:
{
"mcpServers": {
"bevy-fairy": {
"command": "bevy-fairy",
"args": ["--stdio"],
"env": { "BEVY_BRP_HOST": "localhost", "BEVY_BRP_PORT": "15702" }
}
}
}
4. Try it. With the game running, ask the agent: "Call status, then list the game's resources
with brp." It should report ready: true and a list of resource type names. From there, ask it
questions about your game.
Register commands with typed params and a worked example. The agent finds them with commands and
runs them with run; a mistyped name is answered with the nearest real one, and wrong params are
refused before your handler runs.
use bevy_fairy::{DebugCommandInfo, DebugCommandsAppExt};
use serde_json::{json, Value};
#[derive(serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct SpawnCube { at: [f32; 3] }
fn spawn_cube(In(p): In<SpawnCube>, mut commands: Commands) -> Result<Value, String> {
commands.spawn(Transform::from_translation(Vec3::from(p.at)));
Ok(json!({ "spawned_at": p.at }))
}
// After .add_plugins(DebuggerPlugin::default()):
app.add_debug_command(
DebugCommandInfo::new("demo/spawn_cube", "Spawn a cube at a world position in metres")
.params("at: [x, y, z]")
.example(json!({ "at": [0.0, 0.5, 0.0] })),
spawn_cube,
);
Registration is checked at startup: a reserved name (bevy_fairy/, world., ...), a duplicate,
or an example that does not parse as the params type panics then, not when the agent calls it.
If your game needs time to load, build the plugin with DebuggerPlugin::default().host_signals_ready()
and set the DebugReady resource to true when it is; until then every command answers "not
ready yet".
Enable plugin-screenshot, then give the plugin an image one of your cameras renders to:
use bevy_fairy::DebugCaptureTarget;
commands.insert_resource(DebugCaptureTarget { image: render_target_handle });
With a DebugCaptureTarget, captures come from that image and never depend on the window. Without
one, screenshot falls back to the game window. That needs nothing from the OS, but a covered or
minimised window can give a stale frame. A full example with the camera setup is
examples/plugin_agent_scene.rs.
The agent sends input through brp with the method bevy_fairy/input:
{"kind": "Keyboard", "key": "Space"} // a tap: pressed one frame, released the next
{"kind": "Keyboard", "text": "site_67"} // typed into a focused text field
{"kind": "Cursor", "x": 640, "y": 360} // logical window pixels
{"kind": "Mouse", "button": "Left", "action": "Press"}
{"kind": "Cursor", "clear": true} // hand the pointer back to the real mouse
Input is written into Bevy's own input messages before its input systems run, so just_pressed,
text fields and ButtonInput all see it like a real key. The cursor is the exception that needs a
line of your code: read the pointer through bevy_fairy::cursor_position(&window, &debug_cursor),
not Window::cursor_position. The plugin never moves the real pointer, because Bevy would move the
physical mouse out from under whoever is at the machine.
Enable plugin-guide. The agent posts a script with guide; your game shows one step at a time:
{"steps": [{
"label": "drop a floor and a wall",
"goal": "a tile needs two pieces before the solver can match",
"do": ["walk the library with up and down", "press Enter to bring a row in"],
"checkpoint": "tile has two members",
"recovery": "if nothing lands, the filter is hiding every row: press Backspace"
}]}
A checkpoint is a condition your game registers by name, so the plugin never needs to know your game's vocabulary:
use bevy_fairy::Checkpoints;
let has_two = app.register_system(|_: In<serde_json::Value>, tile: Res<Tile>| tile.members >= 2);
app.world_mut().resource_mut::<Checkpoints>().register("tile has two members", has_two);
A step without a checkpoint waits for the person to say it is done. For each step the agent gets back how many times it came up, how many of those its checkpoint passed, and how long it took.
Every game command the agent runs is recorded. scene save <path> writes them to a file;
starting the game with BEVY_FAIRY_SCENE=<path> replays them, one step per frame, once the game
reports ready. Scenes record commands, not raw input.
docs/mcp-tools.md
has every description and argument, generated from the server's own tools/list.Bevy's own methods (world.query, world.get_resources, registry.schema, ...) work too.
A game should depend on bevy_fairy with default-features = false, or it compiles the server too.
None of these need a window or a GPU unless noted. Each prints what happened.
cargo test --workspace # everything
cargo test --no-default-features --features plugin --test plugin_leaf # the no-OS-access check
UPDATE_TOOL_REFERENCE=1 cargo test --test tool_list # regenerate docs/mcp-tools.md
Tool behaviour is tested against examples/fixture_game.rs, whose state is known from its own
constants. evals/ measures
whether an agent with only this server can answer debugging questions about that game.
CLAUDE.md explains the design
decisions that are easy to undo by accident.
Issues and pull requests are welcome at github.com/Ladvien/bevy_fairy.
See CHANGELOG.md.
Licensed under either of MIT or Apache-2.0, at your option.
An agentic debugger for Bevy games: a plugin that exposes a game's state over BRP, and an MCP server that lets a coding agent read and drive it
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Bevy Fairy 通过 stdio 在本地运行。
上次检查时间:2026-10-27。 An agentic debugger for Bevy games: a plugin that exposes a game's state over BRP, and an MCP server that lets a coding agent read and drive it