kovagoadiandClaude
f7ca395a4f
The last commit noted in passing that the server-side half of the admin
GameScript channel "is not in this repo -- docker/config is gitignored --
so it has to be updated separately for any of this to work." That was true
of all nine features the README documents: list_vehicles, list_stations,
list_cargo, get_timetable, get_station, get_station_cargo, get_dispatch and
the event stream all answer from 705 lines of Squirrel that no clone could
reproduce, no reviewer could see, and CI never touched.
The bridge now lives in gamescript/AdminBridge/ with its own README, the
same arrangement docker/patches/ uses for the local JGRPP patches, and
docker-compose.yml bind-mounts it read-only over the container's
game/AdminBridge. docker/config stays ignored -- it also holds savegames,
downloaded content and generated config -- so the copy under it is now
shadowed and can be deleted. main.nut is byte-identical to what was running,
apart from the version work below.
Adds a version handshake, because the channel gives no way to tell a stale
bridge from a hung one: a bridge that does not recognise a command drops it
silently, so a client ahead of the server sees nothing but timeouts. The
bridge now answers get_version with its protocol version plus its command
and event catalogues, and get_bridge_version() raises when that is below
GS_BRIDGE_VERSION. It is opt-in rather than checked on connect: GameScripts
do not tick while the game is paused, so an automatic check would refuse to
connect to a paused server. A bridge older than 4 predates get_version
itself and can only fail by timing out, so the E2E test catches that and
reports it by name instead.
tests/test_gamescript.py gives CI a foothold on the GameScript without a
Squirrel toolchain: it parses the .nut files and pins the protocol version
across info.nut, main.nut and protocol.py, the event catalogue against
GameEventType, and the command table against the commands client.py sends.
The version has to be declared three times because a GameScript cannot read
its own info.nut at runtime -- GSController.GetVersion() returns the OpenTTD
version, not the script's.
info.nut also gains MinVersionToLoad() { return 1; }. The engine defaults it
to GetVersion(), so without it this bump would orphan every savegame pinned
to version 3: the scanner finds no compatible script and falls back with a
warning. The bridge keeps no savegame state, so any version can take over.
HandleCommand now dispatches through the same table get_version reports,
rather than an if/else chain, so the catalogue a client feature-detects
against cannot drift from what is implemented.
Co-Authored-By: Claude <[email protected]>
4.7 KiB
AdminBridge GameScript
The server-side half of this project. Every OpenTTDAdminClient feature that goes over the
GameScript JSON channel — list_vehicles, list_stations, list_cargo, get_timetable,
get_station, get_station_cargo, get_dispatch and the subscribe_events push stream — is a
command this script answers. The Python client is only half the protocol; this is the other half,
and the two are documented together in docs/PROTOCOL.md.
It is a deity GameScript: it joins no company, builds nothing, and only reads game state and
replies on the admin port via GSAdmin.Send().
info.nut— the manifest OpenTTD's script scanner reads (name, version, API version).main.nut— the bridge itself: a command dispatch table, one handler per command, and the event poller.
Why it lives here
docker/config/ is gitignored — it also holds savegames, downloaded content and generated
config — so a GameScript kept there is invisible to review and to CI, and a fresh clone cannot
reproduce the server side at all. This directory is the source of truth, the same arrangement
docker/patches/ uses for the local JGRPP patches.
docker-compose.yml bind-mounts this directory read-only over the container's
game/AdminBridge, so the server runs the tracked copy and nothing else:
- ../gamescript/AdminBridge:/home/openttd/.local/share/openttd/game/AdminBridge:ro
Editing the copy under docker/config/game/AdminBridge/ therefore has no effect; that path is
shadowed by the mount. On a server not started through this compose file, copy the directory
into the OpenTTD data dir instead:
cp -r gamescript/AdminBridge ~/.local/share/openttd/game/
A GameScript is loaded when the game starts, so a change needs the server restarted (or the game reloaded) before it takes effect — the running instance keeps the old code.
Protocol version
info.nut's GetVersion() is the version of the JSON protocol, not of the implementation:
bump it when a command, field or event kind changes shape, not for a refactor. Three places
carry it and all three must move together:
| Where | What |
|---|---|
info.nut → GetVersion() |
what OpenTTD records in the savegame |
main.nut → BRIDGE_VERSION |
what the get_version command reports |
lib/openttd/protocol.py → GS_BRIDGE_VERSION |
what the client requires |
A GameScript cannot read its own info.nut at runtime — GSController.GetVersion() returns the
OpenTTD version — hence the duplication. tests/test_gamescript.py
pins the three together, along with the event catalogue and the command list, so a half-finished
bump fails in CI rather than against a live server.
OpenTTDAdminClient.get_bridge_version() is the client end of this: it asks the running bridge
and raises if it is too old, which is worth doing once at startup. Without it a stale bridge
gives no error at all — it does not recognise the command, so the client just waits out its
timeout. A bridge older than version 4 predates get_version itself and can only fail that way.
Requirements
- JGRPP, patched with
docker/patches/—get_timetableandget_dispatchcallGSOrdergetters those patches add. Every other command uses stock GameScript API, so an unpatched server still answers them. - The admin client must subscribe with
update_frequency(Gamescript, Automatic)or the server drops every reply. The client does this automatically on first use. - GameScripts do not tick while the game is paused, so a paused server answers nothing and every query times out.
Which GameScript actually runs
OpenTTD runs exactly one GameScript, and a savegame remembers the one it was played with by
name: loading it overrides [game_scripts] in openttd.cfg. So a savegame that pins some other
script leaves this bridge unloaded, and every command times out no matter what is mounted where.
The symptom to recognise is commands timing out uniformly — as opposed to a stale bridge, where
the older commands still answer and only newer ones hang.
Verifying a change
docker/config being untracked used to mean this file could only be tested against a running
server. It still needs one for the real check — pytest -m e2e exercises every command end to
end, and docs/TESTING.md covers starting the server. Before that,
pytest -m "not e2e" tests/test_gamescript.py catches the drift a server would only reveal as a
timeout. Note that a syntax error anywhere in main.nut stops the whole bridge from loading, so
every command fails at once — check the server log (docker compose logs) for the compile error.