foxzool wiki

Bevy Remote Protocol (BRP)

Properties1
tagsbevy, rust, ecs, dev-tools, automation, mcp, game-engine, security

4 min read

Bevy Remote Protocol (BRP)

Overview

Bevy Remote Protocol (BRP) is Bevy’s JSON-RPC-based remote access layer for a running bevy application. It lets external tools inspect and mutate the ECS world: query entities, read and change components/resources, spawn/despawn entities, watch component changes, read registry schema, and trigger runtime messages/events.

The important framing: BRP is not the Bevy Editor itself. It is the low-level communication substrate that makes editor-like tools, inspectors, automated tests, Blender/VSCode/Neovim integrations, and AI debugging loops possible. It turns the running ECS world into a tool-addressable runtime database.

Enabling BRP

A Bevy app enables the protocol layer with RemotePlugin and starts an HTTP transport with RemoteHttpPlugin:

use bevy::{
    prelude::*,
    remote::{http::RemoteHttpPlugin, RemotePlugin},
};
 
fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(RemotePlugin::default())
        .add_plugins(RemoteHttpPlugin::default())
        .run();
}

The default HTTP transport binds to localhost on 127.0.0.1:15702; current Bevy main also exposes a render-app port (15703) when render support is enabled. Treat this as a local development/debugging interface, not a public production API.

Protocol shape

BRP uses JSON-RPC 2.0. Method names are case-sensitive strings such as world.query, world.get_components, and world.mutate_components.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "world.get_components",
  "params": {
    "entity": 4294967298,
    "components": ["bevy_transform::components::transform::Transform"],
    "strict": false
  }
}

Component and resource names use full Bevy type paths, not short names. A user component generally needs Reflect plus serialization reflection to be usable from external BRP tools.

Built-in capability map

AreaMethods / capabilityNotes
Entity lifecycleworld.spawn_entity, world.despawn_entity, world.reparent_entitiesCreate, destroy, or reparent entities.
Component accessworld.get_components, world.list_components, world.queryRead known components or query the ECS.
Component mutationworld.insert_components, world.remove_components, world.mutate_componentsPatch world state through reflection paths.
Watchworld.get_components+watch, world.list_components+watchStream component changes for inspector-style tools.
Resource accessworld.get_resources, world.list_resourcesRead reflectable resources.
Resource mutationworld.insert_resources, world.remove_resources, world.mutate_resourcesRuntime tuning and tool control.
Runtime signalsworld.trigger_event, world.write_messageEvent/message control; write_message is present in current main.
Schema/discoveryregistry.schema, rpc.discoverRegistry schema is useful today; OpenRPC discovery exists but is not yet complete.
Schedule/debuggingschedule.list, schedule.graphCurrent-main direction for runtime schedule inspection.
Observersworld.observe+watchCurrent-main direction for event/observer watching.

Version-sensitive notes

Method names changed

Older material may use bevy/query, bevy/get, bevy/insert, or registry/schema. Newer BRP APIs use explicit names:

OldNew
bevy/queryworld.query
bevy/spawnworld.spawn_entity
bevy/destroyworld.despawn_entity
bevy/getworld.get_components
bevy/insertworld.insert_components
bevy/removeworld.remove_components
bevy/mutateworld.mutate_components
registry/schemaregistry.schema

world.query is lenient by default

Since the 0.15 → 0.16 migration path, BRP query behavior defaults to skipping missing or invalid components instead of failing the entire request. Set strict: true when a missing/unreflectable component should be treated as a hard error.

Schedule ordering matters

BRP originally had ordering ambiguity when remote systems ran in Update. The resolved design moved remote request processing to Last under a RemoteSystem set so tools see the finalized state for a frame. This matters for inspectors and watch loops because they should not observe arbitrary mid-frame partial state.

Why it matters

BRP gives Bevy a standard tool protocol instead of forcing every project to build its own debug UI. It connects directly to several existing wiki topics:

  • bevy-development-patterns — BRP is part of the broader pattern of exposing engine state through structured, data-oriented APIs.
  • bevy-game-development — useful for automated smoke tests, screenshots, and remote debugging.
  • bevy-projects — relevant for any ZoOL Bevy tool that needs external inspection, visual regression, or AI-assisted debugging.
  • bevy-version-notes — BRP is one of the important Bevy 0.15-era developer-experience features.

For AI agents in particular, BRP is a better observation channel than logs alone: an agent can query ECS state, inspect components, mutate values, take screenshots through companion tooling, and iterate based on actual runtime state.

Security boundary

BRP can change live program state. Do not expose the HTTP transport to the public internet without authentication and network isolation. The default localhost binding is the right default for development tools. CORS/headers configuration is not a substitute for authentication.

Practical checklist

When adding BRP to a project:

  1. Enable Bevy’s bevy_remote feature.
  2. Add RemotePlugin and a transport such as RemoteHttpPlugin.
  3. Keep the transport bound to localhost unless there is a deliberate security design.
  4. Derive/register Reflect, Serialize, and Deserialize for components/resources that tools should inspect or mutate.
  5. Use registry.schema / world.list_components to discover full type paths.
  6. Prefer strict: false for exploratory inspectors and strict: true for test assertions.
  7. Treat method names in older blog posts/issues as version-sensitive; prefer world.* names.

Open questions / watchlist

  • How complete will OpenRPC support become? rpc.discover exists, but full parameter/result schemas remain an active design problem.
  • How stable will type paths be across Bevy pre-1.0 refactors?
  • Which BRP capabilities will become part of a future official Bevy Editor contract versus remaining dev-tool internals?
  • How far should AI-agent tooling go through raw BRP versus a higher-level MCP bridge such as bevy_brp_mcp?

Graph View

Backlinks