SimTX API/Compatibility and versioning

This page explains how the SimTX API game protocol changes over time, and what a client must do to keep working as it does: the protocol version, protocol revisions within a version, the feature registry, and the additive-only rule. It ends with a summary of the changes from version 24.

Protocol version

The protocol version is the integer in the 8-byte preface. It changes only for a breaking change. A breaking change gets a new version and a new protobuf package (simtx.v26 after simtx.v25), and servers answer older prefaces with a version-unsupported result rather than misreading them.

Version 25 replaced version 24 completely; the two are not compatible. See Changes from v24.

Protocol revisions

Within version 25, additive changes that a peer may need to detect increase the protocol revision. Both hellos carry it: ClientHello.protocol_revision and ServerHello.protocol_revision are the highest revision the sender implements. A peer relies on revision-N behaviour only when the other side's revision is at least N. An unset value is 0.

Revision	Adds
0	A peer that sends no revision: the v25 schema without the revision-gated behaviours.
1	The first released v25, frozen on 24 October 2026: everything in the current .proto files, including the late additions AntennaAim on both starts, Tracking.since_*, IqBlock.sequence, request_id on ReceiverRetune and on StartMonitor / StopMonitor (acknowledged by MonitorAck), BannerLevel and ERROR_CODE_CANCELLED. Gated on the client's revision: a server keeps a station-bound session running across a station edit, with SessionStatus UPDATED, update_reason and a station snapshot, only when the client announced revision 1 or higher. Older clients get ENDED.

A client should send the highest revision whose behaviour it really implements. A client that announces revision 1 must handle UPDATED statuses with a station snapshot.

The schema changed incompatibly before release: enum zero values, the shared StationCore and SessionSite, the single Error model, and the removal of TxReject, TxKick and ModerationError. That final shape is documented as revision 1 rather than 2, because no released peer predates it. Pre-release builds that also announced revision 0 or 1 are not v25 peers. Regenerate bindings from the current files.

Feature registry

Optional server capabilities that depend on the deployment rather than on the schema are listed by name in ServerHello.features, and per server in the server directory with ?include=features.

Feature	Meaning
stations.v1	Persistent stations: StationBinding in session starts, station-bound tickets, station entries in the station list.
pointing	AntennaPointingUpdate and Tracking are accepted.
ephemeris	EphemerisRequest is answered.
passes	PassPredictionRequest is answered.
kinematics	Satellite motion (orbit, attitude, Doppler) is simulated.

ClientHello.features uses the same names for what the client understands: send stations.v1 if the client handles BoundStation and station-bound sessions.

Rules:

• Clients ignore feature names they do not know; servers do the same.
• Names are never reused or redefined. A changed meaning gets a new name, such as stations.v2.
• Treat a missing feature as "not available" and hide the user interface for it.
• Prefer feature checks for deployment capabilities and protocol_revision for knowledge of the schema. Avoid checks on server_version.
• The account service mints station-bound tickets only for servers whose every node advertises stations.v1; otherwise it answers 409 station_binding_unsupported.

Additive only

After the freeze, version 25 grows only by adding:

• new messages and new oneof members of ClientFrame and ServerFrame;
• new fields in existing messages;
• new enum values;
• new names in the string enumerations (modulations, antenna types, sources, weather layers, catalog types).

Field numbers and enum numbers are never renumbered or reused, field types and labels never change, and oneof membership never changes. A removed field's number and name are reserved. The schema of every revision is frozen as a binary descriptor, and the build compares the current schema against it, failing on any removed, renumbered, retyped or relabelled field, removed enum value or message, or changed oneof membership.

What a client must do

• Skip unknown frames. A frame whose member you do not know parses with no member set; ignore it and keep reading.
• Skip unknown fields of every wire type. Generated parsers do; hand-written codecs must.
• Keep unknown enum values and show them as unknown rather than failing.
• Accept unknown string-enumeration names from the server and show them as they are.
• Use presence. Proto3 omits zero values. Fields marked optional say whether they were set; unset means "use the default".
• Ignore unknown JSON fields from the account service, which follows the same rule.

Changes from v24

A summary for authors of v24 clients. The v24 reference is archived at SimTX API v24.

Area	v24	v25
Encoding	Hand-laid big-endian packets with an ID byte and no length prefix	Protobuf messages in varint-delimited ClientFrame / ServerFrame frames; unknown frames and fields are skipped
Handshake	Handshake with magic, version, role, auth kind and credential	8-byte preface, then ClientHello with client name, version, features and protocol revision
Handshake result	HandshakeResult, status 0 = accepted	ServerHello, status 1 = accepted; adds features, protocol revision and clocks
Roles	Six roles including TIMESTAMPED_RECEIVER	Five roles; timestamps are an option of every receiver
Receiver start	ReceiverSessionRequest with inline callsign, location and antenna	ReceiverStart with a SessionSite: a station binding or an ad-hoc site; sample format, tracking
Transmitter start	TransmitterSessionRequest, a TLV field list	TransmitterStart with a SessionSite; imperfections in TxImperfections; ad-hoc transmitters need tx.adhoc
Stations	Each session was its own station with a new UUID	Persistent, account-owned stations and satellites; sessions bind to them
Session state	Implicit; failures often closed the connection silently	SessionStatus BOUND, UPDATED, REJECTED, ENDED
Errors	TxReject, TxKick, ModerationError, flags in responses, silent closes	One Error model with request_id; SessionStatus for sessions
IQ blocks	IqBlock and TimedIqBlock	One IqBlock with optional timestamps and a sequence number
Retune	No acknowledgement	Optional request_id, confirmed by SessionStatus UPDATED
Control session start	ControlAck	Nothing; an accepted ServerHello is enough
Requests	Most control requests had no id	Every control and moderation request has a request_id
Ids	UUIDs as 36-character text	UUIDs as 16 bytes
Frequencies	f32	double
New		Ping and Pong, antenna pointing and tracking, Doppler correction, ephemerides, pass predictions, monitor acknowledgements