wtclaude
adb9df6a2e
All checks were successful
PR Checks / plugin-checks (pull_request) Successful in -1m55s
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
153 lines
7.9 KiB
Markdown
153 lines
7.9 KiB
Markdown
# Rust-Plugins
|
|
|
|
The **in-game half** of the Runic Gateway bridge for [Rust](https://rust.facepunch.com/): one Oxide
|
|
plugin that dials out to a [rust-link](https://gitea.whitlocktech.com/RunicGateway/Rust-Link)
|
|
sidecar and speaks newline-delimited JSON over it.
|
|
|
|
It is the mirror of
|
|
[`RunicGateway/servuo-plugins`](https://gitea.whitlocktech.com/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:
|
|
|
|
- **`Emit` is 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, no `BasePlayer` and no `ConVar` —
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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](https://gitea.whitlocktech.com/RunicGateway/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`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md).
|
|
|
|
## Licence
|
|
|
|
GPL-3.0-or-later. See [LICENSE.md](LICENSE.md).
|