Remote protocol
The NEO Remote Protocol lets a tool query and change a running app's entities, components and resources as JSON over HTTP. How to turn it on, its methods and its limits.
On this page
The NEO Remote Protocol lets another program look inside a running app: list entities, read and change components and resources, spawn and despawn, trigger events and read diagnostics. Requests and responses are JSON-RPC 2.0 messages, sent over HTTP. It's built for editors, inspectors and automated tests.
Turn it on#
Add RemotePlugin, which handles requests, and RemoteHttpPlugin, which listens for them:
use neo::prelude::*;
use neo::remote::{http::RemoteHttpPlugin, RemotePlugin};
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(RemotePlugin::default())
.add_plugins(RemoteHttpPlugin::default())
.run();
}cargo run --features neo/neo_remoteThe app listens on 127.0.0.1:15702 (and 15703 for the render world). RemoteHttpPlugin::default().with_address(..).with_port(..) changes it; with_headers adds HTTP headers, such as CORS headers for a browser-based tool. It only listens on this machine by default: anyone who can reach the port can change your game, so don't expose it.
Components and resources are read and written through reflection, so they need #[derive(Reflect)] and #[reflect(Component)] or #[reflect(Resource)]. Type names in requests are the full Rust paths; ask world.list_components or registry.schema for them.
A request#
curl -s http://127.0.0.1:15702/ -d '{
"jsonrpc": "2.0",
"id": 1,
"method": "world.query",
"params": {
"data": { "components": ["neo_transform::components::transform::Transform"] },
"filter": { "with": ["my_game::Cube"] }
}
}'The response has the same id and either a result (here, each matching entity with its Transform as JSON) or an error with a code and message.
Methods#
| Method | What it does |
|---|---|
world.query | Entities matching components (data.components, data.option, data.has) and filters (filter.with, filter.without). |
world.get_components, world.list_components | One entity's component values, or its component names. |
world.insert_components, world.mutate_components, world.remove_components | Change an entity's components. mutate sets one field by path. |
world.spawn_entity, world.despawn_entity, world.reparent_entities | Create, remove and re-parent entities. |
world.get_resources, world.insert_resources, world.mutate_resources, world.remove_resources, world.list_resources | The same for resources. |
world.trigger_event | Triggers an event by type name. |
world.get_components+watch, world.list_components+watch | Keep the request open and stream changes. |
world.inspect, world.inspect_component, world.inspect_resource, world.inspect_all_resources, world.summarize | Readable summaries of entities, components and the whole world. |
registry.schema, registry.component_metadata | The reflected types and their JSON schema. |
diagnostics.list, diagnostics.get | The app's diagnostics. |
app.info, rpc.discover | About the app, and every method it supports. |
Your own methods can be added with RemotePlugin::default().with_method_main("my_game.reset", handler), where handler is a system that takes the request's parameters.
Examples (need --features neo_remote): run cargo run --example server --features neo_remote, then cargo run --example client --features neo_remote in another terminal.