NEOLearn

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.

Updated October 20, 2026

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:

src/main.rs
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();
}
Shell
cargo run --features neo/neo_remote

The 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#

Shell
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#

MethodWhat it does
world.queryEntities matching components (data.components, data.option, data.has) and filters (filter.with, filter.without).
world.get_components, world.list_componentsOne entity's component values, or its component names.
world.insert_components, world.mutate_components, world.remove_componentsChange an entity's components. mutate sets one field by path.
world.spawn_entity, world.despawn_entity, world.reparent_entitiesCreate, remove and re-parent entities.
world.get_resources, world.insert_resources, world.mutate_resources, world.remove_resources, world.list_resourcesThe same for resources.
world.trigger_eventTriggers an event by type name.
world.get_components+watch, world.list_components+watchKeep the request open and stream changes.
world.inspect, world.inspect_component, world.inspect_resource, world.inspect_all_resources, world.summarizeReadable summaries of entities, components and the whole world.
registry.schema, registry.component_metadataThe reflected types and their JSON schema.
diagnostics.list, diagnostics.getThe app's diagnostics.
app.info, rpc.discoverAbout 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.

Next steps#