wtclaude
adb9df6a2e
Stage 1 of the §14.3 integration plan: the patrol helicopter, Bradley, the cargo ship, the Chinook, airdrops, locked crates, the Travelling Vendor, the satellite and the Deep Sea, with no plugin (D349). - `world.event`, one frame kind whose `event` names which of 24 types (PROTOCOL.md §20.5). The type is in `event`, never `type`: `type` is the envelope's, and the rig's sidecar dropped every world event as untyped when the plan's example put it there. Nothing is said before the world loads or while the server quits. Positions are x/z; the site works out the grid. - Credit (D372, D379): a damage table for the patrol helicopter, the Chinook and Bradley; `heli.downed`, `chinook.downed` and `bradley.destroyed` carry every candidate (blow, last, most, damagers) and the plugin credits nobody. D174's `CreditVehicle` and the tally's apcKills/heliKills are gone. - Locked crates told positively (oil rigs, cargo, ghost ship, a Chinook drop joined at the crate's landing); anything else says nothing. A Bradley's `where` comes from the game's spawners, not `RoadSpawned` (which defaults to true). `airdrop.called` comes from the cargo plane's spawn: `supply.call` raised neither OnAirdrop nor OnCargoPlaneSignaled. - The tally gains cratesHacked and dropsLooted (Safecracker, Scavenger, D356). - `world.call` (D354, D367, D378): one of a schedule's TriggeredEvents at random, without Trigger (which would reset its clock); satellite.random for the satellite. A position for the airdrop (InitDropPosition) and the patrol helicopter (SetInitialDestination) only, both set before the spawn, as the stage-1 spike measured (0-1 m and 10-54 m). Kept; the key is remembered seven days in world-calls.json; EventsMaxWorldCalls (default and ceiling 10) per run. - Hello/status `console.plugins` (D363): the bridge runs its own rg.probe through ConsoleSystem.Run from a timer. Carbon 2.0.262 refuses plugin commands only inside a console command (or a NextTick one queued), which is how §14.2's spike tested; from a timer, and from the link reader's NextTick, it finds them. Reads true on both rigs. - checkPlugin.js: the probe must name a [ConsoleCommand] the plugin declares. Compiled and loaded on both rigs (Rust 25902425, Oxide 2.0.7830, Carbon 2.0.262); heli.arrived, cargo.arrived and airdrop.called read back from each rig's sidecar store. Rigs restored. 18 check tests pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
Rust-Plugins
The in-game half of the Runic Gateway bridge for Rust: one Oxide plugin that dials out to a rust-link sidecar and speaks newline-delimited JSON over it.
It is the mirror of
RunicGateway/servuo-plugins, which
does the same job for Ultima Online — and it inherits that plugin's threading contract wholesale,
because the reason for it is the same on both games.
The threading contract
Everything else in this repo depends on these three:
Emitis called from the main thread. It formats nothing, blocks on nothing, and touches no socket. It enqueues and returns. A slow, wedged, or absent sidecar cannot stall the game.- One link thread owns the socket. It connects, drains the queue, and reconnects with backoff. A single writer keeps event ordering intact.
- A reader thread parses inbound lines and hands each to the main thread via
Interface.Oxide.NextTick. The reader touches no Unity object, noBasePlayerand noConVar— every one of those is main-thread-only, and reading one from the reader is the kind of bug that presents as a crash somewhere else entirely.
The outbound queue is bounded, drop-oldest. On overflow the oldest record goes and is counted, because telemetry is worth less than the server's memory.
Loopback is the trust boundary
There is no token on the game link. The plugin and the sidecar share a host, and the sidecar binds
127.0.0.1 — that is the authentication. Pointing Host at anything routable puts an
unauthenticated command channel on the network.
Installing it
overlay/oxide/plugins/RunicGateway.cs → <server>/oxide/plugins/RunicGateway.cs
overlay/oxide/plugins/RunicGatewayZones.cs → <server>/oxide/plugins/RunicGatewayZones.cs
overlay/oxide/plugins/RunicGatewayDomes.cs → <server>/oxide/plugins/RunicGatewayDomes.cs
RunicGatewayZones.cs is the ZoneManager helper (docs/modules/rust/PLAN_FIXES.md D181, D182). ZoneManager
counts a player in a zone only when its trigger fires on entry, so a zone created, updated or re-created around
somebody already standing there holds nobody. The helper patches that with Harmony. It is optional: without it the
bridge still loads, scores its own zones by position, and reports the helper missing at hello. rgz.status in the
server console says whether it patched.
RunicGatewayDomes.cs is the ZoneDomes helper (docs/modules/rust/PLAN_REDESIGNS.md §3.2, D194). ZoneDomes'
API ends by telling the player who asked how it went, and throws when a plugin calls it with no player; and at its
own start it drops the dome of every zone that does not exist yet, which is every zone the bridge re-creates. The
helper patches the first with Harmony and tells the bridge when ZoneDomes has started, so the bridge can put its
domes back without drawing any twice. It is optional: without it the site offers no dome, and says which piece is
missing. rgd.status in the server console says whether it patched.
Oxide compiles and loads it on the write, and writes oxide/config/RunicGateway.json on first load:
{
"Host": "127.0.0.1",
"Port": 7799,
"QueueCap": 5000,
"ServerId": "main"
}
ServerId is this server's stable identity across wipes and restarts, as the website knows it. It
is deliberately not derived from the hostname: an operator renames a server for a season, and
the site must not lose its history for it.
When that first config is written, and only then, a valid RUSTLINK_SERVER_ID in the server's
environment becomes its ServerId (an invalid one is logged and ignored). That is how the
Pterodactyl egg names a server, since an egg can set a variable but cannot reliably write a
framework's config directory. After that the file is canonical and the website locks the value, so
changing the variable later changes nothing.
On Carbon the same file goes to carbon/plugins/ and its config to carbon/configs/.
That is the developer's loop. An operator uses the
installer (--game rust) or the Pterodactyl
egg, both of which deploy a released plugin and install the sidecar beside it.
Releases
Every merge to main that carries a feat, fix or perf commit cuts a release
(.gitea/workflows/release.yml): runicgateway-rust-plugin-<version>.tar.gz and SHA256SUMS. The
tarball holds one directory, runicgateway-rust-plugin/, with RunicGateway.cs (its [Info]
version stamped to the release), the helpers beside it (each keeping its own version; every .cs is listed with
its sha256 in the manifest's files, and the installer and the egg place them all) and a manifest.json folding in overlay.toml: the protocol, the
Oxide and Carbon floors, and requires_plugins. The layout names no framework; the installer and
the egg decide where the file goes. A release then asks the installer repo to recompose its Rust
bundle.
Prerequisites
The bridge itself needs nothing but Oxide. The features that follow it read three third-party
plugins an operator installs from uMod — Kits, PopupNotifications and ZoneManager. They are
listed in overlay.toml so the installer's doctor can report a missing one by name rather than
leaving the site quietly short of a feature.
Clans on the website come from Rust's own clan system, not from the uMod Clans plugin, which
is optional. The two share no data: a server running the plugin has two unrelated clan systems, and
only the game's own clans become Teams on the site.
Wulf's Economics is optional too, and not in overlay.toml. Where it is loaded the site can pay
coins from an event, show balances and a richest column, and let staff adjust a balance; where it is
not, each of those says "Economics is not installed on this server".
WhiteThunder's Backpacks is optional in the same way. Where it is loaded staff can open a player's
backpack from the site, a player can see their own, and an event can lend a bigger one for its run;
the bridge only ever reads a backpack, and the bigger size is one of Backpacks' own backpacks.size.N
permissions, pushed like any other grant.
Rust's own world events need no plugin at all. The patrol helicopter, Bradley, the cargo ship, the
Chinook, airdrops, locked crates, the Travelling Vendor, the satellite and the Deep Sea reach the
site's feed and its event triggers on every server, and an event can call one of them (world.call).
What a call starts is kept when the event ends; EventsMaxWorldCalls caps how many one run may call.
Diagnosing it
rg.link
from the server console or over RCON. It reports the link's own counters:
protocol=1 serverId=main connected=True depth=0 sent=3 dropped=0 received=2
connects=1 writeErrors=0 bootId=boot-20260915T194502Z
This is the first thing to ask for when the website says a server is offline — it separates "the plugin is not loaded", "the plugin cannot reach the sidecar" and "the website cannot reach the sidecar", which look identical from the site.
bootId identifies the server PROCESS, not the plugin load. It is the process start time, so
oxide.reload RunicGateway does not change it. That matters more than it looks: the website watches
this value to tell a game restart (everything an event put in the world is gone) from a bridge
reconnect (nothing is lost), and a plugin reload is the second kind.
The protocol is a contract
ProtocolVersion in the plugin and protocol in overlay.toml must agree with the sidecar's
PROTOCOL_VERSION and the module's own constant. The installer refuses to pair an overlay and a
sidecar that disagree, so a bump landing in one repo and not the others fails to compose rather than
half-deploying.
The canonical spec is
docs/rust-link/PROTOCOL.md.
Licence
GPL-3.0-or-later. See LICENSE.md.