bevyengine/bevy

BRP protocol

Wire-format details for the Bevy Remote Protocol. JSON-RPC 2.0 over either HTTP or stdio. Messages are JSON objects; semantics for each method are in the bevy_remote rustdoc.

Envelope

Every request:

{
  "jsonrpc": "2.0",
  "id": <any JSON value>,
  "method": "<string>",
  "params": <object | array | null>
}

Every response:

{
  "jsonrpc": "2.0",
  "id": <echoed from request>,
  "result": <method-specific>,
  // OR:
  "error": { "code": <int>, "message": "<string>", "data": <any> }
}

id is opaque to the server; it gets echoed back.

params is method-specific. Some methods accept an empty params (or omit it).

Transports

HTTP (the default)

RemoteHttpPlugin binds an HTTP server on 127.0.0.1:15702 by default. Configurable via RemoteHttpPlugin::with_address and with_port.

Each POST is a single JSON-RPC message. Responses are returned in the same HTTP response. Long-poll subscriptions (bevy/get+watch, bevy/list+watch) hold the HTTP response open until a change is observed.

Origin headers / CORS: the default is permissive (intended for localhost). Don't expose to the public internet.

Stdio

stdio transport is intended for tools that launch Bevy as a subprocess. JSON-RPC messages are framed as one message per line on stdin/stdout. The HTTP plugin is not required.

Standard methods

Method	Params shape	Returns
`bevy/list`	`{ "entity"?: u64, "with"?: [..type names..], "without"?: [..type names..] }`	List of entities or components.
`bevy/get`	`{ "entity": u64, "components": [..type names..] }`	Map of `type name -> reflected value`.
`bevy/query`	`{ "data": { components, has, option }, "filter": { with, without, where } }`	Array of `{ entity, components, has }`.
`bevy/spawn`	`{ "components": { type name -> reflected value } }`	`{ entity: u64 }`.
`bevy/despawn`	`{ "entity": u64 }`	`null`.
`bevy/insert`	`{ "entity": u64, "components": { type name -> reflected value } }`	`null`.
`bevy/remove`	`{ "entity": u64, "components": [..type names..] }`	`null`.
`bevy/reparent`	`{ "entities": [u64], "parent": u64?? }`	`null`.
`bevy/registry/schema`	`{ "type": "fully::qualified::TypeName" }`	JSON-schema.
`bevy/get+watch`	Same as `bevy/get`	Long-poll: returns the next change.
`bevy/list+watch`	Same as `bevy/list`	Long-poll: returns the next change.

Type names are the fully-qualified Rust path (bevy_transform::components::transform::Transform). The BRP uses these to find types in the TypeRegistry. Short names also work when unambiguous.

Component values

Component values in requests and responses are the reflected JSON form of the component. For a Transform:

{
  "translation": { "x": 0.0, "y": 1.0, "z": 0.0 },
  "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
  "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }
}

The exact shape comes from bevy_reflect's serde codec — same as scenes. A type must #[derive(Reflect)], register #[reflect(Component)], and be registered with the TypeRegistry to be visible to the BRP.

Error codes

Standard JSON-RPC codes:

Code	Meaning
-32700	Parse error (malformed JSON).
-32600	Invalid request.
-32601	Method not found.
-32602	Invalid params.
-32603	Internal error.

Bevy-specific extensions (in the -32000 to -32099 range) cover entity-not-found, component-not-registered, schema-not-available, and similar.

Long polling

+watch methods don't return immediately. The server holds the connection open until a change matching the watch criteria happens, then responds. Clients should re-call after each response to maintain a watch.

Implementation: crates/bevy_remote/src/builtin_methods.rs.

Examples

List all entities with a Transform:

curl -s http://127.0.0.1:15702 -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "bevy/list",
  "params": { "with": ["bevy_transform::components::transform::Transform"] }
}'

Read components:

curl -s http://127.0.0.1:15702 -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "bevy/get",
  "params": {
    "entity": 4294967298,
    "components": [
      "bevy_transform::components::transform::Transform"
    ]
  }
}'

Spawn:

curl -s http://127.0.0.1:15702 -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "bevy/spawn",
  "params": {
    "components": {
      "bevy_transform::components::transform::Transform": {
        "translation": {"x":0,"y":0,"z":0},
        "rotation": {"x":0,"y":0,"z":0,"w":1},
        "scale": {"x":1,"y":1,"z":1}
      }
    }
  }
}'