bevyengine/bevy

bevy_remote

The Bevy Remote Protocol (BRP). A JSON-RPC interface for inspecting and mutating a running Bevy app from outside the process. The foundation of the upcoming Bevy editor and a powerful debugging surface for any Bevy game.

Purpose

bevy_remote runs an in-process server that speaks JSON-RPC 2.0. Clients can:

List entities, components, and resources.
Query the world with filters.
Read, insert, remove, and modify components on individual entities.
Spawn or despawn entities.
Subscribe to changes via long-polling.
Run any custom RPC method registered by the user.

Two transports are provided out of the box: HTTP (the default; widely usable from any JSON client) and a stdio mode (useful when launching Bevy as a subprocess of a tool).

Directory layout

crates/bevy_remote/src/
├── lib.rs            # RemotePlugin, BrpRequest, BrpResponse, error types
├── http.rs           # RemoteHttpPlugin
├── builtin_methods.rs   # The standard world.* methods
├── builtin_verbs.rs     # bevy/list, bevy/get, etc.
├── schemas/             # JSON-schema description of types
└── …

Key abstractions

Type	File	Description
`RemotePlugin`	`crates/bevy_remote/src/lib.rs`	Adds the request/response infrastructure.
`RemoteHttpPlugin`	`crates/bevy_remote/src/http.rs`	Binds an HTTP listener (default `127.0.0.1:15702`).
`BrpRequest`, `BrpResponse`	`crates/bevy_remote/src/lib.rs`	Request and response types.
`RemoteMethodRegistry`	`crates/bevy_remote/src/lib.rs`	Resource: registers a method name → handler function.
Built-in methods	`crates/bevy_remote/src/builtin_methods.rs`	`world.query`, `world.get_components`, `world.list_components`, `world.spawn`, `world.despawn`, `world.insert_components`, `world.remove_components`, `world.reparent`.

How it works

sequenceDiagram
    participant Client as External client (curl, editor)
    participant Http as RemoteHttpPlugin
    participant Queue as BrpRequest queue
    participant World as World (main schedule)
    participant Reg as RemoteMethodRegistry

    Client->>Http: POST / JSON-RPC body
    Http->>Queue: enqueue BrpRequest
    World->>Queue: pull pending each tick
    World->>Reg: dispatch method
    Reg-->>World: BrpResponse
    World->>Http: send response
    Http-->>Client: HTTP 200 + body

Requests are queued on a channel and drained from a system on the main schedule. Each request is dispatched to the matching handler in RemoteMethodRegistry. Handlers have access to the full World via a Commands-like API, so they can mutate state in-place.

Responses go back through the same channel and are written to the HTTP response (or stdio).

Built-in methods

Highlights — see the crate-level doc comment in lib.rs for the full list:

Method	Purpose
`bevy/list`	List entities or components.
`bevy/get`	Read components on an entity.
`bevy/query`	Run a query with filters and return matching entities.
`bevy/spawn`	Spawn a new entity with components.
`bevy/despawn`	Despawn entities.
`bevy/insert` / `bevy/remove`	Add or remove components.
`bevy/registry/schema`	Get the JSON schema for a type.
`bevy/get+watch`, `bevy/list+watch`	Subscribe to changes (long-poll).

A request looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bevy/get",
  "params": {
    "entity": 4294967298,
    "components": ["bevy_transform::components::transform::Transform"]
  }
}

The response carries the reflected component values as JSON, encoded via bevy_reflect's serde support.

Integration points

Depends on: bevy_app, bevy_ecs, bevy_reflect, bevy_utils, serde, serde_json, async-channel. HTTP transport depends on http-body-util, hyper, bevy_tasks.
Depended on by: External tools (the in-tree examples include examples/remote/server.rs and examples/remote/client.rs). Editor prototypes consume this directly.

Entry points for modification

New built-in method: add a handler function and register it in BuiltinMethods. The pattern is straightforward.
Custom user method: call app.add_remote_method("my/method", my_handler).
New transport: model after RemoteHttpPlugin. The protocol is transport-agnostic; you only need a way to deliver a BrpRequest and ferry the BrpResponse back.