Blacksite/docs/editor/brp.md

Bevy Remote Protocol (BRP)

The editor enables Bevy’s built-in Remote Plugin over HTTP for automation, CI, and future tooling interop. BRP is editor-only — the shipped game binary does not expose a port.

Enablement

BrpPlugin in crates/editor/src/ext/brp.rs adds:

• RemotePlugin — core remote API
• RemoteHttpPlugin — HTTP transport

Launch the editor with dev features as usual:

cargo run -p editor --features dev

Default HTTP endpoint follows Bevy 0.18 remote defaults (port 15702, routes under /remote/).

Authoring-only mutation policy

BRP and automation must mutate authoring components only — the same allowlist used on scene save in scene_io.rs. Hydration rebuilds runtime ECS (Mesh3d, Bevy lights, physics, SceneRoot, etc.) on the next frame.

Allowed (examples)	Forbidden on level objects
Transform, Name, ActorKind	PointLight, SpotLight, DirectionalLight
Primitive, StaticMeshRenderer, MaterialDesc, MaterialOverride, LightDesc	Mesh3d, MeshMaterial3d, RigidBody, Collider
ModelRef, RigidBodyDesc, ColliderDesc, legacy PhysicsBody, gameplay markers	SceneRoot, generated static mesh children, internal visibility types
PostProcessVolumeDesc	Runtime post-process components on cameras

Prefer:

1. Editing LightDesc instead of SpotLight / DirectionalLight
2. Editing MaterialDesc instead of StandardMaterial handles
3. Editing StaticMeshRenderer instead of child Mesh3d entities
4. Editing ColliderDesc / RigidBodyDesc instead of runtime Avian components
5. Version-controlled assets/levels/*.scn.ron for durable changes

See ADR 0009 — Authoring vs hydrated.

Example flows

List entities

curl -s http://127.0.0.1:15702/remote/world/entities | head

Get entity components

curl -s -X POST http://127.0.0.1:15702/remote/world/get \
  -H 'Content-Type: application/json' \
  -d '{"entity":4294967296,"components":["bevy_transform::Transform"]}'

Mutate authoring transform (automation smoke)

curl -s -X POST http://127.0.0.1:15702/remote/world/mutate \
  -H 'Content-Type: application/json' \
  -d '{"entity":4294967296,"component":"bevy_transform::Transform","value":{"translation":[0,2,0]}}'

Replace entity with a live id from the list call while the editor is running.

Mutate LightDesc (not runtime lights)

curl -s -X POST http://127.0.0.1:15702/remote/world/mutate \
  -H 'Content-Type: application/json' \
  -d '{"entity":ENTITY_ID,"component":"shared::components::LightDesc","value":{...}}'

Hydration applies the change to viewport lighting after the next update.

Mutate PostProcessVolumeDesc

curl -s -X POST http://127.0.0.1:15702/remote/world/mutate \
  -H 'Content-Type: application/json' \
  -d '{"entity":ENTITY_ID,"component":"shared::components::PostProcessVolumeDesc","value":{...}}'

Overrides use None = inherit project; Some(v) = local override per field.

Editor command palette bridge

Registered commands in extensibility.rs are invokable via Ctrl+P and PendingEditorCommands:

Command	Action
play.toggle	Edit / Play
play.toggle_pause	Pause / resume sim in Play
play.toggle_possession	Possess / eject (Play only)
scene.reset_lighting	Remove all authored LightDesc; use project sun/ambient
selection.group	Spawn empty group; reparent selection
selection.focus	Frame editor camera on selection (same as F)
rendering.create_volume	Spawn post-process volume at editor camera
rendering.select_volumes_at_camera	Select highest-priority volume at camera
rendering.focus_active_volumes	Select + frame volumes at camera

External automation can enqueue the same names through the editor command queue when integrated.

CI / headless validation

Validate committed levels without the editor UI:

cargo run -p xtask --bin validate-levels

This runs scene::validate_level_file (schema migrate + authoring-only component check).

cargo test -p shared
cargo test -p scene
cargo check -p editor --features dev

Safety

• Run BRP only in trusted local dev environments.
• Do not enable BrpPlugin in production game builds.
• Scene files remain the source of truth; prefer version-controlled assets/levels/*.scn.ron over live mutation for durable changes.

Related

• Editor architecture
• Debt audit checklist
• Mission — BRP-aligned tooling
• Release notes