SimTX API/Compatibility and versioning

This page describes the protocol version, the protocol revision and the feature registry of the SimTX API game protocol, and what a client must do to stay compatible as version 25 grows.

Protocol version

The protocol version is the integer in the 8-byte preface. The current version is 25, protobuf package simtx.v25. A server refuses a preface with any other version. An incompatible change would get a new version number and a new package.

Protocol revisions

Both hellos carry protocol_revision: ClientHello.protocol_revision and ServerHello.protocol_revision are the highest revision the sender implements. Revision 1 is the current protocol. Clients send 1.

A server keeps a station-bound session running across a station edit, with SessionStatus UPDATED, update_reason and a station snapshot, only for clients that announce revision 1 or higher. A client that announces nothing gets ENDED instead and must reconnect.

Behaviour tied to a revision applies only when the other side announced at least that revision.

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 that advertise stations.v1; otherwise it answers 409 station_binding_unsupported.

Additive changes

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.

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.