Running Your Own MQTT Broker

By default, Studio and the Operator tool connect to the public broker at mqtt.zendir.io. For an isolated network, a classroom, or a private range, you can run your own broker instead. Space Range uses standard publish and subscribe, so any compliant broker works and nothing about the simulation changes.

How Space Range uses the broker

Studio connects to the broker as a client and runs every spacecraft, ground station, and admin controller internally. Operators and scripts connect as other clients. The broker only relays messages between them on topics under Zendir/SpaceRange/.

The broker never needs to understand a single Space Range message. Team isolation is handled entirely by encryption (see the encryption layers), not by broker permissions.

NOTE

If Studio is not connected to the broker, there is no traffic no matter how correct your client or broker is. Start Studio, connect the range, and run the simulation before debugging a client.

What the broker must support

Any MQTT 3.1.1 or later broker is sufficient. Mosquitto, EMQX, HiveMQ, and NanoMQ all work. The broker must provide:

A plain TCP MQTT listener on a known port. The default is 1883.
A WebSockets listener if the browser Operator tool will connect. The hosted deployment serves WebSockets on port 8883. A native client written against a TCP MQTT library does not need this.
Ordinary hierarchical topics under Zendir/SpaceRange/#. Topics are created implicitly on publish and subscribe, so nothing is pre-provisioned.
QoS 0 delivery. Higher QoS levels are harmless but unused.
Binary payloads. Uplink and downlink bodies are raw bytes, not UTF-8 text.

What the broker does not need

No custom server logic, plugins, or bridges. The broker does not decrypt, parse, or route by content.
No access-control lists or per-topic permissions. Segregation between teams is cryptographic.
No retained messages. Studio publishes at QoS 0 and does not set the retain flag, so clients must subscribe before traffic begins.
No authentication, in the default model. You may add broker authentication and Transport Layer Security (TLS) yourself if you need real confidentiality, but Space Range does not require it.

WARNING

The built-in encryption is in-game obfuscation, not security. The XOR layer is trivially broken with known plaintext and the Caesar layer offers about eight bits of secrecy. On a shared or public broker, anyone who knows the topic can see the traffic. For a real private deployment, put the broker behind a TLS endpoint with broker-level access control.

Configuring a local broker

Mosquitto is the simplest broker for a private range. A minimal configuration that serves both native TCP clients and the browser Operator tool is:

# mosquitto.conf
 
# Native MQTT clients (Studio, Python, custom terminals)
listener 1883
protocol mqtt
 
# Browser Operator tool (MQTT over WebSockets)
listener 8883
protocol websockets
 
# Development only: allow clients to connect without credentials
allow_anonymous true

Start the broker with:

mosquitto -c mosquitto.conf -v

The -v flag prints connections and published topics, which is useful while verifying that Studio and a client are talking to the same broker.

NOTE

Port 8883 is conventionally used for MQTT over TLS. Space Range serves the WebSockets Operator tool on that port in the hosted deployment. If you add TLS, update the Operator connection URL and the Studio settings to match, and confirm the transport with your broker operator.

Pointing Studio at your broker

Open Space Range in Studio and open the Client section. Set:

Server: the broker address, for example localhost for a broker on the same machine, or the host name or IP address of the broker.
Port: the TCP listener port, 1883 by default.

Then select Connect. The status line changes to connected when Studio reaches the broker. The full field list is documented in Configure the Server and Teams.

Operators then connect their tool to the same broker address and port, using the game name and their team access code.

Verifying the connection

Start the broker and confirm it is listening on the expected ports.
In Studio, connect the range and start the simulation.
Watch the broker log. You should see Studio subscribe to the team Uplink and Request topics and publish to Session.
Connect a client (the Operator tool or a script) and confirm it receives Session ticks roughly three times a second.

If a client sees no Session messages, the client and Studio are not on the same broker, the game name does not match, or the simulation is not running.

Next, read the protocol reference before writing a client, or continue to building a custom operator terminal.