38 Commits

Author SHA1 Message Date
f38dec2ac4 Merge pull request 'ci(image): clean up after the image build and the deploy' (#50) from chore/ci-self-cleanup into main
All checks were successful
Build and publish the image / build (push) Successful in 1m37s
Build and publish the image / deploy (push) Successful in 10s
PR checks / checks (push) Successful in 2m42s
Reviewed-on: #50
2026-11-04 12:10:59 +00:00
080f9827b8 ci(image): clean up after the image build and the deploy
All checks were successful
PR checks / checks (pull_request) Successful in 3m41s
The build job runs docker on the runner host's daemon, so every run left
two tagged images behind for good. Remove this run's tags once they are
pushed and cap BuildKit's cache at 5 GB, always, never failing the job.

The deploy drops the dangling image its pull replaced on the rgcom host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-11-02 11:20:50 -06:00
7ac19a791c Merge pull request 'fix(app): turn the APK download back on for v0.7.0' (#49) from fix/apk-serviceable into main
Some checks failed
Build and publish the image / build (push) Successful in 3m55s
Build and publish the image / deploy (push) Successful in 13s
PR checks / checks (push) Failing after 14m24s
Reviewed-on: #49
2026-10-31 05:38:36 +00:00
b8306dcdaf fix(app): turn the APK download back on for v0.7.0
All checks were successful
PR checks / checks (pull_request) Successful in 2m30s
platform.json's androidApk.serviceable goes to true. It was false because
v0.5.0's build did not work. v0.7.0's released APK (SHA256 matches
SHA256SUMS) was installed on an Android 16 emulator, connected to the
public demo and read its Rust servers, so /app/ links the download again.

The comment beside the flag now says when it was last checked and to set
it back to false when `asset` moves to a release nobody has run. PLAN.md
D29 gets a dated note.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-31 00:21:46 -05:00
08a4973bde Merge pull request 'feat(app): quote Android v0.7.0, with report, block and hide and account deletion' (#48) from fix/android-v0.7.0 into main
All checks were successful
PR checks / checks (push) Successful in 2m39s
Build and publish the image / build (push) Successful in 4m12s
Build and publish the image / deploy (push) Successful in 37s
Reviewed-on: #48
2026-10-30 23:09:29 +00:00
8b8896f54b feat(app): quote Android v0.7.0, with report, block and hide and account deletion
Some checks failed
PR checks / checks (pull_request) Failing after 3m28s
Android-app v0.7.0 released 2026-10-30 (M8's cutover). platform.json
quotes it and its APK; /app/ gains the two things it added for a member
(report/block/hide on chat lines, and deleting the account), and the
Moderation docs name the app's long press beside the site's menu.

androidApk.serviceable is left false: it records a person having run
the build, and nobody has run v0.7.0's release APK on a phone yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-30 18:08:14 -05:00
e5ec81b172 Merge pull request 'fix(facts): quote 2026-10-30's releases, and the moderation that 1.21.0 brought' (#47) from fix/platform-facts-2026-10-30 into main
All checks were successful
PR checks / checks (push) Successful in 4m4s
Build and publish the image / build (push) Successful in 5m1s
Build and publish the image / deploy (push) Successful in 1m7s
Reviewed-on: #47
2026-10-30 22:31:46 +00:00
e0b2885cd7 fix(facts): quote 2026-10-30's releases, and the moderation that 1.21.0 brought
All checks were successful
PR checks / checks (pull_request) Successful in 5m26s
check:facts went red on seven facts after the day's releases: Module API
1.21.0, Module-Rust v0.7.0 (coreApi ^1.21.0), Module-uo v1.4.1,
Rust-Plugins v0.3.1, and the Rust bundle 2026.10.30 (plugin v0.3.1).
platform.json now quotes them, verified 2026-10-30.

Re-reading the pages that quote them: Module API 1.21.0 is report, block
and hide, so the Moderation page's Reports section described a queue
that no longer exists (forum-only, and "handling a report never touches
the content"). It now covers chat-line reports, the report snapshot,
Hide for everyone from the queue, and what members do for themselves
(Hide for me, Block, Account -> Blocked). The Rust docs' Feed row names
the chat-line menu. The app's menu is not mentioned: the app release
that carries it (v0.7.0) has not shipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-30 17:30:39 -05:00
c1b38081f5 Merge pull request 'fix(legal): declare report, block and hide in the app's data safety' (#46) from fix/play-data-safety-user-safety into main
Some checks failed
Build and publish the image / build (push) Successful in 1m41s
Build and publish the image / deploy (push) Successful in 10s
PR checks / checks (push) Failing after 3m5s
Reviewed-on: #46
2026-10-30 16:05:05 +00:00
dff4232491 fix(legal): declare report, block and hide in the app's data safety
Some checks failed
PR checks / checks (pull_request) Failing after 3m21s
The app now sends reports, blocks and hides (USER_SAFETY.md step 4,
Android-app#64). A new app row, app-safety, declares them: App activity ->
Other user-generated content (the report's note) and Other actions (the
report, block and hide themselves), collected, not shared, required. Other
actions moves from "not collected" to collected in PLAY_DATA_SAFETY.md.

The deployment row for posted content now says a report keeps a copy of
what it reported, and that blocks and hides are kept on the account and
deleted with it (user_blocks and user_hidden_items cascade).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-30 11:02:56 -05:00
caab3476eb Merge pull request 'feat(legal): /delete-account/, the page Google Play is given (D85, D86)' (#45) from feat/delete-account-page into main
All checks were successful
PR checks / checks (push) Successful in 2m22s
Build and publish the image / build (push) Successful in 2m49s
Build and publish the image / deploy (push) Successful in 10s
Reviewed-on: #45
2026-10-30 06:42:54 +00:00
70b31302b7 fix(facts): quote Module API 1.20.0 and Module-uo v1.4.0
All checks were successful
PR checks / checks (pull_request) Successful in 2m34s
check:facts was red on main after account deletion's core and module
steps merged: core's MODULE_API is 1.20.0, Module-uo declares coreApi
^1.20.0, and Module-uo released v1.4.0. Every page reads these from
platform.json, and none needed rewording. Folded into this PR by the org
lead's choice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-30 01:40:52 -05:00
094c606238 feat(legal): /delete-account/, the page Google Play is given (D85, D86)
Some checks failed
PR checks / checks (pull_request) Failing after -31s
Step 5 of docs/website/ACCOUNT_DELETION.md (§4.5). The page explains how
to delete an account on a community's site and in the app, what goes,
what stays and for how long, and who to ask when you cannot sign in. It
cannot delete anything, because we hold no account.

- The facts are one deployment row in collection.mjs (deletion.goes,
  .stays with a keep each, .staff), in the website's own words. /privacy
  section 3 renders it as prose, the page renders its lists, and
  PLAY_DATA_SAFETY.md prints them under the console's deletion questions.
- The app rows that a deletion touches (session, trust token, push,
  inbox snapshot) say so. The Data Safety notes now answer "yes" to
  account deletion and name the URL. lastUpdated is 2026-10-30.
- D85: linked from the footer's legal bar, /privacy sections 2 and 3,
  and /app/'s "Two ways to get it".
- D86: someone who cannot sign in is sent to their community's operator,
  never to us.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-30 01:25:48 -05:00
338cc6f3de Merge pull request 'fix(legal): declare what the app sends as collected, not shared (D84)' (#44) from fix/play-data-safety-collected into main
Some checks failed
PR checks / checks (push) Failing after -1m24s
Build and publish the image / build (push) Successful in 3m5s
Build and publish the image / deploy (push) Successful in 30s
Reviewed-on: #44
2026-10-29 22:30:29 +00:00
d6d5a70ed4 fix(legal): declare what the app sends as collected, not shared (D84)
All checks were successful
PR checks / checks (pull_request) Successful in 2m33s
Play counts data that leaves the device as collected, whoever runs the
server it lands on. The generated Data Safety notes answered "not
collected" because we run no server, which is true of /privacy and the
wrong answer to the form (org lead, 2026-10-29, Android PLAN.md M8).

An audit of the app's edge (every body, query and header in data/api/)
found more leaving the phone than section 2 listed. New rows: the
User-Agent, game-account links and creation, the Contact form, staff
posts and moderation, notification read state and preferences, search
text. The sign-in and trusted-device rows now say what is sent (the
credentials, the device's make and model).

- PlayMapping: a list of console types, plus required and purposes,
  checked against PLAY_DATA_TYPES / PLAY_PURPOSES (the first version
  filed "Other user-generated content" under Messages).
- The generator answers per data type, lists every type not collected,
  and answers the form's security questions.
- The premise test now asserts what is still true: nothing is shared.
- legal.lastUpdated moves to 2026-10-29 with /privacy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-29 08:20:25 -05:00
04e8c14d1f Merge pull request 'fix(facts): quote Module-Rust v0.6.3' (#43) from fix/facts-module-rust-063 into main
Some checks failed
PR checks / checks (push) Successful in 2m44s
Build and publish the image / build (push) Failing after 1h35m32s
Build and publish the image / deploy (push) Has been skipped
Reviewed-on: #43
2026-10-29 11:59:52 +00:00
bda4662a89 fix(facts): quote Module-Rust v0.6.3
All checks were successful
PR checks / checks (pull_request) Successful in 9m11s
check:facts was red on main: platform.json said Module-Rust v0.6.0 and
releases/latest says v0.6.3. v0.6.1 and v0.6.3 are demo-only fixes (DM26,
DM27; there is no v0.6.2) and still require MODULE_API ^1.19.0, so no
page's prose changes. Every page that shows the version interpolates it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-29 05:48:51 -05:00
fcc1a06361 Merge pull request 'feat(demo): list the demo's sign-ins on /beta and link into it per game' (#42) from feat/demo-live into main
Some checks failed
Build and publish the image / build (push) Failing after 3m41s
Build and publish the image / deploy (push) Has been skipped
PR checks / checks (push) Failing after 4m37s
Reviewed-on: #42
2026-10-29 10:12:41 +00:00
769d213c80 feat(demo): list the demo's sign-ins on /beta and link into it per game
Some checks failed
PR checks / checks (pull_request) Failing after 2m16s
The public demo (demo.runicgateway.com) is live, so the site's demo slot
can be switched on. Two decisions of record, PLAN.md §15:

- D82: /beta reads the demo's GET /api/v1/public/settings demo.logins on
  the server, caches it for a minute, and lists the published sign-ins
  with the next wipe. If the demo does not answer, /beta links to its
  sign-in page instead. Gate two reads as in place.
- D83: a deep link into a game module's pages carries data-demo-game, and
  applyBrand.mjs fills it only for games in the new mounted demoGames
  list. The Rust features gain links into /rust and /rust/servers/demo.
  UO's stay hidden on a Rust demo.

The public-demo not-built entry is removed, because its resolvedBy was met.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-28 15:32:34 -05:00
8701126d64 Merge pull request 'fix(docker): pin Node 22.23.4 for the image and CI (Node2Shell)' (#41) from fix/node22-node2shell into main
All checks were successful
PR checks / checks (push) Successful in 3m41s
Build and publish the image / build (push) Successful in 3m53s
Build and publish the image / deploy (push) Successful in 24s
Reviewed-on: #41
2026-10-27 17:49:06 +00:00
e7bbc250a5 chore(facts): Module API 1.19.0, Module-Rust v0.6.0
All checks were successful
PR checks / checks (pull_request) Successful in 5m58s
checkFacts turned this PR red on drift from the demo-mode merges, not on
the Node change: website main is at MODULE_API 1.19.0, Module-Rust main
declares coreApi ^1.19.0, and Module-Rust released v0.6.0. Every page
reads the three values from platform.json; verifiedOn moves to today.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-27 12:37:48 -05:00
d59c993430 fix(docker): pin Node 22.23.4 for the image and CI (Node2Shell)
Some checks failed
PR checks / checks (pull_request) Failing after 2m24s
CVE-2026-111497 ("Node2Shell") is an out-of-bounds write in Node's
bundled Brotli decoder, fixed on 2026-10-21 in 22.23.4. The image used
the floating node:22-bookworm-slim tag, so a cached or stale base could
still carry an older 22.x. Pin the patched version in both stages and in
the PR checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-26 10:01:49 -05:00
9b11c5cb99 Merge pull request 'chore(site): weapon names in the Rust shots; Android-app v0.6.0 and Module-Rust v0.5.1' (#40) from chore/rust-weapon-shots-and-versions into main
All checks were successful
PR checks / checks (push) Successful in 2m15s
Build and publish the image / build (push) Successful in 1m54s
Build and publish the image / deploy (push) Successful in 50s
Reviewed-on: #40
2026-10-23 07:35:45 +00:00
06a8892895 chore(facts): Android-app v0.6.0 and Module-Rust v0.5.1
All checks were successful
PR checks / checks (pull_request) Successful in 2m28s
Both were released on 2026-10-23. Android-app v0.6.0 is the cutover that
ships the Rust screens and the app's core wording (M20), and its APK asset
is runic-gateway-0.6.0.apk. Module-Rust v0.5.1 brings the weapon names in
the feed. verifiedOn moves to 2026-10-23, and checkFacts agrees on all 41
facts.

androidApk.serviceable stays false. It records a person's confirmation
that the published APK works, and nobody has run v0.6.0 against a real
site yet. A smoke test of the signed APK on the emulator covered install,
launch, the HTTPS rule and one TLS round trip, but no Runic Gateway site
serves HTTPS locally.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-23 02:32:59 -05:00
a918e9248e feat(screens): retake the Rust feed shots with weapon names
rust-feed (web) and app-rust-server (phone) showed the prefab names the
module printed before Module-Rust#60 ("with ak47u entity"). Both were
retaken from the Rust demo running that fix, after re-running
mockRustDemo.mjs so the feed's times are fresh. They now read "with
Assault Rifle", "with Thompson", "with MP5A4".

The phone shot was taken with the emulator in Pacific/Honolulu so that no
row crosses midnight and picks up a date; the timezone was restored
afterwards. The real Oxide rig has nobody on, so the server reads 0 of
40 online, and app-rust-server's alt now says "how many players are
online" rather than "six".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-23 02:06:19 -05:00
abf7dceb06 Merge pull request 'feat(site): phase 18 — the Rust screenshots, web and app' (#39) from feat/phase-18-screenshots into main
All checks were successful
PR checks / checks (push) Successful in 2m33s
Build and publish the image / build (push) Successful in 3m26s
Build and publish the image / deploy (push) Successful in 50s
Reviewed-on: #39
2026-10-23 03:09:15 +00:00
c47e9c1aa4 feat(site): phase 18 - the Rust screenshots, web and app
All checks were successful
PR checks / checks (pull_request) Successful in 2m55s
Nine captures tagged rust (D65): the server list, feed, leaderboard,
live map, permissions and the RunicNPC profile editor on the web, and a
server's feed, its map and the player's Rust account in the app, from
an Android-app edge debug build.

D80: every name in a capture is a role (admin, moderator, player...),
from this phase on. D81: the Rust demo's players are mock data written
by scripts/mockRustDemo.mjs; the server, its status, map, permission
groups and RunicNPC sync state are the real Oxide test server's. The
captions and /modules/rust/ and /app/ say which part is a demo cast.

seedDemo.mjs gains --game rust (server row with a weekly wipe, public
presence for the demo, two NPC profiles, a VIP group). captureScreens.mjs
gains a click list per screen. The homepage shows the Rust live map beside
the UO capture (D76); three Rust docs pages carry their screen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 22:05:06 -05:00
4f38e29ad7 Merge pull request 'feat(site): phase 17 — per-game module pages, /runicnpc/, and checkTerms over the built site' (#38) from feat/phase-17-marketing into main
All checks were successful
PR checks / checks (push) Successful in 2m26s
Build and publish the image / build (push) Successful in 3m0s
Build and publish the image / deploy (push) Successful in 53s
Reviewed-on: #38
2026-10-23 01:26:01 +00:00
56473d4d51 feat(site): phase 17 - per-game module pages, /runicnpc/, and checkTerms over the built site
All checks were successful
PR checks / checks (pull_request) Successful in 2m37s
PLAN.md §16 phase 17, built on the org lead's answers of 2026-10-22,
recorded as D75-D79 (count of record 79).

- D75: core marketing pages describe what a game module adds in core's
  words. "Game intelligence" became "What a game module adds"; each
  game's own list moved to src/data/games/ and renders only on the new
  /modules/uo/ and /modules/rust/. /modules/ is a card per game.
- The page-side capability check is per game (assertGameCoverage), the
  item phase 13 moved here.
- D76: the homepage keeps its game screenshot, labelled. screens.mjs
  entries may carry `game` (D67); Screenshot.astro and the app grid
  print the game's name and mark the figure data-game.
- D77: /app/ describes the Rust screens (released the same day).
- D78: /runicnpc/, the standalone page, is in the header and footer;
  the narrow header was re-measured so five links keep two rows.
- D79: checkTerms.mjs --built reads every built page's visible text
  after the build; game routes and data-game elements allow their
  game's words. Proven against ten plants. Still the twelfth check.
- Re-read fixes: /architecture/'s "two machines is also the maximum",
  Discord "guild" on /integrations/, and collection.mjs against what
  Steam sign-in and the Rust module keep (PLAY_DATA_SAFETY.md
  regenerated; the Play answers are unchanged).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 20:10:51 -05:00
ec65b2d5aa Merge pull request 'feat(docs): phase 16 — the RunicNPC subgroup, its API carried in full and drift-checked' (#37) from feat/phase-16-runicnpc into main
All checks were successful
Build and publish the image / build (push) Successful in 2m32s
PR checks / checks (push) Successful in 2m52s
Build and publish the image / deploy (push) Successful in 34s
Reviewed-on: #37
2026-10-22 21:07:54 +00:00
297cc83db5 docs(plan): record the Oxide floor ruling and the API.md table fix
All checks were successful
PR checks / checks (pull_request) Successful in 8m36s
The bundle's Oxide 2.0.7585 is the original compatible version and stays
until the CI staging drill reports an issue (org lead, 2026-10-22). The
API.md table break is fixed in docs #371.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 16:02:40 -05:00
ecc556d7ac feat(docs): phase 16 - the RunicNPC subgroup, its API carried in full and drift-checked
All checks were successful
PR checks / checks (pull_request) Successful in 2m11s
PLAN.md §16 phase 16, with the org lead's D72-D74 (count of record 74).

- Eight pages nested in the Rust group at /docs/rust/runicnpc/ (D72): the
  overview, Install RunicNPC, Commands, NPC profiles, NPC placements, Cost and
  caps, Profile fields (the one field reference the editor, rnpc.profile set,
  the data file and the API all share) and The API.
- The API page carries every call, hook and data shape (D62), in the site's
  own words, with no decision numbers and no per-call version history (D74).
  Signatures print from src/data/runicnpc.mjs through Signature.astro.
- checkReference.mjs gains two sections. Against docs main:runicnpc/API.md:
  the API version, 24 call and 10 hook signatures, and the field names of the
  profile, RunicNpc_List rows, placements, routes and owners (D73), plus
  exactly one <Signature> per call on api.mdx. Against runicnpc-rust
  main:plugin/RunicNPC.cs: console verbs, permissions, place options and
  config keys. Six planted drifts all failed before it was trusted.
- checkSidebar and checkTerms read nested sidebar groups via flatLabels().
- The Rust overview, Events zones and rewards, and Canonical documents link
  the new pages; the canonical documents gain the four runicnpc/ docs.

Both NPC admin screens were walked on the walk site first (D36); nothing was
saved. npm run verify is green.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 15:49:07 -05:00
fe86fc369d Merge pull request 'docs(plan): phase 15's other-repository findings are fixed' (#36) from docs/phase-15-followup into main
All checks were successful
PR checks / checks (push) Successful in 2m42s
Build and publish the image / build (push) Successful in 3m23s
Build and publish the image / deploy (push) Successful in 31s
Reviewed-on: #36
2026-10-22 20:32:25 +00:00
9b28c95305 docs(plan): phase 15's other-repository findings are fixed
All checks were successful
PR checks / checks (pull_request) Successful in 2m42s
PLAN.md §16 recorded three phase-15 findings as reported rather than
fixed. The org lead asked for them fixed the same day: Module-Rust #59
(24 decision numbers in admin copy, and "1 player holds one") and
Rust-Plugins #45 (EventsEnabled's comment). The record now says so.

Reading every EventsEnabled check for that comment also showed the
switch applies at once when saved from the site's config editor, while
the bridge's other settings wait for its next reload. RunicGateway.json
now says that, and adds paying coins to what the switch stops.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 15:31:45 -05:00
aad3a37c09 Merge pull request 'feat(docs): phase 15 — the Rust group, its reference pages checked against their sources' (#35) from feat/phase-15-rust into main
All checks were successful
PR checks / checks (push) Successful in 2m17s
Build and publish the image / build (push) Successful in 3m41s
Build and publish the image / deploy (push) Successful in 33s
Reviewed-on: #35
2026-10-22 20:26:31 +00:00
75c8ffc07a feat(docs): phase 15 - the Rust group, its reference pages checked against their sources
All checks were successful
PR checks / checks (pull_request) Successful in 2m5s
PLAN.md §16 phase 15. A Rust group of fifteen pages after Ultima Online
(D70): the module, installing the bridge (installer, Pterodactyl egg, by
hand), connecting the site, verifying the bridge, linking Steam accounts,
permissions and groups, mod config, who sees who is online, events, zones
and rewards, optional plugins, the live map, troubleshooting, and three
reference pages - rust-link's sidecar.toml, the plugin's
RunicGateway.json, and the event kinds.

checkReference.mjs gains three Rust sections rather than a new check:
sidecar.toml keys and RUSTLINK_* overrides from Rust-Link config.rs,
RunicGateway.json from the plugin's PluginConfig, and the event kinds
in three classes against Module-Rust server/catalogue.js (D71). Every
admin screen was walked on the walk site before it was described (D36).

Core pages now hand off to the Rust group instead of linking out to the
docs repository. Three defects the re-read found here are fixed: the UO
/health sample's hard-coded protocol 4 (both games' samples now render
platform.json through <Code>), Authentication's missing Steam tab, and
two pages saying the site cannot reach EventsEnabled - false on Rust.

Installer v0.8.1 moved checkFacts red mid-phase; platform.json follows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 15:23:07 -05:00
a100195e7b Merge pull request 'feat(docs): phase 14 — game-neutral core docs, an Ultima Online group, and checkTerms' (#34) from feat/phase-14-vocabulary into main
Some checks failed
Build and publish the image / build (push) Failing after -1m50s
Build and publish the image / deploy (push) Has been skipped
PR checks / checks (push) Successful in 8m56s
Reviewed-on: #34
2026-10-22 19:41:17 +00:00
4426d3e339 feat(docs): phase 14 - game-neutral core docs, an Ultima Online group, and checkTerms
All checks were successful
PR checks / checks (pull_request) Successful in 2m10s
PLAN.md §16, D63/D64, plus D67-D69 taken 2026-10-22.

- Core docs use core's words: a Team, a game server, the sidecar, the bridge
  plugin, the game module. Detail that belonged to Ultima Online moved into
  its pages rather than being dropped.
- New "Ultima Online" sidebar group (nine pages): an overview, Connect a
  ServUO shard, Verify the bridge, The shard connection, Client files,
  Troubleshooting, Bridge.cfg, sidecar.toml, Shard event catalog. Five moved
  URLs answer a real 301 (src/config/redirects.mjs, asserted by the served
  test).
- Getting started is game-neutral. "Connect your game server" keeps the old
  URL and hands off to each game; Rust links docs main:rust-link/INSTALL.md
  until phase 15. "Verify the whole stack" stays, neutral (D69).
- D68: GameExample.astro labels a game's real example on a core page with the
  game's name; checkTerms allows that game's words inside it.
- scripts/checkTerms.mjs, the twelfth check: 16 game words, docs pages and
  both sidebar trees, one allowlisted phrase (Discord's "Guild (server) ID").
  Wired into verify and pr-checks.yml.
- canonicalDocs grouped by game; the Rust group carries four documents.
- D67: the screenshot rule from #32 is adopted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 08:54:37 -05:00
137 changed files with 9753 additions and 1173 deletions

View File

@@ -157,6 +157,21 @@ jobs:
docker push "${IMAGE}:latest"
docker push "${IMAGE}:${TAG}"
- name: Remove this run's image and cap the build cache
# The build runs on the HOST daemon, so whatever it leaves stays on the
# runner host for good: every run used to leave two tagged images, and
# each newer `latest` turned the previous one into a permanent `sha-` image
# until the host ran out of disk. Both tags are in the registry by now, so
# the local copies are dead weight. BuildKit keeps its layer cache apart
# from the images, so the next build stays fast; the cache is pruned to a
# cap instead of growing forever (`--reserved-space` is the same flag's
# name on newer Docker). Runs even after a failure, and never fails the job.
if: always()
run: |
docker image rm "${IMAGE}:latest" "${IMAGE}:${TAG}" 2>/dev/null || true
docker builder prune -f --keep-storage 5GB \
|| docker builder prune -f --reserved-space 5GB || true
- name: Log out
if: always()
run: docker logout "${REGISTRY}" || true
@@ -207,3 +222,11 @@ jobs:
echo "::error::The site did not become healthy within 150s."
docker compose logs --tail 100 site
exit 1
- name: Remove the image this deploy replaced
# The pull moves `latest` to the new image and leaves the old one untagged
# on the host. Untagged images are never used again (a rollback pulls a
# `sha-` tag from the registry), so drop them. Dangling images only: nothing
# tagged and nothing a container is using is touched.
if: always()
run: docker image prune -f || true

View File

@@ -22,7 +22,7 @@ jobs:
- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: '22'
node-version: '22.23.4'
cache: npm
- name: Install
@@ -78,6 +78,16 @@ jobs:
# No token, no network, no build — so it runs early and fails fast.
run: npm run check:sidebar
- name: Game vocabulary
# PLAN.md §16, D63/D64 — the twelfth check, phase 14. The site may NAME the games it
# supports anywhere, but a game's vocabulary (shard, guild, clan, uo-link, Oxide…)
# belongs in that game's own docs group, its sidebar group, or a <GameExample> block
# that labels it (D68). Core pages use core's words: a Team, a game server, the
# sidecar, the bridge plugin, the game module.
#
# No token, no network, no build — so it runs early and fails fast.
run: npm run check:terms
- name: Screenshots
# PLAN.md §12, phase 9 (D45). src/data/screens.mjs is the one list of what the site
# shows of itself: every entry must have a file, at the size the markup declares, and
@@ -105,6 +115,17 @@ jobs:
# fails because some other host is slow is a check people learn to ignore.
run: npm run check:links
- name: Game vocabulary in the built pages
# PLAN.md §16, D79 — phase 17 widened the twelfth check to the whole site. The
# marketing pages are templates fed from src/data/, so the words a reader sees are
# mostly not in any source file: a capability label, a screenshot caption, a value
# from platform.json. This pass reads every built page's visible text, alt, title and
# aria-label, the way check:links reads its hrefs. A game's routes, and elements
# marked data-game (<GameExample>, a game-tagged screenshot), allow that game's words.
#
# Still the twelfth check, not a thirteenth: the same script, the same word list.
run: npm run check:terms:built
- name: Platform facts
# PLAN.md §12 — every version, protocol number and bundle tag is re-read from
# its authority over the Gitea API and must agree with src/data/platform.json.

View File

@@ -57,7 +57,7 @@ absent `brand/` produces exactly the stock site, and `data/` is created on first
## The checks
There are eleven, plus two test suites. `npm run verify` runs all of them in dependency order, and
There are twelve, plus two test suites. `npm run verify` runs all of them in dependency order, and
that is what CI does on every pull request.
```bash

View File

@@ -244,7 +244,7 @@ recolours the site and leaves every logo alone. `PLAN.md` §7 is the full accoun
```
brand/
brand.json Site name, tagline, contact address, Discord invite, Gitea org,
demo URL, Play opt-in URL
demo URL and the games it runs, Play opt-in URL
logo.png ONE raster. Every size the site asks for — header at three pixel
ratios, install icons, apple-touch, favicons, a real .ico — is
derived from it on demand
@@ -264,6 +264,14 @@ mounted site name has to reach forty-nine pages that were rendered before the fi
day the Play closed test opens, pasting the URL into `brand/brand.json` puts a working link on the
confirmation screen on the very next request.
**The public demo** is two fields. `demoUrl` shows the homepage's "See it running" button and the
core features' links into it; `demoGames` lists the game modules it runs (`["rust"]` for
`demo.runicgateway.com`), and only those games' links show. Both need the restart. `/beta` also
reads `demoUrl` live: it fetches the demo's published sign-ins from
`<demoUrl>/api/v1/public/settings` and lists them, so the container must be able to reach the
demo's public address. If it cannot, `/beta` links to the demo's sign-in page instead and logs
`[beta] could not read the demo's sign-ins`.
To see which source answered a given asset:
```bash

View File

@@ -15,7 +15,7 @@
# ---------------------------------------------------------------------------------------
# Stage 1 — build
# ---------------------------------------------------------------------------------------
FROM node:22-bookworm-slim AS build
FROM node:22.23.4-bookworm-slim AS build
WORKDIR /build
@@ -54,7 +54,7 @@ RUN mkdir -p /split \
# ---------------------------------------------------------------------------------------
# Stage 2 — runtime
# ---------------------------------------------------------------------------------------
FROM node:22-bookworm-slim AS runtime
FROM node:22.23.4-bookworm-slim AS runtime
WORKDIR /app

534
PLAN.md
View File

@@ -1,6 +1,6 @@
# runicgateway.com — design of record
**Status:** phases 0–12 are built and deployed. **Revision 4 (2026-10-22) plans phases 13–18** —
**Status:** phases 0–14 are built (13 and 14 as part of revision 4). **Revision 4 (2026-10-22) plans phases 13–18** —
the second game, RunicNPC, and taking game vocabulary out of the site at large — in §16.
**Date:** 2026-08-19 (revision 3) · 2026-10-22 (revision 4)
**Repo:** `RunicGateway/runicgateway.com`
@@ -232,12 +232,12 @@ Taken by the org lead (Colby Whitlock) on 2026-08-19. Recorded so they are not r
| **D9** | **No analytics.** No tracking scripts, no third-party requests, no cookie banner. | Reverse-proxy access logs are the only traffic data. |
| **D10** | **Support routes to Discord and Gitea issues.** Invite: `https://discord.gg/t2Jav8yT4g`. | §10. Discord is the front door; Gitea takes issues from anyone with an account, which today is nobody outside the org — §14, N3. |
| **D11** | **Keep the existing emblem.** `runic-emblem.png` is the mark on both the website and the Android launcher icon; the site adopts it rather than drawing a new one. | §11. Revision 1's "draw a new geometric mark" recommendation is withdrawn. |
| **D12** | **A public demo instance is planned but out of scope today** — a Proxmox VM running the full stack including ServUO, with restricted settings and an hourly automatic reset. | §15. The IA reserves the slot so it lands later without a restructure. |
| **D12** | **A public demo instance is planned but out of scope today** — a Proxmox VM running the full stack including ServUO, with restricted settings and an hourly automatic reset. | §15. The IA reserves the slot so it lands later without a restructure. **Built 2026-10-27** as `demo.runicgateway.com`, on Rust with a two-hour reset; the site reaches it through D82 and D83 (§15). |
| **D13** | **Publish the existing address.** No mailbox has been created at the domain and the org lead elected not to wait for one: `whitlocktech@gmail.com` is the published contact wherever the site needs one — `/privacy`, `/terms`, `/community`, the Play listing — and `docs/SECURITY.md` keeps the address it already carries. | Taken 2026-08-19, superseding §14 N2 as a blocker. The address lives **only** in `brand.json` (§7), never in prose, so moving to `privacy@`/`security@` later is a file edit and a restart. Phase 0's PR 0.10 is withdrawn, not deferred. |
**Decisions after D13 are recorded where they were taken**, in the section describing the phase that
raised them, rather than appended here — a decision is only re-litigated when its reasoning is
somewhere other than the thing it decided. The count of record is **sixty-six**:
somewhere other than the thing it decided. The count of record is **eighty-four**:
| # | Where | What it settled |
|---|---|---|
@@ -256,6 +256,15 @@ somewhere other than the thing it decided. The count of record is **sixty-six**:
| D59 | §6, "How phase 12 delivered it" | The container publishes on every interface (amending D55), with `SITE_BIND_ADDR` to narrow it |
| D60–D65 | §16, "The six decisions" | Per-game sidebar groups, RunicNPC inside Rust with its own page, the RunicNPC API carried in full with a drift check, game names allowed but game vocabulary confined, a twelfth check that enforces it (amending D53), Rust screenshots last and from the rigs |
| D66 | §16, "How phase 13 built it" | The hero and footer show the Module API only; a protocol and a bundle belong to a game |
| D67 | §16, "One rule the phases need" | A screenshot belongs to its game: a capture tagged with a game may carry its words, beside the game's name |
| D68–D69 | §16, "How phase 14 built it" | A game's real example on a core page is a tagged, labelled block; *Verify the whole stack* stays in Getting started, game-neutral (amending D60) |
| D70–D71 | §16, "How phase 15 built it" | The Rust group is fifteen pages, one per admin screen where it can be; the Rust event kinds are checked against the module's own classification |
| D72–D74 | §16, "How phase 16 built it" | The RunicNPC subgroup is eight pages with a shared profile-field reference; the API check compares signatures and every data shape's field names; the site's API page carries the current API only, with no decision numbers and no version history |
| D75–D79 | §16, "How phase 17 built it" | Core marketing pages describe what a game module adds in core's words and link to each game's page; the homepage keeps its game screenshot, labelled; `/app/` describes the Rust screens, released the same day; `/runicnpc/` is in the header; `checkTerms.mjs` gains a pass over the built pages |
| D80–D81 | §16, "How phase 18 built it" | A name in a screenshot is a role; the Rust captures' players are mock data |
| D82–D83 | §15, "How the site reaches it" | `/beta` lists the demo's sign-ins as the demo publishes them; a demo deep link names its game and shows only for the games the mounted `demoGames` lists |
| D84 | §9, "How phase 6 built the legal pages" | The Data Safety answers say "collected, not shared" for everything the app sends, amending D33 |
| D85–D86 | §9, "`/delete-account/`" | The deletion page is linked from the footer, `/privacy` and `/app/`; someone who cannot sign in is sent to their community's operator, never to us |
---
@@ -947,6 +956,8 @@ deliberately so — no fetch can tell whether an APK runs. `checkFacts.mjs` asse
still exist and that `minSdk` still says what "Android 10 or newer" claims, so the link is correct
the moment a working build flips the boolean. The panel is not removed while the link is off: a page
that omitted sideloading would read, to somebody who knows the APK exists, as a page hiding it.
*(2026-10-31: the link is back on. Android `v0.7.0`'s APK was installed on an Android 16 emulator,
connected to the public demo and read its Rust servers, so `serviceable` is `true`.)*
**Three mechanisms this phase added that the plan did not anticipate.**
@@ -1061,6 +1072,51 @@ not shared"**, failing with the reason rather than a diff: "we operate no server
is the premise of the whole section, and a telemetry endpoint added later must not be able to
produce a row that quietly contradicts the lede three inches above it.
**D84 — The Data Safety answers say "collected" for everything the app sends** (org lead,
2026-10-29, Android `PLAN.md` M8; amends D33). Play counts data that leaves the device as
collected, whoever runs the server it lands on, so "not collected because we run no server" was the
wrong answer to the form's question even though it is the right sentence for `/privacy`. An audit of
the app's `edge` (every Retrofit body, query and header in `data/api/`) found more leaving the phone
than section 2 listed: the sign-in itself, the device's make and model on a trusted-device request,
the User-Agent, game-account links and in-app game-account creation, the Contact form's name, email
and message, staff posts and moderation, notification read state and preferences, and search text.
Each is now a row, declared **collected, not shared, encrypted in transit, required**; the rows
that stay on the phone say so and carry no console type. `PlayMapping` takes a list of `types`
(checked against `PLAY_DATA_TYPES`, the console's own vocabulary, which caught the original file
filing "Other user-generated content" under Messages), `required` and `purposes`; the generator
folds rows into one answer per data type, lists every type that is not collected, and answers the
form's security questions. D33's test now asserts the part of the premise that is still true:
**nothing is shared**. `/privacy` section 2 keeps saying none of it reaches us, and `lastUpdated`
moved with it. Report, block and hide (Android M8 step 3) adds its rows when it lands.
### `/delete-account/` (2026-10-30)
Play needs one account-deletion address from whoever publishes the app. The platform gained
self-service deletion on the website and in the app (`docs/website/ACCOUNT_DELETION.md`, AD1), and
this page is the address Play is given (AD2, §4.5 there). It cannot delete anything: we hold no
account, so it explains where the button is in the app and on the website, what goes and what stays
and for how long, and who to ask when you cannot sign in.
**The facts are one row.** What a deletion takes is the `deploy-account-deletion` row in
`src/data/collection.mjs`, whose `deletion` field holds the website's own words for what goes and
what stays (`client/src/lib/accountDeletion.js`, which the app's strings repeat) plus how long each
kept thing is kept, which Play asks and the screens do not say. `/privacy` section 3 renders the row
as prose, the page renders its lists, and `PLAY_DATA_SAFETY.md` prints them under the console's
deletion questions, so the three cannot disagree. `deletionRow()` throws when the row is missing,
and `test/legal.test.mjs` fails a kept entry with no retention. The app rows that deletion touches
(the session, the trust token, push and the inbox snapshot) say so, and `lastUpdated` moved.
**D85 — The page is linked from the footer, `/privacy` and `/app/`** (org lead, 2026-10-30). The
footer's legal bar reads Privacy · Terms · Delete account, because a player looking for it looks
where the privacy link is; `/privacy` sections 2 and 3 and the bottom of `/app/`'s "Two ways to get
it" link to it as well.
**D86 — Someone who cannot sign in is sent to their community's operator, never to us** (org lead,
2026-10-30). The page offers "Forgot your password?" first, which works when the account has an
email address and the site can send mail, and then the operator, who can delete any account from the
admin panel. It says plainly that we cannot do it: we hold no account and have no access to any
community's site. Offering our contact address to help find an operator was considered and declined.
**What phase 6 also closed.** `/privacy/` and `/terms/` were the last two entries in
`checkLinks.mjs`'s `PLANNED_ROUTES`; building them emptied the list, and its reverse check is what
forced the deletion. The list itself stays, because §10's documentation routes land in phases 7 and 8
@@ -1086,6 +1142,7 @@ Organised by what a reader is trying to do. A reader should never need to know t
| `/beta/` | The closed-beta signup (§8). The one page that handles its own POST (D28) |
| `/community/` | Discord (`discord.gg/t2Jav8yT4g`) as the front door, the Gitea org for code and contributions, the `brand.json` contact address for vulnerabilities (D13) — the split in §14 N3 |
| `/privacy/`, `/terms/` | §9 |
| `/delete-account/` | §9: how to delete an account you use in the app, and what it keeps. The address Play is given (D85, D86) |
**Feature grouping**, using project terminology:
@@ -1669,6 +1726,12 @@ a mechanism rather than diligence:
reflows while it decodes. No browser and no game server — the capture tool is an authoring
script whose output is committed, exactly like the brand assets.
- **`scripts/checkTokens.mjs`** — no colour literal outside the token file (§7).
- **`scripts/checkTerms.mjs`** — added in phase 14 for D63 and D64, the twelfth check. No game's
vocabulary outside that game's section: its docs group, its sidebar group, or a
`<GameExample>` block (D68). Reads the docs and both sidebar trees before the build; since
phase 17 (D79) a second pass, `--built`, reads every built page's visible text after it, so
the marketing pages and the words their data renders are covered too. A game's own routes, and
an element marked `data-game`, allow that game's words.
- `astro check` plus a production build, in CI on every PR.
---
@@ -1796,9 +1859,56 @@ whether or not N3 is actioned; only one sentence changes.
---
## 15. Planned, not in scope: the demo instance
## 15. The demo instance
D12. Recorded now so the IA reserves room for it and nothing has to be restructured later.
D12. Recorded on 2026-08-19 so the IA reserved room for it and nothing had to be restructured
later. **It exists now:** `https://demo.runicgateway.com`, built in `website` and live since
2026-10-27. Its design of record is `docs/website/DEMO_MODE.md` (DM1-DM29), not this section, and
it came out different from the plan below in three ways that matter to this site:
- **It runs Rust, not Ultima Online.** The site is the normal `website` image with the Rust module,
linked to the org's Oxide test server. So the `/uo/…` deep links D25 wrote have nothing to open
there.
- **It resets every two hours, not hourly, and not by reverting a VM.** A scheduled workflow
restores the game server from a baseline, recreates the site's database, and seeds it again
(`DEMO_MODE.md` §7). The banner gives the next reset in UTC.
- **Its sign-ins are generated on its host.** The passwords exist only in the demo's own `.env`
and in what the demo publishes: with `DEMO_MODE` on, `GET /api/v1/public/settings` answers
`demo.logins`, which is what its sign-in page lists.
### How the site reaches it (2026-10-28)
`DEMO_MODE.md` §10 step 6 says "runicgateway.com `/beta` publishes the logins". The org lead took
two decisions to do that:
**D82 — `/beta` lists the demo's sign-ins as the demo publishes them.** With `demoUrl` mounted,
`/beta` (already rendered per request) reads the demo's `GET /api/v1/public/settings` on the
server, caches the answer for a minute, and lists each `demo.logins` row with the next wipe
time. A copy pasted into `brand.json` was the alternative, and it is one regenerated `.env` away
from publishing passwords that do not work. The read is this server's, not the visitor's, so D9
and the CSP are unchanged. It never fails the page: the demo is down for a few minutes at every
wipe, and then (or after 1.5 seconds without an answer) `/beta` links to the demo's own sign-in
page instead, and asks again 15 seconds later. Every field is shape- and length-checked before
it is rendered. Gate two ("somewhere to point it") reads as in place, with the demo's host name
to type into the app's first screen. `lib/demoLogins.mjs` holds it; `test/demo.test.mjs` tests it.
**D83 — a demo deep link names its game, and shows only for the games the demo runs.** A link
into a game module's pages carries `data-demo-game` after `data-demo-path`. A new mounted list,
`demoGames` (stock `[]`), names the modules the demo runs, and `applyBrand.mjs` fills a game's
links only for a game listed there. Core's links (`/wiki`, `/site/events`, `/site/news`) carry no
game and follow `demoUrl` alone. The Rust features gain links into the demo's server page
(`/rust`, and `/rust/servers/demo` with its `?tab=` for the feed, leaderboard, online, map,
wipes and clans). `demo` is the server's id, fixed by the demo's seed fixture. UO's links stay
in the markup and stay hidden, so a UO demo later is one more entry in the list. `checkBrand.mjs`
holds `demoGames` to the games in `games/index.mjs` and checks that `DEEP_LINK` reads the game.
The `public-demo` entry in `notBuilt.mjs` is gone, because its `resolvedBy` was met.
**What the operator mounts:** `"demoUrl": "https://demo.runicgateway.com"` and
`"demoGames": ["rust"]` in the site's `brand.json`, then a restart. `/beta` follows `demoUrl` on
the next request; the prerendered pages follow both at the restart.
### The plan as written (2026-08-19)
**Shape:** a VM on the org lead's Proxmox host running the full stack — website, `module-uo`, the
uo-link sidecar and a real ServUO shard — so an evaluator clicks one link and sees the actual
@@ -1925,7 +2035,9 @@ screen and the NPC profile editor.
### One rule the phases need, recorded so review can object
**A screenshot belongs to its game.** Phase 9's UO captures carry the word "Shard" in the pixels and
Adopted by the org lead on 2026-10-22 as **D67**.
**D67 — A screenshot belongs to its game.** Phase 9's UO captures carry the word "Shard" in the pixels and
in their alt text. Alt text has to describe the image honestly, so a capture tagged with a game in
`screens.mjs` may use that game's words in its caption and alt. The page showing it must name the
game next to it. `checkTerms.mjs` reads the tag. The homepage's "What it looks like" therefore either
@@ -2022,6 +2134,416 @@ cover, and phase 17 is the phase that writes that list. Phase 13 does the half t
check: `checkFacts` now holds Module-Rust's declared capabilities against `platform.json`, so a
capability the module adds turns this repo red today. The page-side assertion lands with the page.
### How phase 14 built it
Three decisions, taken on 2026-10-22 when the restructure reached pages D60 had not placed. The
count of record is now **sixty-nine**. D67 is the screenshot rule above, adopted that day.
**D68 — a game's real example on a core page is a tagged, labelled block.** Some core pages need
a real example rather than an invented one: *The module manifest* shows a manifest, *Scheduled
events* names a module's budget dimensions, and the *Installer CLI* has to print
`--game <servuo|rust>`, because that is the flag. §1 prefers the real thing, since an invented
example is checked by nothing. So the example keeps its game's words and says whose they are:
`src/components/GameExample.astro` prints the game's name above the block, read from
`platform.json` so the label cannot disagree with the attribute, and `checkTerms.mjs` allows that
game's words, and only that game's, between the tags. It is D67's bargain applied to text: a
game's words are honest on a core page when the game is named right beside them. The
alternatives were an invented neutral example (the Integration Kit's template could not serve: it
mounts `/clans`) and prose only, which would have left the core pages less concrete.
**D69 — *Verify the whole stack* stays in Getting started, game-neutral.** This amends D60, which
had Getting started end on the hand-off page. The core page now teaches the four links in the
chain — the plugin loaded, the game server reached the sidecar, the sidecar is healthy, the site
is ingesting — which are the same for both games, and sends the reader to their game for the
commands. The Ultima Online commands became that group's *Verify the bridge*. The Ultima Online
host requirements moved onto *Connect a ServUO shard*, and the Ultima Online rows of
*Troubleshooting* became the group's own *Troubleshooting* page.
**What moved, and what stayed.** The Ultima Online group has nine pages: an overview (*The Ultima
Online module*, which took *Install a game module*'s "what the `uo` module adds"), *Connect a
ServUO shard*, *Verify the bridge*, *The shard connection*, *Client files*, *Troubleshooting*,
*Bridge.cfg*, *sidecar.toml* and the *Shard event catalog*. Five pages changed URL, and each old
URL answers with a real `301` from the server: `src/config/redirects.mjs`, asserted by
`test/headers.test.mjs`. *Connect a game server* did **not** move. Its URL is now the
game-neutral hand-off page (*Connect your game server*), which is a better landing for an old link
than a redirect into one game. Until phase 15, its Rust row links to `docs`
`main:rust-link/INSTALL.md`.
**The core pages use core's words** (D63): a Team, a game server, the sidecar, the bridge plugin,
the game module. Detail that was really one game's moved into that game's pages rather than being
dropped. *The bridge*'s guild-roster passage, for example, is now a general rule about Team rosters,
with the Ultima Online specifics in its event catalog. Three passages were checked against Rust before they were
generalised: both bridges dial loopback newline-delimited JSON with one writer thread, both
sidecars answer `/health` with *plugin connected*, both plugins ship `EventsEnabled` off, and
both modules encrypt their sidecar token with core's key. `canonicalDocs` is now grouped by
game, and the Rust group carries four documents. Discord's *guild* became *Discord server*
everywhere except the one label core's Discord Bot screen really prints, *Guild (server) ID*,
which is the check's only allowlist entry, as D64 predicted.
**`checkTerms.mjs` is the twelfth check.** It reads every docs page, frontmatter included, and
both sidebar trees as data. It knows 16 words, each tagged with its game. Link targets, bare URLs,
imports and `{…}` expressions are not read, because an address is not prose and an expression
renders a value from `src/data/`, which phase 17 brings into scope. Fenced code is read. An
allowlist entry that stops matching fails the check, so the list cannot rot. Before it was
trusted it was run against a planted page: five violations (a word in prose, in a title, in link
text, in a code fence, and inside another game's block) all failed, and a URL and an expression
carrying the same words both passed.
**Two findings outside this repository**, reported rather than fixed (they belong to other
repositories):
- **Core's own Teams panel says "shard".** `website` `client/src/lib/teamAdmin.js` tells an
administrator the list "is not a confirmed empty shard". The docs page now paraphrases it
rather than quoting it.
- **The installer's `--help` says "Which game's shard side"** for `--game`, and `--site-url` names
"Admin → Shard (uo-link)" for both games.
### How phase 15 built it
Two decisions, taken by the org lead on 2026-10-22 before any page was written. The count of
record is now **seventy-one**.
**D70 — the Rust group is fifteen pages.** D60 named the topics and not the pages. The group
follows the Ultima Online group's shape: an overview, then the journey (*Install the bridge*,
*Connect the site*, *Verify the bridge*), then one page per admin screen where there is one
(*Permissions and groups*, *Mod config from the site*, *Who sees who is online*, *Events, zones
and rewards*), then *Linking Steam accounts*, *Optional plugins*, *The live map* and
*Troubleshooting*, and three reference pages (*sidecar.toml*, *RunicGateway.json*, *Event
kinds*). *Who sees who is online* and *Optional plugins* got pages of their own rather than
being folded into the overview and the events page, because each has a screen or a trap of its
own — RaidableBases must be restarted, never reloaded. The alternative was ten longer pages. The
question put to the org lead called this option "14 pages" while listing fifteen; the list is
what was chosen. RunicNPC's subgroup is phase 16's.
**D71 — the Rust event kinds are checked against the module's classification.** The plan said the
protocol-14 event list would be checked "against its sources". There were two candidates:
`PROTOCOL.md`, whose kinds are spread across tables from §8.4 to §20.12, and `Module-Rust`
`server/catalogue.js`, which holds three lists in code — public, staff, and the presence subset
of public. The second was chosen, for D39's reason: the visibility ladder is checked against the
module that enforces it, and so is this. The module's own test already holds its lists to
`PROTOCOL.md`, so the chain reaches the spec without this repo parsing prose tables. The page
shows three classes, and each is compared separately, so a kind moving from staff to public
upstream fails here twice.
**`checkReference.mjs` gained three Rust sections**, as the plan said, rather than a new check:
rust-link's `sidecar.toml` (parsed from its serde structs by the same function as uo-link's, now
shared) and the six `RUSTLINK_…` variables that override it; the bridge plugin's
`RunicGateway.json`, read from the public fields of `PluginConfig` in `RunicGateway.cs`; and the
event kinds (D71). The canonical documents gained `OPERATING.md` and `CARBON.md` under Rust.
**Every admin screen was walked on the walk site first** (D36), signed in as the walk admin:
Rust servers (Test, Edit, Chat titles, Optional mods), Rust permissions (a player, a group's four
tabs), Rust mod config (the tree and `RunicGateway.json`'s read-only keys), Rust visibility, Rust
zone presets, the event editor's action list, a user's Rust section, and the public server page's
feed, map and leaderboard. Nothing was saved. The NPC screens are phase 16's. Writing from the
walk and the source corrected three of my own drafts before they shipped: a reward does **not**
need a linked account (rewards go to Steam ids), the bundle ships **three** helpers, not two, and
the Test button prints the raw status (`protocol-mismatch`), not a phrase.
**What the re-read found in this repository**, fixed here:
- ***Verify the bridge* (Ultima Online) showed `"protocol":4`** in its `/health` sample, a
hard-coded version four protocols stale. Both games' samples now render the protocol from
`platform.json` through Starlight's `<Code>`, which is how a version gets into a code block
without being typed.
- ***Authentication* said "four tabs"** and never mentioned Steam, which core shipped with Module
API 1.17.0. It now has five, and a *Steam* section the Rust pages link to.
- ***Scheduled events* and *Events architecture* said the site cannot reach `EventsEnabled`.**
True for Ultima Online, false for Rust: an administrator can edit `RunicGateway.json`, that switch
included, from Admin → Rust mod config. Both pages now say so, the first as two tagged examples
(D68).
**`checkFacts` went red mid-phase, as designed.** Installer v0.8.1 shipped on 2026-10-22 — the
game-neutral `--help` that phase 14 reported, fixed in `installer` #43 alongside `website` #221 for
the Teams panel — so `platform.json` moved to it. Its only change is that help text, which no page
quotes.
**Findings in other repositories.** Reported in the PR, and then fixed at the org lead's ask the
same day, each in its own repository's PR into `edge`:
- **`Module-Rust` admin copy showed decision numbers.** A group's *Servers* tab read "unless it is
shared (D189)", and the *not imported yet* chip's tooltip ended "(D198)". A search of every
non-comment line found **24** such strings an administrator reads — the event editor's step and
budget descriptions and five NPC validation errors among them. All went in `Module-Rust` #59; the
developer-facing swagger descriptions keep theirs.
- **`Module-Rust`'s servers page read "Last pushed: 1 player hold one."** Also `Module-Rust` #59.
- **`Rust-Plugins`' `PluginConfig.EventsEnabled` comment said it "gates taking a lease only"**,
which stopped being true at protocol 9. It now lists everything the switch gates, read from every
check in the file: `Rust-Plugins` #45.
- **`docs` `rust-link/INTEGRATION.md` predates the installer**: it says there is no installer
support for Rust and shows protocol-1 samples. **`rust-link/INSTALL.md`'s by-hand step names two
helpers**; the bundle ships three. The org lead approved a separate `docs` PR for these:
`docs` #370.
### How phase 16 built it
Three decisions, taken by the org lead on 2026-10-22 before any page was written. The count of
record is now **seventy-four**.
**D72 — the RunicNPC subgroup is eight pages, one of them a shared profile-field reference.** D61
named five topics. The subgroup sits at the end of the Rust group, nested, at
`/docs/rust/runicnpc/`: *RunicNPC* (the overview), *Install RunicNPC*, *Commands*, *NPC profiles*,
*NPC placements*, *Cost and caps*, *Profile fields* and *The API*. The site's two NPC screens get a
page each, as the Rust group's screens do, and the cost warning and caps get their own page rather
than a section of *Install*. ***Profile fields* is the one page every way of writing a profile
links to**: the site's editor (whose sections it follows, with each field's label), `rnpc.profile
set` (which takes the same JSON paths), the data file, and the API. So the API page shows calls,
hooks, placements and routes, and links there for a profile's shape rather than repeating it. The
alternatives were D61's five pages, and seven without the shared reference.
**D73 — the API check compares signatures and field names.** D62 named calls, hooks and
signatures. The check also compares the field names of every data shape `API.md` gives: a
profile's fields, `RunicNpc_List`'s keys, a placement's keys, a route's keys, and the owners. A
field added to the profile upstream turns this site red the same way a new call does. The
alternative, calls and hooks only, would have let the largest and most-changed shape drift
unnoticed.
**D74 — the site's API page carries the current API only.** `API.md` explains itself with decision
numbers (*D258, D269*) and plan stages, and tags each call with the API version that added it. The
site page drops both. Decision numbers mean nothing to a plugin author outside this project — the
reason `Module-Rust` #59 removed them from the admin screens — and the version history is
`API.md`'s to keep. The page states the current API version, read from `platform.json`, and shows
how to check it before calling. The alternatives were keeping the "since API n" tags, and copying
`API.md` faithfully, decision numbers included.
**The drift check is two sections of `checkReference.mjs`**, so the count of checks stays at
twelve, as the plan said:
- **Against `docs` `main:runicnpc/API.md`**, through the `contents` endpoint: the API version
against `platform.json`; all 24 calls by whole signature, parsed from their headings; all 10
hooks by signature, from their table; and the field names of the five shapes (D73). A profile
field cell that names two fields (`hurtByPlayers`, `hurtsPlayers`), or a bare name after a dotted
one (`phases[].damageDealt`, `aimCone`), is read the way a person reads it. And the page itself:
every call must have exactly one `<Signature call="…" />` on `api.mdx`, so "carried in full" is
held by the build, not by whoever last edited the page.
- **Against `runicnpc-rust` `main:plugin/RunicNPC.cs`**: the console verbs it registers, the
permissions it registers (and that every command's permission is one of them), the `key=`
options `ParseOptions` accepts, and the JSON keys of its config classes. These are names on the
*Commands* and *Cost and caps* pages, and §12 has checked every name the Reference pages write
since phase 8. D62 did not ask for this half; it is the phase-15 precedent (the bridge plugin's
`RunicGateway.json` is read from its source the same way) applied to the two new pages that list
names.
Signatures print from `src/data/runicnpc.mjs` through `src/components/Signature.astro`, which
renders them with Starlight's `<Code>`, so the signature a reader copies is the one the check
compared. Descriptions live beside them as short strings, written in the site's words, and
`src/components/Ticks.astro` renders their backticks, bold and links — never HTML. Before the check
was trusted, six drifts were planted: a parameter added to a call, a hook renamed, a `RunicNpc_List`
key renamed, a profile field renamed, a command verb renamed, and one call's `<Signature>` removed
from the page. All six failed, each naming the side it broke.
**The sidebar check learned nested groups.** `checkSidebar.mjs` and `checkTerms.mjs` read both
trees through `flatLabels()` in `sidebar.mjs`, which writes a nested page as `RunicNPC › Commands`.
The plan's order, and its vocabulary, are held for a subgroup exactly as for a group.
**Every admin screen was walked first** (D36), signed in as the walk admin on the walk site against
both rigs: *Rust NPC profiles* (the servers with their RunicNPC version, API and last push; the
profile list; the faction table; the editor opened on a new profile, through every section) and
*Rust NPC placements* (the server picker, the map with its layers, a waiting placement whose
profile had gone, and the cost warning above the list). Nothing was saved. Two claims were then
checked in `Module-Rust`'s server before they were written: the push tick is 30 s with a
quarter-hourly audit (`npcSync.js`), and saving a profile asks every covered server that answers
for its kits.
**What else changed.** The Rust overview's staff table links the two NPC screens to their pages,
and its "In this group" table gains the subgroup. *Events, zones and rewards* links its *Place
NPCs* step to the profiles page. The canonical documents gain `runicnpc/API.md`, `COMMANDS.md`,
`INSTALL.md` and `PLAN.md` under Rust, and that page now names the API page as the one deliberate
exception to "every page links out".
**Two findings outside this repository**, reported in the PR:
- **The Rust bundle's Oxide floor is lower than RunicNPC's — and that is intended.**
`v2/rust/current.json` says Oxide 2.0.7585, the bridge plugin's floor, while RunicNPC's own
`plugin.toml` says 2.0.7726. The org lead ruled on 2026-10-22 that **2.0.7585 is the original
compatible version and stays**. It moves only when the CI staging drill reports an issue, and then
as part of the update that fixes it. The site states each number where it belongs (the Rust
overview quotes the bundle's, the RunicNPC pages RunicNPC's) and claims nothing about the gap.
- **`API.md`'s profile table broke in two places.** The `boss` rows and the `loot` rows each
followed a blank line with no header row, so Gitea rendered them as plain text full of pipes.
The check parses them line by line and was not affected. Fixed at the org lead's ask in `docs`
#371, which removes the two blank lines and changes nothing else.
### How phase 17 built it
Five decisions, taken by the org lead on 2026-10-22 before any page was written, each from a
concrete example. The count of record is now **seventy-nine**.
**D75 — core marketing pages describe what a game module adds in core's words, and link to
the games.** The homepage, `/features/`, `/architecture/` and `/app/` name both games and use
neither game's vocabulary. The module-supplied group became *What a game module adds*: seven
things both modules supply, each in its own way (live server status, a live feed, leaderboards,
maps, Teams from the game, players' own game accounts, game steps for events), with a button
to each game's page. Each game's real list, in its own words, lives in `src/data/games/` and
renders only on `/modules/uo/` and `/modules/rust/`. The alternative was D68 applied to
marketing — game-labelled blocks carrying each game's real list on the core pages. It was
declined as longer, and as the front door carrying two games' jargon at once.
**D76 — the homepage's "What it looks like" keeps its game screenshot, labelled.** This is
D67's choice, made. The capture stays the Ultima Online live-status screen, now printing
"Ultima Online" beside it, because the claim under the data-path diagram is live game state
on a public page and no core screen shows that. Phase 18 adds a labelled Rust capture beside
it. The alternative, a core screen such as the admin dashboard, was declined.
**D77 — `/app/` describes the app's Rust screens.** When the phase began they were on
`Android-app` `edge` only, 26 commits ahead of `main` and in no release. The org lead chose to
describe them and release them the same day, rather than hold the page or say "next release".
`/app/`'s game section is now *The game, live*: one item per game, titled with the game's name
and written in core's words, plus Rust's half of *Your own side of the game*.
**D78 — `/runicnpc/` is in the header.** The top navigation is now five items, so a Rust
server owner who runs no Runic Gateway finds the plugin from any page (D61's reason). It is in
the footer's Product column and on the Rust module page's RunicNPC card too. The alternative
was the footer and the card only.
**D79 — `checkTerms.mjs` reads the built pages.** D64 had the check widen to all of `src/`. A
source scan of the marketing pages would see expressions rather than the words they render —
a capability label, a screenshot caption, a value from `platform.json` — and would take ids
like `shard-status` and slugs like `guilds` for prose. So the check gained a second pass,
`--built`, run after the build the way `checkLinks.mjs` is. It reads every page's visible text
plus `alt`, `title`, `aria-label`, `placeholder`, the `<title>` and the meta description, and
not link targets, scripts, styles or comments. A game's routes (`GAME_ROUTES`: its docs group,
its module page, and `/runicnpc/` for Rust) allow its words, and so does any element marked
`data-game` — `<GameExample>` and, new this phase, a game-tagged `<Screenshot>`. Starlight's
sidebar and the previous/next links are skipped, because the source pass reads the sidebar as
data and each neighbour's title is checked on its own page. The source pass is unchanged and
still runs first, naming a file and a line. Failures from the built pass name a route and a
snippet. It is still the twelfth check: one script, one word list, one allowlist (whose entry
now carries a `route` as well as a `file`). The alternative was a source scan with per-file
exemptions.
**The check was proven before it was trusted.** Ten plants went into the built HTML. Six
failed, each naming where: a word in a core page's text, in an `alt`, in a `title`, a
UO word inside a block marked Rust, a word split across two syntax-highlighting `<span>`s, and a
UO word on a Rust page. Four passed: a word only in an `href`, one in a `<script>`, UO words on
`/modules/uo/`, and a UO block on a core page. On the build as it stood before this phase, the
pass found 49 words on seven marketing pages; all are gone.
**What was built.**
- **`/modules/`** is core now. Its Ultima Online worked example became a card per game, from
`src/data/games/index.mjs`, and what the modules share — a sidecar, their own tables, their
own releases — is said once beneath them.
- **`/modules/uo/`** carries the Ultima Online list that used to be *Game intelligence*, the
three pieces with their versions, and the five screenshots `/features/` showed until now.
- **`/modules/rust/`** carries eight features for players and four for staff, written from the
Rust docs group phase 15 walked, the four pieces (the module, rust-link, `RunicGateway.cs`,
RunicNPC) and the RunicNPC card D61 asked for. It has no screenshots and no slots for them
(D65, D4).
- **`/runicnpc/`** is written for a server owner with no site: what it does, the two ways to run
it, and where to get it. Every number is read — release, API version and floors from
`platform.json`, the counts of calls and hooks from `runicnpc.mjs`, which phase 16's check
holds to `API.md`.
- **The page-side capability check is per game**, closing the item phase 13 moved here.
`assertGameCoverage()` holds each game's list to its module's declared capabilities in both
directions. The homepage, `/features/` and each game page call it, and
`assertDetailCoverage()` now reads the games' lists too.
- **The supported-games strip** (D63) is `src/components/SupportedGames.astro`, on the homepage,
`/features/` and `/modules/`.
- **D67 is in the components.** `screens.mjs` entries may carry `game`; nine are tagged `uo`.
`Screenshot.astro` and `/app/`'s phone grid print the game's name beside each tagged capture
and mark it `data-game`.
**What the re-read found**, fixed here:
- **`/architecture/` said two machines is "the minimum and also the maximum"**, false since Rust
shipped: one sidecar serves one server, so a community with six servers runs six. The caption
now says two is the minimum and a sidecar sits beside each game server, and its game host
section no longer says the installer prints "four values" (that count was one game's).
- **`/integrations/` and the Discord capability called a Discord server a "guild"** — Discord's
API word, but read on this site as a game's. They say *Discord server* now, as phase 14 made
the docs say.
- **`collection.mjs` was re-read against what the Rust module and Steam sign-in keep**, as the
plan required, before anything was claimed. *Account records* now names linked sign-in
identities, Steam's display name and avatar address included (`user_identities`). *Game data
from the connected server* names, for Rust, each player's Steam id and in-game name, their
statistics, who is online, and the event record, which includes chat, player reports and the
IP addresses on sign-in attempts and bans, readable by staff only. Its retention now states
the module's 30 days for that record and the sidecar's 14-day default. The Play Data Safety
answers did not change: the app's Rust screens read from the deployment and send it only a
one-time link code, which the existing "everything you read and post" row already covers. Its
wording lost "shard", so `PLAY_DATA_SAFETY.md` was regenerated.
### How phase 18 built it
Two decisions, taken by the org lead on 2026-10-22 while the phase was under way. The count of
record is now **eighty-one**.
**D80 — a name in a screenshot is a role.** Every username a capture shows — a site account, a
player in a feed, a member of a group — is `admin`, `moderator` or `player`, numbered
(`player2` …) when one screen needs several. A name that says what the account is reads as a
demonstration; an invented person's name reads as somebody's real community. It holds from
this phase on: the phase 9 captures keep their cast, by the org lead's ruling ("no going back
to change the old ones").
**D81 — the Rust captures' players are mock data.** The rig has no players. The phase first
staged stand-in players on it with a rig-only plugin, and the org lead stopped that in favour
of writing the game data straight into the demo's database. This amends D4 for the Rust
captures only. What is real in them is still most of the screen: a real Oxide test server
behind a real rust-link sidecar, its status, its world map and markers, the permission groups
its plugins hold, and RunicNPC's sync state. What is mock is the players: the feed, the
leaderboard, the weapon kills, the server list's player count and the linked Steam account.
`scripts/mockRustDemo.mjs` writes them as SQL in the module's own row shapes, and every name
in them is a role (D80). The captions describe what a screen does and never claim a player did
something; `screens.mjs`, `/modules/rust/` and `/app/` say plainly which part is a demo cast.
The homepage's Rust capture (D76) is the live map, because nothing in that frame is mocked.
The alternative, staging real kills with stand-ins, was abandoned after it cost a morning:
the Rust update had left the rig rebuilding its navmesh for ten minutes, and it stopped
answering the console for most of that time.
**The demo is a second deployment.** One deployment runs one game module (the core refuses a
second at boot), so the Rust demo has its own database, `rgdemorust`, its own core on the
review machine, and Module-Rust v0.5.0. The recipe, in order:
1. Bring the rig up to date (Rust, Oxide and Carbon, the rig rule). The org lead ruled one rig
enough: the Oxide rig, now Rust 26139947 and Oxide 2.0.7839. A restart did not update Rust:
steamcmd cancelled the delta on a DLL Oxide patches ("Corrupt game files"), and a panel
reinstall did not help either. Removing `steamapps/appmanifest_258550.acf` and starting
made steamcmd verify everything and finish. The Carbon rig was left on 25902425.
2. Create the database (without a `COLLATE` clause) and start the core against it with
`MODULES_DIR` holding the module and `BRAND_NAME="Runic Gateway Demo"`. Create `admin`,
`moderator` and `player` with generated passwords.
3. `node scripts/seedDemo.mjs --game rust`, with `RG_RUST_SERVERS` naming a JSON file outside
the repository that holds the server's id, name, sidecar address and token. It writes the
neutral identity, the two accounts, the server row with a weekly wipe, public visibility
for who is online and the map's players (the demo's choice, said in the seed), two RunicNPC
profiles on a kit the rig's Kits holds, and a VIP group with `player` in it.
4. `node scripts/mockRustDemo.mjs`, piped into the database, after the site has seen the
server once so its current wipe exists.
5. `npm run screens:capture` with the Rust ids. Set the server's player count just before
`rust-servers`, since the live server writes its own every thirty seconds.
**What was built.**
- **Nine captures**, all tagged `rust`: six web (the server list, the feed, the leaderboard,
the live map, the permissions screen with a group open, and the NPC profile editor) and three
phone (a server's feed, its map, and the player's Rust account). The phone ones are from an
`Android-app` `edge` debug build on the `s22_ultra` AVD, signed in as `player`; the Rust
screens were not in a release yet. The app's server list was left out: one server card on a
phone-height screen is mostly empty.
- **`captureScreens.mjs` can click.** An entry may carry `click`, the visible text of what to
click before the shot, for a subject behind a tab or a button the route cannot reach — the
permissions group and the profile editor. A step that matches nothing fails the shot.
- **Where they show:** `/modules/rust/` (the public four under what players see, the two staff
screens under theirs, with a sentence saying which part is a demo cast); the homepage's
*What it looks like*, the live map beside the Ultima Online capture (D76); `/app/`'s grid,
whose lede no longer says "not mocked up"; and three docs pages — the live map, permissions
and groups, and RunicNPC's NPC profiles.
**What the phase found**, reported, not fixed here:
- **The feed prints prefab names as weapons**: "with ak47u entity", "with bolt rifle entity".
The bridge sends `weapon` as the held entity's short prefab name, and Module-Rust's feed
prints it through `format.js`'s `prefab()`, which only turns dots and underscores into
spaces; the app does the same. It is in the captures as
the product shows it.
- **The app's first-run and sign-in screens say "shard"** ("Connect to your shard", "Sign in
with your shard account"), on every deployment, a Rust one included.
- **The permissions screen's Players tab lists Steam ids the rig already held**, among them
the org lead's own account from the player walk. That is the screen working (D31's reversal
adopts every grant), and why the capture opens the Groups tab; it is noted because any
demo pointed at a rig shows them.
---
[api]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md

View File

@@ -1,7 +1,7 @@
<!--
GENERATED FILE — do not edit.
Source: src/data/collection.mjs (scope "app") + src/data/legal.mjs
Source: src/data/collection.mjs (scope "app", and the deletion row) + src/data/legal.mjs
Generator: scripts/playDataSafety.mjs
Edit the data file and run `npm run play:datasafety`. CI runs the same
@@ -19,49 +19,100 @@ The Play Console asks, for every category of data, whether the app **collects**
We operate **no server the app talks to.** The app ships pointed at nothing: its first screen asks for the address of a Runic Gateway deployment and validates it before anything else in the app runs. That deployment belongs to whoever runs that community. Data therefore travels from the device to *their* server, and there is no endpoint of ours anywhere in the path — not for content, not for telemetry, and not for crash reports, of which there are none.
That is why nearly every answer below is "not collected", and it is also the answer most likely to be questioned in a review. The supporting facts are in the table: each row names the file it was read out of.
Play still counts what the app sends to that server as **collected**: the data leaves the device, and the form does not ask whose server it lands on. So everything the app sends is declared collected, not shared, and required, which is the conservative answer and the accurate one (org lead, 2026-10-29). What stays true, and what `/privacy` says, is that none of it reaches us.
Where the console offers free text about security practices, two things are worth saying: credentials are held in Android’s encrypted storage (AES-256-GCM via Jetpack Security), and push notifications carry **no content** — a relay receives a stream name and a reference, and the app fetches the actual message over its own authenticated connection.
## Data collection and security
## Data types
- **Does the app collect or share any of the required user data types?** Yes, it collects them (below). It shares none.
- **Is all of the user data collected by the app encrypted in transit?** Yes. The release build’s network security config sets `cleartextTrafficPermitted="false"` for every connection, and the app refuses an `http` deployment address outside debug builds. Read from: `app/src/main/res/xml/network_security_config.xml`, `core/net/ServerUrl.kt`.
- **Is any of it processed ephemerally?** No. The deployment keeps what it receives, under its operator’s policy, and we cannot promise otherwise on its behalf.
- **Free text on security practices**, where the console offers it: credentials are held in Android’s encrypted storage (AES-256-GCM via Jetpack Security), and push notifications carry **no content**: a relay receives a stream name and a reference, and the app fetches the actual message over its own authenticated connection.
| Category | Data type | Collected by us | Shared by us | Answer |
|---|---|---|---|---|
| Personal info | User IDs | No | No | Not collected by us. |
| Personal info | User IDs | No | No | Not collected by us. |
| App info and performance | Other app data | No | No | Not collected by us. Stored on the device only. |
| Messages | Other in-app messages | No | No | Not collected by us. Declare the relay hop in the console’s free-text security section if it asks. |
| Messages | Other user-generated content | No | No | Not collected by us. |
| Messages | Other in-app messages | No | No | Not collected by us. Stored on the device only. |
| Device or other IDs | Device or other IDs | No | No | Not collected. |
## Data types the app collects
| Category | Data type | Collected | Shared | Required | Purposes | From |
|---|---|---|---|---|---|---|
| Personal info | Name | Yes | No | Yes | App functionality | Your name, email address and message, if you use Contact |
| Personal info | Email address | Yes | No | Yes | App functionality | Your name, email address and message, if you use Contact |
| Personal info | User IDs | Yes | No | Yes | App functionality; Fraud prevention, security, and compliance; Account management | Your sign-in, and the tokens it issues; Linking a game account |
| Messages | Other in-app messages | Yes | No | Yes | App functionality | Your name, email address and message, if you use Contact; What you post and send from the app |
| App activity | App interactions | Yes | No | Yes | App functionality; Personalization | Which notifications you have read, and which you want |
| App activity | In-app search history | Yes | No | Yes | App functionality | What you search for |
| App activity | Other user-generated content | Yes | No | Yes | App functionality; Fraud prevention, security, and compliance; Personalization | What you post and send from the app; What you report, block or hide |
| App activity | Other actions | Yes | No | Yes | App functionality; Fraud prevention, security, and compliance; Personalization | What you report, block or hide |
| App info and performance | Diagnostics | Yes | No | Yes | App functionality; Fraud prevention, security, and compliance | The app’s version and your Android version |
| Device or other IDs | Device or other IDs | Yes | No | Yes | App functionality; Fraud prevention, security, and compliance; Account management | The trusted-device token and the device’s name, if you asked for one; Push registration, if you turn notifications on |
## Data types the app does not collect
The form lists every type, so every one is answered. Vocabulary read from Play Console Help on 2026-10-29; check it against the console’s current list.
- **Location:** none collected.
- **Personal info:** Address, Phone number, Race and ethnicity, Political or religious beliefs, Sexual orientation, Other info: not collected.
- **Financial info:** none collected.
- **Health and fitness:** none collected.
- **Messages:** Emails, SMS or MMS: not collected.
- **Photos and videos:** none collected.
- **Audio files:** none collected.
- **Files and docs:** none collected.
- **Calendar:** none collected.
- **Contacts:** none collected.
- **App activity:** Installed apps: not collected.
- **Web browsing:** none collected.
- **App info and performance:** Crash logs, Other app performance data: not collected.
## Held on the device only
Not collected, because none of it leaves the phone; listed so nobody declares it by mistake.
- **The address of the deployment you chose.** It never leaves the phone. It is the destination of requests, not the contents of one.
- **A snapshot of your notifications, so the inbox opens without a signal.** The snapshot is written on the phone from data the deployment had already delivered. It is not uploaded anywhere.
- **No analytics, no crash reporting, no advertising.** No crash reporter, no advertising ID, no analytics identifier, and no library that would generate one is linked into the build.
## Each answer, and why it is the truthful one
### Your sign-in tokens
### Your sign-in, and the tokens it issues
**Personal info → User IDs.** Not collected by us.
**Personal info → User IDs.** Collected, not shared, required.
When you sign in to a deployment, the app keeps the access and refresh tokens it was issued, plus the username, role and account id they belong to. They are held in encrypted storage on the device (AES-256-GCM through Jetpack Security) and are sent to exactly one place: the deployment that issued them.
Purposes: App functionality; Account management; Fraud prevention, security, and compliance.
- **Why that answer:** The credentials are issued by, and returned to, a server the user nominated. Nothing reaches an endpoint under our control, because we run none.
- **Retention:** On the device until you sign out
- **In detail:** Signing out clears them; uninstalling the app removes them with it.
- **Read from:** `core/auth/EncryptedTokenStore.kt`
Signing in sends your username and password to the deployment, or with single sign-on a one-time code from the provider, plus a two-factor code when the account has one. The deployment answers with an access and a refresh token and the username, role and account id they belong to. The tokens are held in encrypted storage on the device (AES-256-GCM through Jetpack Security) and are sent to exactly one place: the deployment that issued them, with every request. Changing your username or password, setting up two-factor sign-in and generating recovery codes from the app go to the same place. So does deleting the account, which sends your username, your password and, if the account has one, a two-factor code.
### The trusted-device token, if you asked for one
- **Why that answer:** The username, password and tokens leave the phone for the deployment the user chose, and Play counts that as collection whoever runs the server. None of it reaches us. Security is a purpose because the deployment checks two-factor codes and trusted devices with it.
- **Retention:** On the device until you sign out or delete the account
- **In detail:** Signing out clears them, and so does deleting the account; uninstalling the app removes them with it.
- **Read from:** `data/api/AuthApi.kt, data/api/SsoApi.kt, data/api/MeApi.kt, core/auth/EncryptedTokenStore.kt`
**Personal info → User IDs.** Not collected by us.
### The trusted-device token and the device’s name, if you asked for one
Ticking “trust this device” during two-factor sign-in stores an opaque token so the deployment can skip the second factor next time. It lives in its own encrypted store, deliberately separate from the session, because it has to outlive a sign-out to be worth anything — and the deployment holds only a hash of it, so the copy on your phone is the only usable one.
**Device or other IDs → Device or other IDs.** Collected, not shared, required.
- **Why that answer:** Same as the session tokens: minted by the user’s deployment, stored on the device, presented back to that same deployment.
Purposes: Account management; Fraud prevention, security, and compliance.
Ticking “trust this device” during two-factor sign-in stores an opaque token so the deployment can skip the second factor next time. It lives in its own encrypted store, deliberately separate from the session, because it has to outlive a sign-out to be worth anything — and the deployment holds only a hash of it, so the copy on your phone is the only usable one. The phone’s make and model, such as “Samsung SM-S918B”, goes with the request as the device’s label, so you can tell it apart in the deployment’s list of trusted devices. It is a model name, not a hardware identifier.
- **Why that answer:** The token identifies this device to the deployment, and the label is sent with it. Both are presented to the deployment that minted the token and to nothing else.
- **Retention:** On the device until it expires or you revoke it
- **In detail:** Thirty days, and revocable at any time from the deployment’s Trusted Devices screen, which is also where it can be revoked if the phone is lost.
- **Read from:** `core/auth/EncryptedTrustTokenStore.kt`
- **In detail:** Thirty days, and revocable at any time from the deployment’s Trusted Devices screen, which is also where it can be revoked if the phone is lost. Deleting the account from the app drops it from the phone too, since there is no next sign-in for it to skip.
- **Read from:** `core/auth/EncryptedTrustTokenStore.kt, core/auth/DeviceNameProvider.kt`
### The app’s version and your Android version
**App info and performance → Diagnostics.** Collected, not shared, required.
Purposes: App functionality; Fraud prevention, security, and compliance.
Every request carries a User-Agent such as “RunicGatewayApp/0.6.0 (Android 15)”. It is there because a deployment turns away traffic that looks like a scanner, and it names nothing about you or the phone beyond those two version numbers.
- **Why that answer:** It is technical information about the app and the device, and it is sent with every request. The deployment uses it to tell the app from a scanner.
- **Retention:** Under the deployment operator’s policy
- **In detail:** A deployment’s access log may keep it, as any web server keeps the user agent of a browser.
- **Read from:** `di/NetworkModule.kt, core/net/UserAgentInterceptor.kt`
### The address of the deployment you chose
**App info and performance → Other app data.** Not collected by us. Stored on the device only.
**No console type.** Not collected. Stored on the device only.
The app ships pointed at nothing and asks for an address on first run. That address is stored in ordinary preferences rather than encrypted storage — it is not a secret, it is the equivalent of a bookmark — and it is what every other screen in the app talks to.
@@ -71,43 +122,110 @@ The app ships pointed at nothing and asks for an address on first run. That addr
### Push registration, if you turn notifications on
**Messages → Other in-app messages.** Not collected by us. Declare the relay hop in the console’s free-text security section if it asks.
**Device or other IDs → Device or other IDs.** Collected, not shared, required. Mention the relay in the free-text security section if the console asks.
Purposes: App functionality.
Push is off until you enable it. When you do, the app mints a random, unguessable topic name on the notification relay the deployment nominates, and registers that topic’s URL with the deployment so it has somewhere to send a nudge. What actually travels through the relay is content-free — a stream name and a reference, never the message — and the app then fetches the real content over its authenticated connection to the deployment. A leaked topic name therefore reveals nothing, which is the reason the relay needs no account and holds nothing about you.
- **Why that answer:** The notification passes through a relay chosen by the deployment, and it carries no content — the app pulls the content itself, authenticated. Neither hop reaches a server we operate.
- **Retention:** Until you turn push off, sign out, or uninstall
- **In detail:** Signing out or disabling push unregisters the device with the deployment and discards the topic. The relay retains whatever its own operator configures it to; if the deployment points at a relay it does not run, that relay is a third party to both of us, and it still only ever sees a tickle.
- **Read from:** `core/push/NtfyTopic.kt, core/push/PushPreferences.kt`
- **Why that answer:** The topic URL is an address for this device, and the app sends it to the deployment. The relay is the one the deployment nominates to deliver its own notifications, so it carries them on the deployment’s behalf rather than receiving a share. It only ever sees a topic name and a tickle; the app pulls the content itself, authenticated. No hop reaches a server we operate.
- **Retention:** Until you turn push off, sign out, delete the account, or uninstall
- **In detail:** Signing out or disabling push unregisters the device with the deployment and discards the topic; deleting the account drops the registration on the deployment with everything else. The relay retains whatever its own operator configures it to; if the deployment points at a relay it does not run, that relay is a third party to both of us, and it still only ever sees a tickle.
- **Read from:** `core/push/NtfyTopic.kt, core/push/PushPreferences.kt, data/api/NotificationsApi.kt`
### Everything you read and post in the app
### Linking a game account
**Messages → Other user-generated content.** Not collected by us.
**Personal info → User IDs.** Collected, not shared, required.
Forum posts, Team activity, character and shard information, notification preferences: all of it is a live read or write against the deployment. Apart from the notification snapshot described in the next entry, nothing is cached for offline use and nothing is duplicated anywhere else — the app with no signal is an app with almost no content, which is a limitation and also an accurate description of where the data lives.
Purposes: App functionality; Account management.
- **Why that answer:** Content is written to the community’s own installation. We have no copy, no access and no way to obtain one.
Linking your site account to a game sends the one-time code the game gave you. Where a game server offers it, the app can also create a new game account, which sends the account name and password you chose. Unlinking sends the id being unlinked, such as a Steam id. All of it goes to the deployment, which keeps the link against your site account.
- **Why that answer:** Game account names, Steam ids and link codes identify a player, and the app sends them to the deployment.
- **Retention:** Held by the deployment until you unlink, under its operator’s policy
- **Read from:** `data/api/PlayerShardApi.kt, data/api/PlayerRustApi.kt, data/api/MeApi.kt`
### Your name, email address and message, if you use Contact
**Personal info → Name; Personal info → Email address; Messages → Other in-app messages.** Collected, not shared, required.
Purposes: App functionality.
The Contact screen sends the name, email address and message you type to the deployment, which passes them on to its operator by email so they can reply. Nothing is sent until you press send.
- **Why that answer:** The form’s three fields leave the phone for the deployment, whose operator receives them.
- **Retention:** Held by the deployment’s operator, under their policy
- **In detail:** The message is delivered to the operator’s mailbox, and kept as long as they keep it.
- **Read from:** `data/api/PublicApi.kt, data/api/dto/ContactDto.kt`
### What you post and send from the app
**Messages → Other in-app messages; App activity → Other user-generated content.** Collected, not shared, required.
Purposes: App functionality.
Most of the app is reading. What it sends is what you write, and most of that is for staff: news posts, wiki categories, a broadcast to the game, the answer to a player’s help page, and the account and reason on a kick or a ban. All of it is a live write to the deployment. Apart from the notification snapshot described below, nothing is cached for offline use and nothing is duplicated anywhere else — the app with no signal is an app with almost no content, which is a limitation and also an accurate description of where the data lives.
- **Why that answer:** Posts, broadcasts and replies are written to the community’s own installation. We have no copy, no access and no way to obtain one.
- **Retention:** Held by the deployment, under its operator’s policy
- **Read from:** `PLAN.md §9 section 2`
- **Read from:** `data/api/AdminApi.kt`
### What you report, block or hide
**App activity → Other user-generated content; App activity → Other actions.** Collected, not shared, required.
Purposes: App functionality; Fraud prevention, security, and compliance; Personalization.
Long-pressing a chat line offers Report, Hide for me and Block player. A report sends which line it is, the reason you picked and, if you wrote one, a note of up to 500 characters, so the deployment’s staff can review it. Hide for me and Block player send which line it is; the deployment works out who wrote it and keeps the hide or the block on your account, so it applies on the website and on every device. Your list of blocks, and unblocking someone, come from and go to the same place. For staff, Hide for everyone and Show to everyone again send the line too. Nothing is sent until you choose one.
- **Why that answer:** The report’s note is text the user writes, and reporting, blocking and hiding are actions the app sends to the deployment, which keeps them. Reports exist so staff can act on abuse; blocks and hides change what this one reader is shown.
- **Retention:** Held by the deployment, under its operator’s policy
- **In detail:** A block or a hide lasts until you remove it or delete the account, which deletes them. A report stays as a moderation record, with a copy of what the line said, until the operator removes it.
- **Read from:** `data/api/SafetyApi.kt, data/api/dto/SafetyDto.kt, data/api/RustApi.kt`
### Which notifications you have read, and which you want
**App activity → App interactions.** Collected, not shared, required.
Purposes: App functionality; Personalization.
Opening a notification marks it read on the deployment, so the badge agrees on every device you use. Your choice of notification streams, and of which arrive by push or email, is saved there too.
- **Why that answer:** Read state and preferences are actions in the app that are sent to, and kept by, the deployment.
- **Retention:** Held by the deployment, under its operator’s policy
- **Read from:** `data/api/NotificationsApi.kt`
### What you search for
**App activity → In-app search history.** Collected, not shared, required.
Purposes: App functionality.
Searching the wiki, a game’s market or its creature atlas sends what you typed to the deployment, because the deployment does the searching. The app keeps no history of searches.
- **Why that answer:** Search text leaves the phone in the request to the deployment.
- **Retention:** Under the deployment operator’s policy
- **In detail:** The query is part of the request’s address, so a deployment’s access log may record it. That is why it is declared rather than called ephemeral.
- **Read from:** `data/api/PublicApi.kt`
### A snapshot of your notifications, so the inbox opens without a signal
**Messages → Other in-app messages.** Not collected by us. Stored on the device only.
**No console type.** Not collected. Stored on the device only.
The app keeps the most recent notifications it has already fetched — at most thirty, and only the first page — on the device, so opening the inbox shows you what you had rather than a spinner. It is a copy of what the deployment already sent you and it is refreshed from there; nothing is written here that was not read from your own account. It is scoped to the account that fetched it, so a second person signing in on the same phone is never shown the first one’s messages.
- **Why that answer:** The snapshot is written on the phone from data the deployment had already delivered. It is not uploaded anywhere, and no server we operate is on either end of it.
- **Retention:** Until you sign out, or the thirty are pushed out by newer ones
- **In detail:** Signing out deletes the snapshot outright. It lives in the app’s ordinary preference store rather than the encrypted one — sign-in tokens are the thing that store is for — which is worth stating plainly: on a device where someone has root, these are readable, and they are notification bodies rather than credentials.
- **Why that answer:** The snapshot is written on the phone from data the deployment had already delivered. It is not uploaded anywhere.
- **Retention:** Until you sign out or delete the account, or the thirty are pushed out by newer ones
- **In detail:** Signing out, or deleting the account, deletes the snapshot outright. It lives in the app’s ordinary preference store rather than the encrypted one — sign-in tokens are the thing that store is for — which is worth stating plainly: on a device where someone has root, these are readable, and they are notification bodies rather than credentials.
- **Read from:** `core/inbox/DataStoreInboxCache.kt, data/repository/AuthRepository.kt`
### No analytics, no crash reporting, no advertising
**Device or other IDs → Device or other IDs.** Not collected.
**App info and performance → Crash logs.** Not collected. The advertising ID declaration is "no".
There is no third-party SDK in the app at all — no Firebase, no Crashlytics, no advertising identifier, no measurement library. That is checkable rather than claimed: it is what the dependency list and the manifest say, and a build that gained one would gain permissions with it.
- **Why that answer:** No advertising ID, no analytics identifier, and no library that would generate one is linked into the build.
- **Why that answer:** No crash reporter, no advertising ID, no analytics identifier, and no library that would generate one is linked into the build.
- **Retention:** Nothing to retain
- **Read from:** `app/build.gradle.kts, app/src/main/AndroidManifest.xml`
@@ -115,8 +233,31 @@ There is no third-party SDK in the app at all — no Firebase, no Crashlytics, n
- **Privacy policy URL:** `/privacy` on this site. It is the URL Play is given, and section 2 of it is about the app specifically.
- **Target audience:** adults. The beta is stated as **18 or older** (D31); the app contains no content directed at children and no age verification.
- **Account deletion:** the app creates no account with us — an account belongs to the deployment the user chose, and is deleted there. The only list we hold is the beta signup, which is erased on request; `/privacy` section 4 says how to ask.
- **Data deletion request URL:** the contact address published on `/privacy`, which is read from the mounted `brand.json` rather than typed anywhere in the source (D13).
- **Accounts the app can start:** the sign-in screen links to the deployment’s own sign-up page, which opens in the browser, and where a game server offers it the app creates a game account on it. Read from: `ui/auth/LoginViewModel.kt`, `data/api/PlayerShardApi.kt`.
- **Can users delete their account? Yes,** in the app (*My account* → *Delete my account…*) and on the deployment’s website (*Account* → *Delete my account*). It takes the password, and a two-factor code where the account has one, and the account is deleted at once. The account belongs to the deployment the user chose, so it is deleted there; we hold none. Read from: `ui/auth/DeleteAccountScreen.kt`, `data/api/MeApi.kt`.
- **Delete account URL:** `/delete-account/` on this site (D85). It names the app and us, gives the steps in the app and on the website, says what is deleted and what is kept and for how long, and tells someone who cannot sign in to ask their community’s operator, who can delete any account from the admin panel (D86).
- **Deleting some data without deleting the account:** the deployment holds it, so that is a request to its operator. The one list we hold, the beta signup, is erased on request; `/privacy` section 4 says how to ask.
## What an account deletion deletes and keeps
The console asks what is deleted and what is kept. These are the same words `/delete-account/` renders, from the same row of `src/data/collection.mjs`.
**Deleted at once:**
- your sign-in, password, email address, two-factor settings and recovery codes
- every signed-in device, trusted device and push registration
- your linked sign-ins, such as Google, Discord or Steam
- your game-account links, and anything this site granted in the game through them
- your notification settings and inbox
**Kept:**
- What you wrote where others read it, such as forum posts, stays. Other members see it as written by “[deleted player]”. *Until a moderator or the operator removes it, as with any post.*
- Reports you filed and appeals you made stay as moderation records. Staff can still see who it was, and the activity log keeps its IP addresses. *Until the operator removes them.*
- Event results stay with the score and the in-game name, with no site account behind them. *Until the operator removes them.*
- A game account stays on the game server. Only its link to this site goes. *For as long as the game server keeps it, which is up to whoever runs that server.*
- The record of notifications sent to you keeps a one-way hash of your email address, never the address, and no longer names your account. An address that bounced or was reported as spam stays on the suppression list, so it is never mailed again. *The record is swept after a period the operator sets, 180 days by default. The suppression list does not expire.*
- If you were staff, your username can never be used again, by anyone.
## What the website collects, for the same reviewer
@@ -128,4 +269,4 @@ Not part of the Data Safety form — that form is about the app — but a review
- **Your browser’s user-agent string, truncated** — With the row; blanked on removal.
- **The web server’s access log** — Short-term operational retention, then rotated away.
Last generated from data dated 2026-09-01. Regenerate with `npm run play:datasafety` after any change to what the app stores.
Last generated from data dated 2026-10-30. Regenerate with `npm run play:datasafety` after any change to what the app stores.

View File

@@ -13,7 +13,7 @@ it before changing anything here.
**Status: phase 12 of 12 — delivery. The site is built.** Fifty pages: ten marketing, legal and
app pages and forty of documentation, with real screenshots of the product, full-text search, a
per-page Content-Security-Policy, eleven checks that fail the build when the platform moves out from
per-page Content-Security-Policy, twelve checks that fail the build when the platform moves out from
under a claim, and a closed-beta signup backed by SQLite on a bind mount. This phase is the part
that makes it a deployment rather than a repository — the container image, the compose file, the
publishing workflow and [`DEPLOY.md`](DEPLOY.md).
@@ -32,7 +32,7 @@ npm run build # → dist/ (prerendered pages + the Node server entry)
npm start # serve the built site
```
Node 22 LTS or newer. Nothing else — no database, no game server, no container runtime.
Node 22.23.4+ (or 24.22.1+); older builds carry the Node2Shell Brotli bug, CVE-2026-111497. Nothing else — no database, no game server, no container runtime.
## Running it in production
@@ -51,11 +51,12 @@ a publication**.
## The checks, and why they are not optional
Eleven of them, from `PLAN.md` §12. None is a linter; each one enforces a promise the site makes
Twelve of them, from `PLAN.md` §12. None is a linter; each one enforces a promise the site makes
that would otherwise decay quietly.
```bash
npm run check:sidebar # the rendered docs tree still matches the planned one
npm run check:terms # no game's vocabulary outside its section: docs + sidebar
npm run check:screens # every screenshot has an entry, at the size declared
npm run check:tokens # no colour literal outside the token file
npm run check:brand # the branding pipeline's two quiet failures
@@ -64,6 +65,7 @@ npm run check # astro check
npm test # the beta signup's decision path, and the policy data
npm run build # everything below reads the build
npm run check:links # every internal link resolves
npm run check:terms:built # the same rule over every built page, as rendered
GITEA_TOKEN=<token> npm run check:facts # every version agrees with its authority
GITEA_TOKEN=<token> npm run check:quickstart # the install page still matches website's own files
GITEA_TOKEN=<token> npm run check:reference # every name the Reference lists still exists
@@ -228,11 +230,15 @@ src/
data/collection.mjs What is collected, in three scopes. /privacy renders it and the
Play Data Safety notes are generated from it — one inventory.
data/legal.mjs The values /terms, /privacy and the consent sentence must share.
data/games/ One file per game, in that game's words, checked against its
module's capabilities. Only that game's pages render it.
styles/tokens.css THE token file — the only place a colour literal may appear.
styles/global.css The layout shell, built entirely from tokens.
styles/starlight.css Restates our tokens as Starlight's, so the docs cannot drift.
layouts/, components/ The marketing chrome.
pages/ Marketing routes.
pages/modules/ One page per game module; with /runicnpc/, the only marketing
routes that may use a game's own words (D63, checkTerms --built).
pages/beta.astro The signup. Renders AND handles its own POST — runs per request.
content/docs/docs/ Documentation. The extra level mounts Starlight at /docs.
pages/brand/ GET /brand/* — the mount, resolved and derived. Runs per request.

View File

@@ -4,6 +4,7 @@ import node from '@astrojs/node';
import starlight from '@astrojs/starlight';
import { inlineScriptHashes, inlineStyleHashes } from './src/config/cspHashes.mjs';
import { docsRedirects } from './src/config/redirects.mjs';
import { docsSidebar } from './src/config/sidebar.mjs';
/**
@@ -34,6 +35,10 @@ export default defineConfig({
format: 'directory',
},
// Pages that moved into a game's own sidebar group (PLAN.md §16, D60). See the file.
redirects: docsRedirects,
security: {
csp: {
directives: [

View File

@@ -23,13 +23,22 @@
"giteaOrg": "https://gitea.whitlocktech.com/RunicGateway",
"$comment_demo": [
"§15 / D12. A public demo instance is planned and out of scope today. The homepage's",
"'See it running' slot and /features/'s per-capability affordance render only when this",
"is a non-empty URL, so the site gains a working demo by way of one line in a mounted",
"file — no rebuild, consistent with §7."
"§15 / D12. The public demo's address, e.g. https://demo.runicgateway.com. The",
"homepage's 'See it running' slot and /features/'s per-capability affordance render only",
"when this is a non-empty URL, so the site gains a working demo by way of one line in a",
"mounted file — no rebuild, consistent with §7. /beta also reads the demo's published",
"sign-ins from it, on the next request (D82)."
],
"demoUrl": "",
"$comment_demoGames": [
"D83. The game modules the demo at demoUrl runs, by module id (\"rust\", \"uo\"). A",
"'See it running' link into a game's own pages shows only for a game listed here, so",
"a Rust demo never links to a /uo/ page it does not have. Core's links (the wiki, the",
"event calendar, news) follow demoUrl alone. Read at the next restart, like demoUrl."
],
"demoGames": [],
"$comment_beta": [
"PLAN.md §8 / D27. The Google Play closed-test opt-in URL. Empty until the track",
"exists, and /beta renders a waiting state rather than a broken link while it is.",

View File

@@ -22,16 +22,18 @@
"check:quickstart": "node scripts/checkQuickstart.mjs",
"check:reference": "node scripts/checkReference.mjs",
"check:sidebar": "node scripts/checkSidebar.mjs",
"check:terms": "node scripts/checkTerms.mjs",
"check:terms:built": "node scripts/checkTerms.mjs --built",
"check:screens": "node scripts/checkScreens.mjs",
"check:a11y": "node scripts/checkA11y.mjs",
"check:csp": "node scripts/checkCsp.mjs",
"play:datasafety": "node scripts/playDataSafety.mjs",
"beta": "node scripts/beta.mjs",
"test": "node --test test/beta.test.mjs test/legal.test.mjs test/footer.test.mjs",
"test": "node --test test/beta.test.mjs test/legal.test.mjs test/footer.test.mjs test/demo.test.mjs",
"brand:assets": "node scripts/buildBrandAssets.mjs",
"screens:capture": "node scripts/captureScreens.mjs",
"csp:hashes": "node scripts/checkCsp.mjs --reset && astro build && node scripts/checkCsp.mjs --write && astro build && node scripts/checkCsp.mjs",
"verify": "npm run check:sidebar && npm run check:screens && npm run check:tokens && npm run check:brand && npm run check:datasafety && npm run check && npm test && npm run build && npm run check:links && npm run check:facts && npm run check:quickstart && npm run check:reference && npm run test:served && npm run check:a11y && npm run check:csp",
"verify": "npm run check:sidebar && npm run check:terms && npm run check:screens && npm run check:tokens && npm run check:brand && npm run check:datasafety && npm run check && npm test && npm run build && npm run check:links && npm run check:terms:built && npm run check:facts && npm run check:quickstart && npm run check:reference && npm run test:served && npm run check:a11y && npm run check:csp",
"test:served": "node --test test/headers.test.mjs"
},
"dependencies": {

Binary file not shown.

After

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 284 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 173 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 57 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 111 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

View File

@@ -193,17 +193,38 @@ if (demoFrom !== demoTo) {
* because `global.css` hides `[data-demo-url='']` — the visibility rule stays one rule for
* both kinds of link, and only the `href` differs.
*/
const DEEP_LINK = /href="[^"]*" data-demo-url="[^"]*" data-demo-path="([^"]*)"/g;
const DEEP_LINK = /href="[^"]*" data-demo-url="[^"]*" data-demo-path="([^"]*)"(?: data-demo-game="([^"]*)")?/g;
const deepLinkTo = (demoPath) => {
const href = demoTo ? `${demoTo.replace(/\/+$/, '')}${demoPath}` : '';
/**
* Which games the demo runs (D83). A deep link into a game module's pages carries that
* game's id in `data-demo-game`, and it is filled only when the mounted `demoGames` names
* it: the demo is a Rust deployment, and a `/uo/market` link into it is a 404. Core's own
* links (`/wiki`, `/site/events`) carry no game and follow `demoUrl` alone, because every
* deployment has them.
*
* An absent or malformed list means no game's links, not every game's. A demo whose games
* nobody named is one whose game links cannot be known to work.
*/
const gamesOf = (value) => (Array.isArray(value) ? value.filter((id) => typeof id === 'string') : []);
const gamesFrom = gamesOf(previous.demoGames);
const gamesTo = gamesOf(resolved.demoGames);
const gamesChanged = gamesFrom.join(',') !== gamesTo.join(',');
if ('demoGames' in mounted && !Array.isArray(mounted.demoGames)) {
console.warn('[brand] the mounted "demoGames" is not a list of game ids — no game links will show.');
}
const deepLinkTo = (demoPath, game) => {
const root = !game || gamesTo.includes(game) ? demoTo : '';
const href = root ? `${root.replace(/\/+$/, '')}${demoPath}` : '';
return (
`href="${escapeHtml(href)}" data-demo-url="${escapeHtml(demoTo)}" ` +
`data-demo-path="${demoPath}"`
`href="${escapeHtml(href)}" data-demo-url="${escapeHtml(root)}" ` +
`data-demo-path="${demoPath}"` +
(game === undefined ? '' : ` data-demo-game="${game}"`)
);
};
if (!replacements.length) {
if (!replacements.length && !gamesChanged) {
console.log('[brand] mount matches what is already applied; nothing to rewrite.');
process.exit(0);
}
@@ -303,8 +324,8 @@ for (const file of walk(CLIENT)) {
// After the literal swaps, never before: the plain-slot replacement also matches the
// first two attributes of a deep link, so it runs first and this pass corrects the
// `href` it just wrote. Recomputing rather than replacing is what makes that safe.
after = after.replace(DEEP_LINK, (whole, demoPath) => {
const rebuilt = deepLinkTo(demoPath);
after = after.replace(DEEP_LINK, (whole, demoPath, game) => {
const rebuilt = deepLinkTo(demoPath, game);
if (rebuilt !== whole) counts.set('demoDeep', counts.get('demoDeep') + 1);
return rebuilt;
});
@@ -330,6 +351,9 @@ if (counts.get('demoDeep')) {
` ${'demoUrl deep'.padEnd(14)} ${demoTo ? `linked -> ${demoTo}/…` : 'links hidden'} (${counts.get('demoDeep')}x)`
);
}
if (gamesChanged) {
console.log(` ${'demoGames'.padEnd(14)} ${gamesTo.length ? gamesTo.join(', ') : 'no game links'}`);
}
if (inlineCollisions.length) {
console.error(

View File

@@ -138,6 +138,23 @@ for (const shot of todo) {
try {
await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 });
// A screen whose subject is behind a tab or a button the route cannot reach. Each step is
// the visible text the element starts with; the first visible button, link or tab that
// matches is clicked. A step that matches nothing fails the shot rather than capturing
// the wrong screen.
for (const label of shot.click ?? []) {
const clicked = await page.evaluate((text) => {
const candidates = [...document.querySelectorAll('button, a, [role="tab"], [role="button"], li')];
const hit = candidates.find(
(el) => el.offsetParent !== null && el.textContent.trim().startsWith(text),
);
if (hit) hit.click();
return Boolean(hit);
}, label);
if (!clicked) throw new Error(`nothing to click starting "${label}"`);
await new Promise((resolve) => setTimeout(resolve, 800));
}
if (shot.scrollY) {
await page.evaluate((y) => window.scrollTo(0, y), shot.scrollY);
}

View File

@@ -32,6 +32,7 @@ import path from 'node:path';
import sharp from 'sharp';
import { classify } from '../src/lib/brandAssets.mjs';
import { games } from '../src/data/games/index.mjs';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const DEFAULTS = path.join(ROOT, 'brand-default');
@@ -157,6 +158,20 @@ if (brand) {
}
}
// D83: the one list-valued field. Each entry is a game module's id, checked against the
// games this site describes, so a typo is a failed build rather than a demo whose game
// links silently never appear.
const gameIds = games.map((game) => game.key);
if (!Array.isArray(brand.demoGames)) {
fail('brand.json is missing the list field "demoGames" (an empty list is the stock value).');
} else {
for (const id of brand.demoGames) {
if (!gameIds.includes(id)) {
fail(`brand.json's "demoGames" names ${JSON.stringify(id)}, which is not one of ${gameIds.join(', ')}.`);
}
}
}
/**
* Kept in step with `TEXT_FIELDS` in `applyBrand.mjs` by reading that file rather than by
* restating the list. A field added there and forgotten here would be unchecked; a field
@@ -348,6 +363,23 @@ if (!deepPattern) {
);
}
// A game's link (D83) must also be read WITH its game. A pattern that matched the first
// three attributes and dropped the fourth would treat a /uo/ link as a core one and fill
// it on every demo, which is the 404 the attribute exists to prevent.
const gameSample = `${sample} data-demo-game="rust"`;
let gameRead = null;
try {
gameRead = new RegExp(deepPattern[1]).exec(gameSample)?.[2] ?? null;
} catch {
// Reported above.
}
if (gameRead !== 'rust') {
fail(
`applyBrand.mjs's DEEP_LINK does not read the game out of \`${gameSample}\`.\n` +
' Game links would follow demoUrl alone and point into modules the demo may not run.'
);
}
const deepStrays = [];
let deepLinks = 0;

View File

@@ -7,6 +7,10 @@
* this is the machinery that makes writing the NAMES down safe anyway — the same bargain
* checkQuickstart.mjs struck for the quickstart, applied to six more sources.
*
* Phase 15 (PLAN.md §16) added the Rust group's three: rust-link's `sidecar.toml` and its
* environment overrides, the bridge plugin's `RunicGateway.json`, and the event kinds with the
* class each is served under (D71).
*
* Each enumeration in `src/data/reference.mjs` is compared against its authority, read from
* the repository that owns it over the Gitea API — never from a working tree, per §1's
* process rule. Every comparison is a SET comparison in both directions:
@@ -39,7 +43,24 @@ import {
bridgeCfg,
visibilityLadder,
canonicalDocs,
rustSidecarConfig,
rustSidecarEnv,
rustPluginConfig,
rustEventKinds,
} from '../src/data/reference.mjs';
import {
runicnpcOwners,
runicnpcCalls,
runicnpcHooks,
runicnpcListKeys,
runicnpcPlacementKeys,
runicnpcRouteKeys,
runicnpcProfileFields,
runicnpcCommands,
runicnpcPermissions,
runicnpcPlaceOptions,
runicnpcConfig,
} from '../src/data/runicnpc.mjs';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const platform = JSON.parse(readFileSync(path.join(ROOT, 'src/data/platform.json'), 'utf8'));
@@ -103,6 +124,235 @@ const cfgKeysOf = (text) =>
.filter(Boolean)
.map((m) => m[1]);
/**
* A sidecar's TOML keys, parsed from its serde structs rather than from a sample file,
* because the sample is GENERATED by the binary on first run and no committed copy is
* authoritative. Each `pub name: T` inside a `struct XCfg` is one key, and the struct name
* gives the section. Both sidecars are written this way, so one parser serves both.
*/
function tomlKeysOf(configRs) {
const keys = [];
for (const m of configRs.matchAll(/struct\s+(\w+)Cfg\s*\{([\s\S]*?)\n\}/g)) {
const section = m[1].toLowerCase();
for (const f of m[2].matchAll(/pub\s+(\w+)\s*:/g)) keys.push(`${section}.${f[1]}`);
}
return keys;
}
/** The body of a C# class, by brace counting from its opening brace. */
function classBody(source, name) {
const start = source.search(new RegExp(`class\\s+${name}\\b`));
if (start < 0) return null;
const open = source.indexOf('{', start);
let depth = 0;
for (let i = open; i < source.length; i++) {
if (source[i] === '{') depth++;
else if (source[i] === '}' && --depth === 0) return source.slice(open + 1, i);
}
return null;
}
/**
* The quoted strings inside `const NAME = Object.freeze([ … ])`, comments removed first —
* the module's comments are prose, and prose has apostrophes.
*/
function frozenListOf(source, name) {
const m = source.match(new RegExp(`const\\s+${name}\\s*=\\s*Object\\.freeze\\(\\[([\\s\\S]*?)\\]\\)`));
if (!m) return null;
const code = m[1].replace(/\/\/.*$/gm, '');
return [...code.matchAll(/'([^'\n]+)'/g)].map((x) => x[1]);
}
/**
* One section of a Markdown document: from the line starting with `heading` to the next
* heading of the same or a higher level. Null when there is no such heading, which every
* caller reports — a section that silently vanished must not read as an empty one.
*/
function mdSection(md, heading) {
const lines = md.split(/\r?\n/);
const start = lines.findIndex((l) => l.startsWith(heading));
if (start < 0) return null;
const level = heading.match(/^#+/)[0].length;
const stop = new RegExp(`^#{1,${level}} `);
let end = lines.length;
for (let i = start + 1; i < lines.length; i++) {
if (stop.test(lines[i])) {
end = i;
break;
}
}
return lines.slice(start + 1, end).join('\n');
}
/** The backticked names in the first cell of every table row of a section. */
function firstCellNames(section) {
return section
.split('\n')
.filter((l) => l.startsWith('| `'))
.map((l) => [...l.split('|')[1].matchAll(/`([^`]+)`/g)].map((m) => m[1]));
}
const collapse = (s) => s.replace(/\s+/g, ' ').trim();
/** The top-level keys of the first ```json block in a section. */
function jsonKeysOf(section) {
const m = section?.match(/```json\s*\n([\s\S]*?)\n```/);
if (!m) return null;
try {
return Object.keys(JSON.parse(m[1]));
} catch {
return null;
}
}
async function checkRunicNpcApi(md) {
const hint = 'docs main:runicnpc/API.md';
// The version the specification describes, against the one platform.json quotes (and
// checkFacts holds to the plugin's own plugin.toml). Together they close the loop.
const version = Number(md.match(/\*\*API version (\d+)\*\*/)?.[1]);
if (version !== platform.runicnpc.api) {
fail('RunicNPC API version', `${hint} describes API ${version || '(none found)'}; platform.json says ${platform.runicnpc.api}`);
} else ok(`RunicNPC API version (${version})`);
// Calls: `### \`RunicNpc_X(params)\` → \`returns\`` headings, compared by whole signature.
const theirCalls = new Map(
[...md.matchAll(/^### `(RunicNpc_\w+)\(([^)]*)\)` → `([^`]+)`\s*$/gm)].map((m) => [m[1], collapse(`(${m[2]}) → ${m[3]}`)]),
);
const myCalls = new Map(Object.entries(runicnpcCalls).map(([n, c]) => [n, collapse(`(${c.params}) → ${c.returns}`)]));
compareSignatures('RunicNPC call', myCalls, theirCalls, hint);
// Hooks: the first cell of each row of "Hooks it raises".
const hooksSection = mdSection(md, '## Hooks it raises');
if (!hooksSection) fail('RunicNPC hooks', `no "## Hooks it raises" section in ${hint}`);
else {
const theirHooks = new Map(
[...hooksSection.matchAll(/^\| `(OnRunicNpc\w+)\(([^)]*)\)` \|/gm)].map((m) => [m[1], collapse(`(${m[2]})`)]),
);
const myHooks = new Map(Object.entries(runicnpcHooks).map(([n, h]) => [n, collapse(`(${h.params})`)]));
compareSignatures('RunicNPC hook', myHooks, theirHooks, hint);
}
// The data shapes, by field name (D73).
const shape = (label, heading, mine, read) => {
const section = mdSection(md, heading);
const theirs = section && read(section);
if (!theirs || theirs.length === 0) fail(label, `could not read the "${heading}" section of ${hint}`);
else compareSets(label, mine, theirs, `${hint} "${heading.replace(/^#+ /, '')}"`);
};
shape('RunicNPC owner', '## Owners', Object.keys(runicnpcOwners), (s) => firstCellNames(s).flat());
shape('RunicNpc_List key', '### `RunicNpc_List', Object.keys(runicnpcListKeys), (s) => firstCellNames(s).flat());
// A profile's fields. A cell may name several (`hurtByPlayers`, `hurtsPlayers`), and a bare
// name after a dotted one shares its prefix (`phases[].damageDealt`, `aimCone`).
shape(
'RunicNPC profile field',
'### A profile',
Object.values(runicnpcProfileFields).flatMap((group) => Object.keys(group)),
(s) =>
firstCellNames(s).flatMap(([first, ...rest]) => {
const prefix = first.includes('.') ? first.slice(0, first.lastIndexOf('.') + 1) : '';
return [first, ...rest.map((n) => (n.includes('.') ? n : prefix + n))];
}),
);
// A placement's keys: the example's, plus the optional ones its bullets introduce.
shape('RunicNPC placement key', '### A placement', Object.keys(runicnpcPlacementKeys), (s) => {
const keys = jsonKeysOf(s);
return keys && [...new Set([...keys, ...[...s.matchAll(/^- `(\w+)`/gm)].map((m) => m[1])])];
});
shape('RunicNPC route key', '### A route', Object.keys(runicnpcRouteKeys), jsonKeysOf);
// The page itself: every call has exactly one <Signature call="…" />, so "in full" is held
// by the build and not by whoever last edited api.mdx.
const page = readFileSync(path.join(ROOT, 'src/content/docs/docs/rust/runicnpc/api.mdx'), 'utf8');
const onPage = [...page.matchAll(/<Signature\s+call="(\w+)"/g)].map((m) => m[1]);
let covered = true;
for (const call of Object.keys(runicnpcCalls)) {
const n = onPage.filter((c) => c === call).length;
if (n !== 1) {
covered = false;
fail(`RunicNPC API page: ${call}`, `has ${n} <Signature call="${call}" /> on api.mdx — every call needs exactly one, with its prose`);
}
}
if (covered) ok(`RunicNPC API page covers every call (${onPage.length})`);
}
/** Compare name → signature maps: both directions by name, then each shared name by signature. */
function compareSignatures(label, mine, theirs, hint) {
compareSets(label, [...mine.keys()], [...theirs.keys()], hint);
let same = true;
for (const [name, sig] of mine) {
if (theirs.has(name) && theirs.get(name) !== sig) {
same = false;
fail(`${label} ${name}`, `signature differs — here "${sig}", ${hint} "${theirs.get(name)}"`);
}
}
if (same) ok(`${label} signatures (${mine.size})`);
}
/** The text of a C# method, by brace counting from the first brace after its name. */
function methodBody(source, name) {
const start = source.search(new RegExp(`\\b${name}\\s*\\(`));
if (start < 0) return null;
const open = source.indexOf('{', start);
let depth = 0;
for (let i = open; i < source.length; i++) {
if (source[i] === '{') depth++;
else if (source[i] === '}' && --depth === 0) return source.slice(open + 1, i);
}
return null;
}
function checkRunicNpcSource(cs) {
const hint = 'runicnpc-rust main:plugin/RunicNPC.cs';
// The verbs: every `rnpc.<verb>` console command. The chat command answers the same verbs.
compareSets(
'RunicNPC command',
[...new Set(Object.values(runicnpcCommands).flatMap((s) => Object.keys(s)).map((usage) => usage.split(' ')[0]))],
[...cs.matchAll(/\[ConsoleCommand\("rnpc\.(\w+)"\)\]/g)].map((m) => m[1]),
`${hint} [ConsoleCommand]`,
);
// A command's permission must be one the plugin registers.
const perms = [...cs.matchAll(/const\s+string\s+Perm\w+\s*=\s*"(runicnpc\.\w+)"/g)].map((m) => m[1]);
compareSets('RunicNPC permission', Object.keys(runicnpcPermissions), perms, `${hint} Perm constants`);
for (const [section, commands] of Object.entries(runicnpcCommands)) {
for (const [usage, c] of Object.entries(commands)) {
if (c.perm.startsWith('runicnpc.') && !perms.includes(c.perm)) {
fail(`RunicNPC command ${usage}`, `(${section}) needs "${c.perm}", which the plugin does not register`);
}
}
}
const options = methodBody(cs, 'ParseOptions');
if (!options) fail('RunicNPC place option', `could not find ParseOptions in ${hint}`);
else {
compareSets(
'RunicNPC place option',
Object.keys(runicnpcPlaceOptions),
[...options.matchAll(/case\s+"(\w+)":/g)].map((m) => m[1]),
`${hint} ParseOptions`,
);
}
// The config: `[JsonProperty("name")] public Type Field`, and a field whose type is another
// config class is a section, its keys written `section.key`.
const jsonKeys = (className, prefix = '') => {
const body = classBody(cs, className);
if (!body) return null;
return [...body.matchAll(/\[JsonProperty\("(\w+)"\)\]\s*public\s+(\w+)\s+\w+/g)].flatMap(([, key, type]) => {
const nested = /Config$/.test(type) ? jsonKeys(type, `${prefix}${key}.`) : null;
return nested ?? [`${prefix}${key}`];
});
};
const configKeys = jsonKeys('PluginConfig');
if (!configKeys) fail('RunicNPC.json', `could not find class PluginConfig in ${hint}`);
else compareSets('RunicNPC.json', Object.keys(runicnpcConfig), configKeys, `${hint} PluginConfig`);
}
async function run() {
if (!TOKEN) {
console.error('checkReference: GITEA_TOKEN is not set. This check cannot run anonymously.');
@@ -122,13 +372,12 @@ async function run() {
// Parsed from the serde structs rather than from a sample file, because the sample is
// GENERATED by the binary on first run and no committed copy is authoritative. Each
// `pub name: T` inside a `struct XCfg` is one key, and the struct name gives the section.
const configRs = await raw('link', 'sidecar/src/config.rs');
const sidecarKeys = [];
for (const m of configRs.matchAll(/struct\s+(\w+)Cfg\s*\{([\s\S]*?)\n\}/g)) {
const section = m[1].toLowerCase();
for (const f of m[2].matchAll(/pub\s+(\w+)\s*:/g)) sidecarKeys.push(`${section}.${f[1]}`);
}
compareSets('sidecar.toml', Object.keys(sidecarConfig), sidecarKeys, 'link main:sidecar/src/config.rs');
compareSets(
'sidecar.toml',
Object.keys(sidecarConfig),
tomlKeysOf(await raw('link', 'sidecar/src/config.rs')),
'link main:sidecar/src/config.rs',
);
// ── 3. Installer commands ─────────────────────────────────────────────────
const cliRs = await raw('installer', 'src/cli.rs');
@@ -168,13 +417,94 @@ async function run() {
//
// Existence only. A link to a document that moved is the single most likely way this
// section breaks, and it is exactly what a build can answer.
for (const docPath of Object.keys(canonicalDocs)) {
for (const docPath of Object.values(canonicalDocs).flatMap((group) => Object.keys(group))) {
const url = `${BASE}/api/v1/repos/${ORG}/docs/contents/${docPath}?ref=main`;
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
if (res.ok) ok(`canonical doc ${docPath}`);
else fail(`canonical doc ${docPath}`, `not found in docs main (HTTP ${res.status})`);
}
// ── 7. Rust: rust-link's sidecar.toml, and the variables that override it ──
//
// PLAN.md §16, phase 15. The same parser as uo-link's — both sidecars declare their file
// as serde structs — plus the environment overrides, which a Pterodactyl egg sets and an
// operator meets on the panel before they ever see the file.
const rustConfigRs = await raw('Rust-Link', 'sidecar/src/config.rs');
compareSets(
'rust-link sidecar.toml',
Object.keys(rustSidecarConfig),
tomlKeysOf(rustConfigRs),
'Rust-Link main:sidecar/src/config.rs',
);
compareSets(
'rust-link environment variable',
Object.keys(rustSidecarEnv),
[...rustConfigRs.matchAll(/get\("(RUSTLINK_[A-Z_]+)"\)/g)].map((m) => m[1]),
'Rust-Link main:sidecar/src/config.rs',
);
for (const [envName, key] of Object.entries(rustSidecarEnv)) {
if (!(key in rustSidecarConfig)) fail(`rust-link environment variable ${envName}`, `says it overrides "${key}", which is not a key listed here`);
}
// ── 8. Rust: the bridge plugin's RunicGateway.json ────────────────────────
//
// The public fields of `PluginConfig`, which the framework serialises as the file.
const pluginCs = await raw('Rust-Plugins', 'overlay/oxide/plugins/RunicGateway.cs');
const pluginBody = classBody(pluginCs, 'PluginConfig');
if (!pluginBody) {
fail('RunicGateway.json', 'could not find class PluginConfig in Rust-Plugins main:overlay/oxide/plugins/RunicGateway.cs');
} else {
compareSets(
'RunicGateway.json',
Object.values(rustPluginConfig).flatMap((group) => Object.keys(group)),
[...pluginBody.matchAll(/public\s+[\w<>[\],]+\s+(\w+)\s*=/g)].map((m) => m[1]),
'Rust-Plugins main:overlay/oxide/plugins/RunicGateway.cs PluginConfig',
);
}
// ── 9. Rust: the event kinds, and who may see each ────────────────────────
//
// D71: checked against the module's own catalogue, because the module is what enforces
// the boundary (the same reasoning as check 5). Three comparisons, each a security
// statement: a kind listed public here must be public there, a presence kind must be one
// of the module's presence kinds, and a staff kind must be staff there. A kind moved from
// staff to public upstream fails this check twice over, which is the point.
const catalogue = await raw('Module-Rust', 'server/catalogue.js');
const upPublic = frozenListOf(catalogue, 'PUBLIC_KINDS');
const upStaff = frozenListOf(catalogue, 'STAFF_KINDS');
const upPresence = frozenListOf(catalogue, 'PRESENCE_KINDS');
if (!upPublic || !upStaff || !upPresence) {
fail('Rust event kinds', 'could not find PUBLIC_KINDS, STAFF_KINDS and PRESENCE_KINDS in Module-Rust main:server/catalogue.js');
} else {
const hint = 'Module-Rust main:server/catalogue.js';
compareSets('Rust presence kind', Object.keys(rustEventKinds.presence), upPresence, `${hint} PRESENCE_KINDS`);
compareSets(
'Rust public kind',
Object.keys(rustEventKinds.public),
upPublic.filter((k) => !upPresence.includes(k)),
`${hint} PUBLIC_KINDS (less its presence kinds)`,
);
compareSets('Rust staff kind', Object.keys(rustEventKinds.staff), upStaff, `${hint} STAFF_KINDS`);
for (const k of upPresence) {
if (!upPublic.includes(k)) fail(`Rust presence kind ${k}`, 'is a presence kind upstream but not a public one — the page explains presence as a narrowing of public, so re-read it');
}
}
// ── 10. RunicNPC: the API, against its specification ──────────────────────
//
// PLAN.md §16, D62 and D73. The one place this site carries a contract in full rather than
// linking to it, so the one place it must be held to the contract most tightly: every call
// and hook by its whole signature, and every field name of every data shape, both ways.
// `docs` `main:runicnpc/API.md` is normative, so it is the authority, not the plugin source.
await checkRunicNpcApi(await raw('docs', 'runicnpc/API.md'));
// ── 11. RunicNPC: the commands, permissions, options and config ───────────
//
// Names, checked against the plugin's own source the way RunicGateway.json is (check 8):
// the console verbs it registers, the permissions it registers, the `key=` options
// `place` and `here` parse, and the JSON keys of its config classes.
checkRunicNpcSource(await raw('runicnpc-rust', 'plugin/RunicNPC.cs'));
// ── Report ────────────────────────────────────────────────────────────────
if (failures.length === 0) {
console.log(`checkReference: ${checked.length} enumeration check(s) passed against their sources.`);

View File

@@ -22,13 +22,15 @@
* No token and no network: both trees are in this repository.
*/
import { docsSidebar, plannedSidebar } from '../src/config/sidebar.mjs';
import { docsSidebar, plannedSidebar, flatLabels } from '../src/config/sidebar.mjs';
const failures = [];
const fail = (what, detail) => failures.push({ what, detail });
const live = new Map(docsSidebar.map((g) => [g.label, g.items.map((i) => i.label)]));
const planned = new Map(Object.entries(plannedSidebar));
// A nested group (RunicNPC inside Rust, phase 16) flattens to `Group › Page` labels, so its
// pages and their order are held to the plan exactly as a top-level group's are.
const live = new Map(docsSidebar.map((g) => [g.label, flatLabels(g.items)]));
const planned = new Map(Object.entries(plannedSidebar).map(([label, items]) => [label, flatLabels(items)]));
// ── Groups ──────────────────────────────────────────────────────────────────
for (const label of live.keys()) {

449
scripts/checkTerms.mjs Normal file
View File

@@ -0,0 +1,449 @@
#!/usr/bin/env node
/**
* checkTerms.mjs — PLAN.md §16, D63 and D64. The twelfth check, added in phase 14 and widened
* to the whole site in phase 17 (D79).
*
* D63: outside a game's own section, the site may NAME the games it supports, but it may not
* use their VOCABULARY. Core concepts keep core's names — a Team, a game server, the sidecar,
* the bridge plugin, the game module — because that is what core itself calls them, and a
* site that says "shard" on a core page is describing one game's deployment as though it were
* the platform.
*
* D64: a convention that holds only while everyone remembers it does not hold. This is the
* same argument `checkTokens.mjs` makes for colours, applied to words. The vocabulary problem
* was measured before this check existed — "shard" 227 times in 45 files — and none of that
* was anybody's decision; it was the residue of a site written while there was one game.
*
* It runs in two passes, one before the build and one after.
*
* node scripts/checkTerms.mjs # the SOURCE pass: docs pages and the sidebar
* node scripts/checkTerms.mjs --built # the BUILT pass: every page in dist/, as rendered
*
* ── The source pass (phase 14) ──────────────────────────────────────────────────────────
*
* - every page under `src/content/docs`, frontmatter included (a title and a description
* are what a reader sees first, in the sidebar and in search results);
* - `src/config/sidebar.mjs`, as DATA rather than as text: every group label and every
* page label, in both trees. Its comments are not scanned, because a comment is not
* something a reader of the site ever sees.
*
* It needs no build, so it runs early and fails fast, and it names a file and a line.
*
* ── The built pass (phase 17, D79) ──────────────────────────────────────────────────────
*
* The marketing pages are `.astro` templates fed from `src/data/`, so most of the words a
* reader sees on them are not in the template at all: a capability's label, a screenshot's
* caption, a version read from `platform.json`. A source scan sees an expression and skips
* it, or sees an id like `shard-status` and takes it for prose. So this pass reads what the
* build actually produced — the same argument `checkLinks.mjs` makes for links. For every
* page in `dist/client` it reads the visible text, plus `alt`, `title`, `aria-label`,
* `placeholder`, the `<title>` and the meta description. It does not read link targets,
* scripts, styles or comments. It names a route and a snippet rather than a line; the source
* pass still gives lines for the docs, where most of the words are.
*
* Two parts of every docs page are skipped, because each is checked somewhere better:
* Starlight's sidebar (the source pass reads both trees as data, group by group) and the
* previous/next links (each is a neighbouring page's title, checked on that page).
*
* ── Where a game's words are allowed ────────────────────────────────────────────────────
*
* - in that game's own docs directory (`GAME_DIRS`) and its own sidebar group — a group
* whose label is the game's `name` in `platform.json`;
* - on that game's own routes (`GAME_ROUTES`): its docs group, its module page, and for
* Rust the standalone RunicNPC page;
* - inside an element marked `data-game="…"`: `<GameExample>` on a docs page (D68) and a
* game-tagged `<Screenshot>` (D67). Both print the game's name beside the words, which is
* the bargain: a game's words are honest on a core page when the game is named right
* there. In the source pass, the `<GameExample>` tags themselves mark the region.
*
* What is NOT read, deliberately: link targets and bare URLs or paths (a repository is called
* what it is called, and an address is not prose — but LINK TEXT is read, so `[Module-uo](…)`
* fails and `[releases](…)` passes), MDX `import` lines, and, in the source pass only, `{…}`
* expressions — the built pass reads what they rendered.
*
* No token and no network: everything it reads is in this repository or its build output.
*/
import { readFileSync, existsSync } from 'node:fs';
import { readdir } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
import { docsSidebar, plannedSidebar, flatLabels } from '../src/config/sidebar.mjs';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
const platform = JSON.parse(readFileSync(path.join(ROOT, 'src/data/platform.json'), 'utf8'));
const BUILT = process.argv.includes('--built');
/**
* The words, each tagged with the game it belongs to. Matching is case-insensitive and on
* word boundaries, so "shard" does not match `SHARD_VISIBILITY` and "wipe" does not match
* "wiped" unless it is listed.
*
* A word is on this list because it is a game's name for something core has its own name for
* (shard → game server, guild and clan → Team), or because it names one game's component
* (uo-link → the sidecar, ServUO → the game server). Game NAMES — Ultima Online, UO, Rust —
* are not on it: D63 allows them everywhere. Steam is not on it either: Steam sign-in is a
* core identity provider, even though Rust was its first user.
*/
const TERMS = [
{ game: 'uo', word: 'shard', re: /\bshards?\b/gi },
{ game: 'uo', word: 'ServUO', re: /\bservuo\b/gi },
{ game: 'uo', word: 'uo-link', re: /\buo-?link\b/gi },
{ game: 'uo', word: 'Module-uo', re: /\bmodule-uo\b/gi },
{ game: 'uo', word: 'Bridge.cfg', re: /\bbridge\.cfg\b/gi },
{ game: 'uo', word: 'cliloc', re: /\bclilocs?\b/gi },
{ game: 'uo', word: 'guild', re: /\bguilds?\b/gi },
{ game: 'uo', word: 'IDOC', re: /\bidocs?\b/gi },
{ game: 'rust', word: 'rust-link', re: /\brust-?link\b/gi },
{ game: 'rust', word: 'Rust-Plugins', re: /\brust-plugins\b/gi },
{ game: 'rust', word: 'Module-Rust', re: /\bmodule-rust\b/gi },
{ game: 'rust', word: 'Oxide', re: /\boxide\b/gi },
{ game: 'rust', word: 'Carbon', re: /\bcarbon\b/gi },
{ game: 'rust', word: 'uMod', re: /\bumod\b/gi },
{ game: 'rust', word: 'clan', re: /\bclans?\b/gi },
{ game: 'rust', word: 'wipe', re: /\bwipes?\b/gi },
];
/** Each game's own docs directory. A page under one may use that game's words. */
const GAME_DIRS = {
uo: 'src/content/docs/docs/ultima-online/',
rust: 'src/content/docs/docs/rust/',
};
/**
* Each game's own routes, for the built pass: its docs group, the page about its module, and
* for Rust the standalone RunicNPC page (D61), which a server owner reads without knowing what
* the platform is. A route matches when the page's path starts with one of these.
*/
const GAME_ROUTES = {
uo: ['/docs/ultima-online/', '/modules/uo/'],
rust: ['/docs/rust/', '/modules/rust/', '/runicnpc/'],
};
/**
* The allowlist: an exact phrase on one page that may use a word the rule would otherwise
* refuse. Short on purpose, and every entry says why. `file` is where the source pass meets
* it and `route` is where the built pass does. An entry that no longer matches fails the
* check too, so the list cannot rot into a set of permanent exemptions.
*/
const ALLOW = [
{
file: 'src/content/docs/docs/administration/notifications-and-email.mdx',
route: '/docs/administration/notifications-and-email/',
text: 'Guild (server) ID',
why: "Discord's own word, not a game's: it is the label on core's Discord Bot screen.",
},
];
for (const game of new Set([...Object.keys(GAME_DIRS), ...Object.keys(GAME_ROUTES)])) {
if (!platform.games[game]) throw new Error(`checkTerms: "${game}" is given a section here, but platform.json has no such game.`);
}
for (const t of TERMS) {
if (!platform.games[t.game]) throw new Error(`checkTerms: "${t.word}" is tagged "${t.game}", which platform.json does not know.`);
}
const failures = [];
const fail = (where, detail) => failures.push({ where, detail });
/** Replace a span with spaces, keeping newlines, so later line numbers stay true. */
const blank = (text) => text.replace(/[^\n]/g, ' ');
/** Hits for every term the given context may not use. `allowed` is a game key, or null. */
function scan(text, allowed) {
const hits = [];
for (const t of TERMS) {
if (t.game === allowed) continue;
t.re.lastIndex = 0;
for (const m of text.matchAll(t.re)) hits.push({ term: t, value: m[0], index: m.index });
}
return hits;
}
const gameName = (game) => platform.games[game].name;
async function* walk(dir, pattern) {
let entries;
try {
entries = await readdir(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) yield* walk(full, pattern);
else if (pattern.test(entry.name)) yield full;
}
}
// ═══ The source pass ═══════════════════════════════════════════════════════════════════
/** The game whose directory holds this file, or null for a core page. */
function gameOfPath(relative) {
const posix = relative.split(path.sep).join('/');
for (const [game, dir] of Object.entries(GAME_DIRS)) if (posix.startsWith(dir)) return game;
return null;
}
function lineOf(source, index) {
return source.slice(0, index).split('\n').length;
}
/**
* Turn an MDX source into the text a reader would actually see, with everything that is not
* prose blanked out. Returns that text plus the GameExample regions, as offsets into it.
*/
function proseOf(source, relative) {
let text = source;
// GameExample regions first, while the tags are still intact. Recorded, then the tags
// themselves are blanked so the attribute does not read as prose.
const regions = [];
for (const m of text.matchAll(/<GameExample\s+game="([^"]*)"\s*>([\s\S]*?)<\/GameExample>/g)) {
const game = m[1];
if (!platform.games[game]) {
fail(`${relative}:${lineOf(source, m.index)}`, `<GameExample game="${game}"> names a game platform.json does not have`);
}
regions.push({ game, start: m.index, end: m.index + m[0].length });
}
text = text.replace(/<\/?GameExample\b[^>]*>/g, blank);
text = text.replace(/<!--[\s\S]*?-->/g, blank); // HTML comments
text = text.replace(/^import\s.*$/gm, blank); // MDX imports
text = text.replace(/\]\([^)\s]*\)/g, (m) => '] ' + blank(m.slice(2))); // link targets, not their text
text = text.replace(/\b(?:href|src)=(?:"[^"]*"|\{`[^`]*`\})/g, blank); // JSX/HTML link targets
text = text.replace(/\bhttps?:\/\/[^\s)>"'`]+/g, blank); // bare URLs
// `{…}` expressions, outside code fences only — a fenced JSON example's braces are prose.
// Innermost first, repeatedly, so nested and multi-line expressions both go.
const parts = text.split(/(^```[\s\S]*?^```)/m);
for (let i = 0; i < parts.length; i += 2) {
let prev;
do {
prev = parts[i];
parts[i] = parts[i].replace(/\{[^{}]*\}/g, blank);
} while (parts[i] !== prev);
}
text = parts.join('');
return { text, regions };
}
async function sourcePass() {
// ── 1. The documentation pages ──
let files = 0;
const allowUsed = new Set();
for await (const file of walk(path.join(ROOT, 'src', 'content', 'docs'), /\.mdx?$/)) {
const relative = path.relative(ROOT, file).split(path.sep).join('/');
const source = readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
files++;
let { text, regions } = proseOf(source, relative);
for (const [i, entry] of ALLOW.entries()) {
if (entry.file !== relative) continue;
if (text.includes(entry.text)) {
allowUsed.add(i);
text = text.split(entry.text).join(blank(entry.text));
}
}
const pageGame = gameOfPath(relative);
for (const hit of scan(text, pageGame)) {
const region = regions.find((r) => hit.index >= r.start && hit.index < r.end);
if (region && region.game === hit.term.game) continue;
const where = region ? `inside <GameExample game="${region.game}">` : pageGame ? `in the ${gameName(pageGame)} group` : 'on a core page';
fail(`${relative}:${lineOf(source, hit.index)}`, `"${hit.value}" is ${gameName(hit.term.game)} vocabulary, ${where}`);
}
}
for (const [i, entry] of ALLOW.entries()) {
if (!allowUsed.has(i)) fail(`allowlist: ${entry.file}`, `"${entry.text}" no longer appears there — remove the entry`);
}
// ── 2. The sidebar, as data ──
const gameByName = new Map(Object.entries(platform.games).map(([key, g]) => [g.name, key]));
const trees = [
['docsSidebar', docsSidebar.map((g) => [g.label, flatLabels(g.items)])],
['plannedSidebar', Object.entries(plannedSidebar).map(([label, items]) => [label, flatLabels(items)])],
];
let labels = 0;
for (const [treeName, groups] of trees) {
for (const [groupLabel, items] of groups) {
const game = gameByName.get(groupLabel) ?? null;
for (const label of [groupLabel, ...items]) {
labels++;
for (const hit of scan(label, game)) {
fail(
`src/config/sidebar.mjs ${treeName} → ${groupLabel}`,
`"${label}" uses "${hit.value}", ${gameName(hit.term.game)} vocabulary, ${game ? `in the ${gameName(game)} group` : 'in a core group'}`,
);
}
}
}
}
return `${files} docs pages and ${labels} sidebar labels use only their own game's words`;
}
// ═══ The built pass ════════════════════════════════════════════════════════════════════
const DIST = path.join(ROOT, 'dist', 'client');
/** `dist/client/a/b/index.html` → `/a/b/`; `dist/client/404.html` → `/404`. */
function routeOf(file) {
const rel = path.relative(DIST, file).split(path.sep).join('/');
if (rel === 'index.html') return '/';
if (rel.endsWith('/index.html')) return `/${rel.slice(0, -'index.html'.length)}`;
return `/${rel.replace(/\.html$/, '')}`;
}
function gameOfRoute(route) {
for (const [game, prefixes] of Object.entries(GAME_ROUTES)) {
if (prefixes.some((p) => route.startsWith(p))) return game;
}
return null;
}
/**
* Where the element opening at `start` closes, counting nested elements of the same name.
* Astro's output is well formed, which is what makes this enough without a parser.
*/
function elementEnd(html, start, tag) {
const re = new RegExp(`<(/?)${tag}\\b[^>]*?(/?)>`, 'gi');
re.lastIndex = start;
let depth = 0;
for (let m = re.exec(html); m; m = re.exec(html)) {
if (m[2] === '/') continue; // self-closing
depth += m[1] === '/' ? -1 : 1;
if (depth === 0) return re.lastIndex;
}
return html.length;
}
/** Every element whose opening tag matches `openRe`, as `{ start, end, match }`. */
function elements(html, openRe) {
const found = [];
for (const m of html.matchAll(openRe)) {
const tag = /^<([a-z0-9-]+)/i.exec(m[0])[1];
found.push({ start: m.index, end: elementEnd(html, m.index, tag), match: m });
}
return found;
}
const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', rsquo: '’', lsquo: '‘', ldquo: '“', rdquo: '”', mdash: '—', ndash: '–', hellip: '…', rarr: '→', middot: '·' };
const decode = (s) =>
s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
if (e[0] === '#') return String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1)));
return ENTITIES[e.toLowerCase()] ?? m;
});
/**
* Elements whose text runs on into the next word with no space between: a word split across
* two `<span>`s by a syntax highlighter is still one word to a reader. Everything else is a
* boundary, so `<h3>Guilds</h3><p>Guild…` does not read as "GuildsGuild".
*/
const INLINE = /^(?:a|abbr|b|bdi|bdo|cite|code|data|dfn|em|i|kbd|mark|q|s|samp|small|span|strong|sub|sup|time|u|var|wbr)$/i;
/** The words a reader sees in a piece of HTML: its text, and the attributes that are read aloud or shown. */
function visibleText(html) {
const attrs = [];
for (const m of html.matchAll(/\s(?:alt|title|aria-label|placeholder)="([^"]*)"/gi)) attrs.push(m[1]);
let text = html.replace(/<\/?([a-z][a-z0-9-]*)\b[^>]*>/gi, (_, tag) => (INLINE.test(tag) ? '' : ' '));
text = decode([text, ...attrs.map(decode)].join(' \n '));
text = text.replace(/\bhttps?:\/\/\S+/g, ' '); // bare URLs
text = text.replace(/(^|[\s(“"'])\/[\w./#?=&%-]+/g, '$1 '); // bare paths — an address, not prose
return text.replace(/\s+/g, ' ');
}
function snippet(text, index, length) {
const from = Math.max(0, index - 50);
const to = Math.min(text.length, index + length + 50);
return `${from > 0 ? '…' : ''}${text.slice(from, to).trim()}${to < text.length ? '…' : ''}`;
}
async function builtPass() {
if (!existsSync(DIST)) {
console.error('checkTerms --built: dist/client does not exist. Run `npm run build` first.');
process.exit(1);
}
let pages = 0;
let regionsSeen = 0;
const allowUsed = new Set();
for await (const file of walk(DIST, /\.html$/)) {
const route = routeOf(file);
let html = readFileSync(file, 'utf8');
pages++;
// The head: only the parts a reader sees, in a tab or a search result.
const head = /<head\b[\s\S]*?<\/head>/i.exec(html)?.[0] ?? '';
const headText = [/<title>([\s\S]*?)<\/title>/i.exec(head)?.[1] ?? '', /<meta\s+name="description"\s+content="([^"]*)"/i.exec(head)?.[1] ?? ''].join(' \n ');
html = html.replace(/<head\b[\s\S]*?<\/head>/i, ' ');
html = html.replace(/<(script|style|template|noscript)\b[\s\S]*?<\/\1>/gi, ' ');
html = html.replace(/<!--[\s\S]*?-->/g, ' ');
// Checked elsewhere (see the header): Starlight's sidebar and its previous/next links.
for (const skip of [/<nav\b[^>]*\baria-label="Main"[^>]*>/gi, /<div\b[^>]*\bclass="pagination-links\b[^>]*>/gi]) {
for (const el of elements(html, skip).reverse()) html = html.slice(0, el.start) + ' ' + html.slice(el.end);
}
const pageGame = gameOfRoute(route);
const pieces = [{ text: decode(headText), allowed: pageGame, where: 'in the page title or description' }];
// Regions marked with a game. Read with that game's words allowed, then cut out.
for (const el of elements(html, /<[a-z][a-z0-9-]*\b[^>]*\bdata-game="([^"]*)"[^>]*>/gi).reverse()) {
const game = el.match[1];
regionsSeen++;
if (!platform.games[game]) {
fail(route, `an element is marked data-game="${game}", which platform.json does not have`);
continue;
}
pieces.push({ text: visibleText(html.slice(el.start, el.end)), allowed: game, also: pageGame, where: `inside a block marked ${gameName(game)}` });
html = html.slice(0, el.start) + ' ' + html.slice(el.end);
}
pieces.push({ text: visibleText(html), allowed: pageGame, where: pageGame ? `on a ${gameName(pageGame)} page` : 'on a core page' });
for (const piece of pieces) {
let { text } = piece;
for (const [i, entry] of ALLOW.entries()) {
if (entry.route !== route || !text.includes(entry.text)) continue;
allowUsed.add(i);
text = text.split(entry.text).join(' '.repeat(entry.text.length));
}
for (const hit of scan(text, piece.allowed)) {
if (piece.also && hit.term.game === piece.also) continue;
fail(route, `"${hit.value}" is ${gameName(hit.term.game)} vocabulary, ${piece.where}\n ${snippet(text, hit.index, hit.value.length)}`);
}
}
}
for (const [i, entry] of ALLOW.entries()) {
if (!allowUsed.has(i)) fail(`allowlist: ${entry.route}`, `"${entry.text}" no longer appears in the built page — remove the entry`);
}
return `${pages} built pages use only their own game's words (${regionsSeen} game-marked blocks read with their game's words allowed)`;
}
// ═══ Report ════════════════════════════════════════════════════════════════════════════
const summary = BUILT ? await builtPass() : await sourcePass();
if (failures.length === 0) {
console.log(`checkTerms${BUILT ? ' --built' : ''}: ${summary} (${TERMS.length} terms, ${ALLOW.length} allowlisted phrase${ALLOW.length === 1 ? '' : 's'}).`);
} else {
console.error(`\ncheckTerms${BUILT ? ' --built' : ''}: ${failures.length} game word(s) outside their game's section:\n`);
for (const f of failures) console.error(` ✗ ${f.where}\n ${f.detail}`);
console.error(`
PLAN.md §16, D63: name the games anywhere, but keep their vocabulary in their own section.
Use core's word instead — a Team, a game server, the sidecar, the bridge plugin, the game
module. A marketing page describes what a game module adds in core's words and links to
the game's own page (D75). If a docs page genuinely needs a game's real example, wrap it in
<GameExample game="…"> (D68); a screenshot of a game screen carries its game tag (D67).
Add to the allowlist in this script only for a word that is not a game's at all, and say why.
`);
process.exit(1);
}

205
scripts/mockRustDemo.mjs Normal file
View File

@@ -0,0 +1,205 @@
#!/usr/bin/env node
/**
* mockRustDemo.mjs — the game data on the Rust demo's screenshots. PLAN.md §16 phase 18, D81.
*
* node scripts/mockRustDemo.mjs > rust-demo.sql
* docker exec -i <db container> mariadb -u<user> -p<password> <rust demo db> < rust-demo.sql
*
* Prints SQL; it connects to nothing. Run it after `seedDemo.mjs --game rust`, with the demo
* site connected to its server at least once, so the server row and its current wipe exist.
*
* ---------------------------------------------------------------------------------------
* WHY THIS IS MOCK DATA, WHEN THE UO CAPTURES ARE NOT
* ---------------------------------------------------------------------------------------
* D4 asks for real captures, and phase 9 got them from a real shard with a person signed in.
* The Rust rig has no players. Phase 18 first staged stand-in players on it with a rig-only
* plugin; that cost a morning of a server the update had left rebuilding its navmesh, and the
* org lead chose this instead (D81): the feed, the leaderboard and the linked Steam account
* are written into the demo's database here, in the module's own row shapes, and everything
* else on the screens is the real server's (its status, its world map, its sync state).
*
* Every name is a role (D80): player, player2 … player7, and moderator. The Steam ids sit in a
* range no real account uses.
*
* Re-running replaces what it wrote: it deletes the server's events, stats, weapon kills and
* these players first. Real events that arrived from the server are deleted with them.
*/
const SERVER = 'rust-oxide';
const ID_BASE = 76561199920000000n;
/** The cast. `n` makes the Steam id; `user` links one to a site account by username. */
const CAST = [
{ n: 1, name: 'player', user: 'player' },
{ n: 2, name: 'player2' },
{ n: 3, name: 'player3' },
{ n: 4, name: 'player4' },
{ n: 5, name: 'player5' },
{ n: 6, name: 'player6' },
{ n: 7, name: 'player7' },
{ n: 9, name: 'moderator' },
];
const steam = (n) => String(ID_BASE + BigInt(n));
const who = (n) => CAST.find((c) => c.n === n).name;
const now = Date.now();
const ago = (minutes) => now - Math.round(minutes * 60_000);
// ── The feed, oldest first ─────────────────────────────────────────────────────────────
//
// Each frame is the shape the bridge plugin emits (copied from frames the walk database
// holds), less `serverId`/`wipeId`/`t`/`type`, which `frame()` adds.
const death = (killer, victim, weapon, distance, grid, extra = {}) => ({
kind: 'player.death',
steamId: steam(victim),
name: who(victim),
attackerId: steam(killer),
attackerName: who(killer),
attackerType: 'player',
weapon,
distance,
grid,
sleeping: false,
...extra,
});
const world = (event, fields = {}) => ({ kind: 'world.event', event, ...fields });
const FEED = [
[150, { kind: 'player.connected', steamId: steam(1), name: who(1) }],
[148, { kind: 'player.connected', steamId: steam(2), name: who(2) }],
[146, { kind: 'player.connected', steamId: steam(3), name: who(3) }],
[141, world('cargo.arrived', { x: 2900, z: -2100 })],
[137, { kind: 'player.connected', steamId: steam(9), name: who(9) }],
[131, { kind: 'player.chat', steamId: steam(2), name: who(2), channel: 'Global', message: 'anyone selling scrap at outpost?' }],
[126, death(3, 4, 'bolt_rifle.entity', 187.4, 'AF10')],
[119, { kind: 'player.connected', steamId: steam(5), name: who(5) }],
[112, world('crate.hack.started', { steamId: steam(2), name: who(2), where: 'oilrig_small', x: 3358, z: 1721 })],
[104, death(1, 2, 'ak47u.entity', 22.4, 'R18')],
[98, world('heli.arrived', { x: 400, z: -900 })],
[96, world('crate.unlocked', { steamId: steam(5), name: who(5), where: 'oilrig_small', x: 3358, z: 1721 })],
[91, { kind: 'player.connected', steamId: steam(6), name: who(6) }],
[86, death(5, 3, 'lr300.entity', 64.9, 'H7')],
[80, world('heli.downed', {
x: 2453, z: -943,
credit: {
blow: steam(3), last: steam(1), most: steam(1),
damagers: [{ steamId: steam(1), damage: 5200 }, { steamId: steam(3), damage: 3900 }, { steamId: steam(6), damage: 900 }],
},
names: { [steam(1)]: who(1), [steam(3)]: who(3), [steam(6)]: who(6) },
creditRule: 'most',
})],
[74, { kind: 'player.chat', steamId: steam(9), name: who(9), channel: 'Global', message: 'wipe is Thursday 19:00, bases stay up till then' }],
[69, { kind: 'npc.boss.died', name: 'Gate Warden', killerName: who(6), killerId: steam(6), damagers: 3 }],
[63, death(6, 1, 'semi_auto_rifle.entity', 41.2, 'K12')],
[58, world('airdrop.looted', { steamId: steam(4), name: who(4), x: 164, z: -1507 })],
[52, { kind: 'player.connected', steamId: steam(7), name: who(7) }],
[47, death(2, 6, 'mp5.entity', 12.6, 'R17', { }) ],
[41, { kind: 'dt.won', steamId: steam(4), name: who(4), invaderCount: 2, invaders: [steam(4), steam(7)], x: 150, z: -800 }],
[36, world('bradley.destroyed', {
where: 'launch_site', x: -1200, z: 300,
credit: {
blow: steam(1), last: steam(1), most: steam(5),
damagers: [{ steamId: steam(5), damage: 630 }, { steamId: steam(1), damage: 385 }],
},
names: { [steam(1)]: who(1), [steam(5)]: who(5) },
creditRule: 'most',
})],
[31, death(1, 7, 'ak47u.entity', 96.3, 'J9')],
[25, { kind: 'gc.ended', steamId: steam(7), name: who(7), x: 200, z: -800 }],
[21, {
kind: 'raid.completed', base: 'raideasy7', difficulty: 'Easy', level: 0, pvp: false,
id: 'raid-demo-1', key: 'demo', ownerId: steam(6), ownerName: who(6), raiderCount: 1,
raiders: [{ steamId: steam(6), name: who(6) }], x: 280, z: -800,
}],
[16, death(3, 5, 'bolt_rifle.entity', 241.7, 'AB4', { })],
[12, { kind: 'player.chat', steamId: steam(1), name: who(1), channel: 'Global', message: 'gg on the heli' }],
[8, world('cargo.docking', { harbour: 'harbor_2', harbourName: 'Harbor', x: 2595, z: -2215 })],
[5, death(4, 2, 'thompson.entity', 18.9, 'Q14')],
[2, { kind: 'player.disconnected', steamId: steam(2), name: who(2), reason: 'Disconnected', sessionSec: 8760 }],
];
// ── The leaderboard ────────────────────────────────────────────────────────────────────
//
// Consistent with the feed in spirit, not to the kill: a wipe is days long and the feed above
// is its last two hours.
const STATS = {
1: { kills: 31, deaths: 12, npc_kills: 58, headshots: 14, best_pvp_m: 212.4, structures: 340, playtime_sec: 61200, heli_kills: 2, apc_kills: 1, crates_hacked: 3, drops_looted: 5 },
3: { kills: 27, deaths: 9, npc_kills: 22, headshots: 19, best_pvp_m: 288.1, structures: 120, playtime_sec: 48900, heli_kills: 1, crates_hacked: 1, drops_looted: 2 },
5: { kills: 19, deaths: 15, npc_kills: 41, headshots: 6, best_pvp_m: 133.0, structures: 510, playtime_sec: 55800, apc_kills: 1, crates_hacked: 2, drops_looted: 7 },
6: { kills: 16, deaths: 11, npc_kills: 30, headshots: 5, best_pvp_m: 97.6, structures: 260, playtime_sec: 40100, raids_completed: 2, drops_looted: 3 },
4: { kills: 12, deaths: 18, npc_kills: 25, headshots: 3, best_pvp_m: 74.2, structures: 180, playtime_sec: 37400, treasures_won: 1, drops_looted: 4 },
2: { kills: 9, deaths: 21, npc_kills: 47, headshots: 2, best_pvp_m: 58.8, structures: 610, playtime_sec: 52300, crates_hacked: 2, drops_looted: 6 },
7: { kills: 6, deaths: 10, npc_kills: 13, headshots: 1, best_pvp_m: 96.3, structures: 90, playtime_sec: 21000, guarded_won: 1, drops_looted: 1 },
9: { kills: 2, deaths: 1, npc_kills: 4, headshots: 0, best_pvp_m: 35.0, structures: 40, playtime_sec: 9800 },
};
const WEAPON_KILLS = {
1: { 'ak47u.entity': 21, 'semi_auto_rifle.entity': 6, 'python.entity': 4 },
3: { 'bolt_rifle.entity': 22, 'lr300.entity': 5 },
5: { 'lr300.entity': 13, 'mp5.entity': 6 },
6: { 'semi_auto_rifle.entity': 10, 'ak47u.entity': 6 },
4: { 'thompson.entity': 8, 'mp5.entity': 4 },
2: { 'mp5.entity': 7, 'thompson.entity': 2 },
7: { 'ak47u.entity': 4, 'python.entity': 2 },
9: { 'lr300.entity': 2 },
};
// ── SQL ────────────────────────────────────────────────────────────────────────────────
const q = (value) =>
value === null || value === undefined ? 'NULL' : `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
const ids = CAST.map((c) => q(steam(c.n))).join(', ');
const out = [];
out.push('-- mockRustDemo.mjs — PLAN.md §16 phase 18 (D81). Generated; do not edit by hand.');
out.push(`SET @server = ${q(SERVER)};`);
out.push(
"SET @wipe = (SELECT wipe_id FROM rust_wipes WHERE server_id = @server ORDER BY last_seen DESC LIMIT 1);",
);
out.push("SELECT IF(@wipe IS NULL, 'NO WIPE YET: connect the site to the server first', CONCAT('wipe ', @wipe)) AS mock;");
out.push('DELETE FROM rust_events WHERE server_id = @server;');
out.push('DELETE FROM rust_player_wipe_stats WHERE server_id = @server;');
out.push('DELETE FROM rust_weapon_kills WHERE server_id = @server;');
out.push(`DELETE FROM rust_account_links WHERE steam_id IN (${ids});`);
out.push(`DELETE FROM rust_players WHERE steam_id IN (${ids});`);
for (const c of CAST) {
out.push(
`INSERT INTO rust_players (steam_id, name, first_seen, last_seen) VALUES (${q(steam(c.n))}, ${q(c.name)}, NOW() - INTERVAL 6 DAY, NOW() - INTERVAL 2 MINUTE);`,
);
}
for (const [minutes, body] of FEED) {
const t = ago(minutes);
const raw = JSON.stringify({ ...body, serverId: SERVER, t, type: 'event', wipeId: '@@WIPE@@' });
const [before, after] = raw.split('"@@WIPE@@"');
out.push(
`INSERT INTO rust_events (server_id, wipe_id, kind, t, steam_id, raw, created_at) VALUES (@server, @wipe, ${q(body.kind)}, ${t}, ${q(body.steamId ?? null)}, CONCAT(${q(before)}, JSON_QUOTE(@wipe), ${q(after)}), FROM_UNIXTIME(${Math.floor(t / 1000)}));`,
);
}
for (const [n, row] of Object.entries(STATS)) {
const cols = Object.keys(row);
out.push(
`INSERT INTO rust_player_wipe_stats (server_id, wipe_id, steam_id, sessions, last_seen, ${cols.join(', ')}) VALUES (@server, @wipe, ${q(steam(Number(n)))}, 6, NOW() - INTERVAL 2 MINUTE, ${cols.map((k) => row[k]).join(', ')});`,
);
}
for (const [n, weapons] of Object.entries(WEAPON_KILLS)) {
for (const [weapon, kills] of Object.entries(weapons)) {
out.push(
`INSERT INTO rust_weapon_kills (server_id, wipe_id, steam_id, weapon, kills) VALUES (@server, @wipe, ${q(steam(Number(n)))}, ${q(weapon)}, ${kills});`,
);
}
}
for (const c of CAST.filter((member) => member.user)) {
out.push(
`INSERT INTO rust_account_links (steam_id, user_id, name, server_id, linked_at) SELECT ${q(steam(c.n))}, id, ${q(c.name)}, @server, NOW() - INTERVAL 5 DAY FROM users WHERE username = ${q(c.user)};`,
);
}
console.log(out.join('\n'));

View File

@@ -38,7 +38,14 @@ import { readFileSync, writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
import { collectedIn, playRows } from '../src/data/collection.mjs';
import {
collectedIn,
deletionRow,
PLAY_DATA_TYPES,
PLAY_PURPOSES,
PLAY_VOCABULARY_READ,
playRows,
} from '../src/data/collection.mjs';
import { legal } from '../src/data/legal.mjs';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
@@ -52,6 +59,33 @@ const cell = (text) => String(text).replace(/\|/g, '\\|').replace(/\s*\n\s*/g, '
const yesNo = (value) => (value ? 'Yes' : 'No');
/**
* The form asks per data type, not per row, and two rows can answer the same type (the
* trusted-device token and the push topic are both "Device or other IDs"). So the
* collected rows are folded into one entry per type, in the console's order: required if
* any row requires it, the union of the purposes, and the rows it came from.
*/
function declaredTypes(rows) {
const entries = [];
for (const [category, types] of Object.entries(PLAY_DATA_TYPES)) {
for (const type of types) {
const from = rows.filter(
(row) => row.play.collected && row.play.types.some((t) => t.category === category && t.type === type)
);
if (!from.length) continue;
const purposes = new Set(from.flatMap((row) => row.play.purposes));
entries.push({
category,
type,
required: from.some((row) => row.play.required),
purposes: PLAY_PURPOSES.filter((p) => purposes.has(p)),
rows: from,
});
}
}
return entries;
}
function render() {
const rows = playRows();
const site = collectedIn('site');
@@ -61,7 +95,9 @@ function render() {
lines.push('<!--');
lines.push(' GENERATED FILE — do not edit.');
lines.push('');
lines.push(` Source: src/data/collection.mjs (scope "app") + src/data/legal.mjs`);
lines.push(
` Source: src/data/collection.mjs (scope "app", and the deletion row) + src/data/legal.mjs`
);
lines.push(` Generator: ${GENERATOR}`);
lines.push('');
lines.push(' Edit the data file and run `npm run play:datasafety`. CI runs the same');
@@ -101,40 +137,87 @@ function render() {
);
lines.push('');
lines.push(
'That is why nearly every answer below is "not collected", and it is also the answer ' +
'most likely to be questioned in a review. The supporting facts are in the table: ' +
'each row names the file it was read out of.'
);
lines.push('');
lines.push(
'Where the console offers free text about security practices, two things are worth ' +
'saying: credentials are held in Android’s encrypted storage (AES-256-GCM via ' +
'Jetpack Security), and push notifications carry **no content** — a relay receives a ' +
'stream name and a reference, and the app fetches the actual message over its own ' +
'authenticated connection.'
'Play still counts what the app sends to that server as **collected**: the data leaves ' +
'the device, and the form does not ask whose server it lands on. So everything the ' +
'app sends is declared collected, not shared, and required, which is the conservative ' +
'answer and the accurate one (org lead, 2026-10-29). What stays true, and what ' +
'`/privacy` says, is that none of it reaches us.'
);
lines.push('');
/* --------------------------------------------------------------------------------- */
lines.push('## Data types');
lines.push('## Data collection and security');
lines.push('');
lines.push('| Category | Data type | Collected by us | Shared by us | Answer |');
lines.push('|---|---|---|---|---|');
for (const row of rows) {
lines.push('- **Does the app collect or share any of the required user data types?** Yes, it collects them (below). It shares none.');
lines.push(
'- **Is all of the user data collected by the app encrypted in transit?** Yes. The ' +
'release build’s network security config sets `cleartextTrafficPermitted="false"` ' +
'for every connection, and the app refuses an `http` deployment address outside ' +
'debug builds. Read from: `app/src/main/res/xml/network_security_config.xml`, ' +
'`core/net/ServerUrl.kt`.'
);
lines.push(
'- **Is any of it processed ephemerally?** No. The deployment keeps what it receives, ' +
'under its operator’s policy, and we cannot promise otherwise on its behalf.'
);
lines.push(
'- **Free text on security practices**, where the console offers it: credentials are ' +
'held in Android’s encrypted storage (AES-256-GCM via Jetpack Security), and push ' +
'notifications carry **no content**: a relay receives a stream name and a reference, ' +
'and the app fetches the actual message over its own authenticated connection.'
);
lines.push('');
/* --------------------------------------------------------------------------------- */
const declared = declaredTypes(rows);
lines.push('## Data types the app collects');
lines.push('');
lines.push('| Category | Data type | Collected | Shared | Required | Purposes | From |');
lines.push('|---|---|---|---|---|---|---|');
for (const entry of declared) {
lines.push(
`| ${cell(row.play.category)} | ${cell(row.play.type)} | ${yesNo(row.play.collected)} ` +
`| ${yesNo(row.play.shared)} | ${cell(row.play.answer)} |`
`| ${cell(entry.category)} | ${cell(entry.type)} | Yes | No | ${yesNo(entry.required)} ` +
`| ${cell(entry.purposes.join('; '))} | ${cell(entry.rows.map((r) => r.title).join('; '))} |`
);
}
lines.push('');
lines.push('## Data types the app does not collect');
lines.push('');
lines.push(
'The form lists every type, so every one is answered. Vocabulary read from Play ' +
`Console Help on ${PLAY_VOCABULARY_READ}; check it against the console’s current list.`
);
lines.push('');
for (const [category, types] of Object.entries(PLAY_DATA_TYPES)) {
const rest = types.filter((type) => !declared.some((e) => e.category === category && e.type === type));
if (!rest.length) continue;
const all = rest.length === types.length;
lines.push(`- **${category}:** ${all ? 'none collected' : `${rest.join(', ')}: not collected`}.`);
}
lines.push('');
const onDevice = rows.filter((row) => !row.play.collected);
lines.push('## Held on the device only');
lines.push('');
lines.push('Not collected, because none of it leaves the phone; listed so nobody declares it by mistake.');
lines.push('');
for (const row of onDevice) lines.push(`- **${cell(row.title)}.** ${cell(row.play.because)}`);
lines.push('');
lines.push('## Each answer, and why it is the truthful one');
lines.push('');
for (const row of rows) {
const types = row.play.types.map((t) => `${t.category} → ${t.type}`).join('; ');
lines.push(`### ${row.title}`);
lines.push('');
lines.push(`**${row.play.category} → ${row.play.type}.** ${cell(row.play.answer)}`);
lines.push(`**${types || 'No console type'}.** ${cell(row.play.answer)}`);
lines.push('');
if (row.play.collected) {
lines.push(`Purposes: ${row.play.purposes.join('; ')}.`);
lines.push('');
}
lines.push(cell(row.body));
lines.push('');
lines.push(`- **Why that answer:** ${cell(row.play.because)}`);
@@ -156,14 +239,49 @@ function render() {
'(D31); the app contains no content directed at children and no age verification.'
);
lines.push(
'- **Account deletion:** the app creates no account with us — an account belongs to ' +
'the deployment the user chose, and is deleted there. The only list we hold is the ' +
'beta signup, which is erased on request; `/privacy` section 4 says how to ask.'
'- **Accounts the app can start:** the sign-in screen links to the deployment’s own ' +
'sign-up page, which opens in the browser, and where a game server offers it the app ' +
'creates a game account on it. Read from: `ui/auth/LoginViewModel.kt`, ' +
'`data/api/PlayerShardApi.kt`.'
);
lines.push(
'- **Data deletion request URL:** the contact address published on `/privacy`, which ' +
'is read from the mounted `brand.json` rather than typed anywhere in the source (D13).'
'- **Can users delete their account? Yes,** in the app (*My account* → *Delete my ' +
'account…*) and on the deployment’s website (*Account* → *Delete my account*). It ' +
'takes the password, and a two-factor code where the account has one, and the account ' +
'is deleted at once. The account belongs to the deployment the user chose, so it is ' +
'deleted there; we hold none. Read from: `ui/auth/DeleteAccountScreen.kt`, ' +
'`data/api/MeApi.kt`.'
);
lines.push(
'- **Delete account URL:** `/delete-account/` on this site (D85). It names the app and ' +
'us, gives the steps in the app and on the website, says what is deleted and what is ' +
'kept and for how long, and tells someone who cannot sign in to ask their community’s ' +
'operator, who can delete any account from the admin panel (D86).'
);
lines.push(
'- **Deleting some data without deleting the account:** the deployment holds it, so ' +
'that is a request to its operator. The one list we hold, the beta signup, is erased ' +
'on request; `/privacy` section 4 says how to ask.'
);
lines.push('');
/* --------------------------------------------------------------------------------- */
const deletion = deletionRow().deletion;
lines.push('## What an account deletion deletes and keeps');
lines.push('');
lines.push(
'The console asks what is deleted and what is kept. These are the same words ' +
'`/delete-account/` renders, from the same row of `src/data/collection.mjs`.'
);
lines.push('');
lines.push('**Deleted at once:**');
lines.push('');
for (const item of deletion.goes) lines.push(`- ${cell(item)}`);
lines.push('');
lines.push('**Kept:**');
lines.push('');
for (const entry of deletion.stays) lines.push(`- ${cell(entry.what)} *${cell(entry.keep)}*`);
lines.push(`- ${cell(deletion.staff)}`);
lines.push('');
lines.push('## What the website collects, for the same reviewer');

View File

@@ -4,17 +4,26 @@
*
* node scripts/seedDemo.mjs → seed (idempotent; safe to re-run)
* node scripts/seedDemo.mjs --dry-run → say what it would do, write nothing
* node scripts/seedDemo.mjs --game rust → the Rust demo instead (PLAN.md §16 phase 18)
*
* Environment (all optional; the defaults are this machine's review stack):
*
* RG_BASE http://localhost:3000 the website the seed drives
* RG_ADMIN_USER demoadmin an existing admin, created by website's own
* RG_ADMIN_USER demoadmin (rust: admin) an existing admin, created by website's own
* RG_ADMIN_PASS DemoReview!2026 `npm run seed` — see PLAN.md §13 phase 9
* RG_DEMO_PASS DemoReview!2026 the password every seeded cast member gets
* UOLINK_BASE http://127.0.0.1:8080 sidecar REST, written to Admin → Shard
* UOLINK_WS ws://127.0.0.1:8080/ws sidecar WebSocket
* UOLINK_TOKEN (unset) sidecar auth token; skipped when absent
* UOLINK_PROTOCOL (platform.json) wire protocol to pin — see the note below
* RG_RUST_SERVERS (unset) rust only: a JSON file outside the repository,
* [{ id, name, sidecarBaseUrl, sidecarToken }]
*
* One deployment runs one game module (the core refuses a second at boot), so the Rust demo
* is a second deployment with its own database, and `--game rust` seeds that one. Its cast
* is named for its roles — admin, moderator, player — and so is every stand-in on the game
* server behind it (D80): a name in a screenshot should say what the account is, not
* invent a person.
*
* ---------------------------------------------------------------------------------------
* WHY THE SEED DRIVES THE API AND NEVER THE DATABASE
@@ -47,9 +56,17 @@ import { readFileSync } from 'node:fs';
import platform from '../src/data/platform.json' with { type: 'json' };
const gameAt = process.argv.indexOf('--game');
const GAME = gameAt === -1 ? 'uo' : process.argv[gameAt + 1];
if (!['uo', 'rust'].includes(GAME)) {
console.error(`--game is uo or rust, not "${GAME}"`);
process.exit(1);
}
const BASE = (process.env.RG_BASE || 'http://localhost:3000').replace(/\/+$/, '');
const API = `${BASE}/api/v1`;
const ADMIN_USER = process.env.RG_ADMIN_USER || 'demoadmin';
const ADMIN_USER = process.env.RG_ADMIN_USER || (GAME === 'rust' ? 'admin' : 'demoadmin');
const ADMIN_PASS = process.env.RG_ADMIN_PASS || 'DemoReview!2026';
const DEMO_PASS = process.env.RG_DEMO_PASS || 'DemoReview!2026';
const UOLINK_BASE = process.env.UOLINK_BASE || 'http://127.0.0.1:8080';
@@ -109,6 +126,85 @@ const USERS = [
{ username: 'mirenavox', role: 'player' },
];
// ── The Rust demo (PLAN.md §16 phase 18) ───────────────────────────────────────────────
//
// The same neutral identity (D43) over a Rust server. The cast is two accounts besides the
// admin, each named for its role (D80). Teams, the feed, the leaderboard and the map are the
// game's, as they are for UO; what the site owns here is the server row, the NPC profiles
// and a permission group, so those are seeded.
const RUST_SETTINGS = {
...SETTINGS,
status_message: 'Live — the demo server is up.',
homepage_teaser:
'A public demonstration of Runic Gateway: a self-hosted community site wired to a ' +
'live Rust server. Everything on this site is real data from the server behind it.',
};
const RUST_USERS = [
{ username: 'moderator', role: 'moderator' },
{ username: 'player', role: 'player' },
];
// Two RunicNPC profiles: a guard who fights, and a passive trader who talks. Their kit is
// one the rig's Kits holds; a profile naming a kit Kits does not have is refused by RunicNPC
// and shows as refused on the screen, which is not the screen being shown. The guard's name
// sorts first, so the editor the NPC screenshot opens (its first Edit) is the fuller one.
const NPC_KIT = process.env.RG_NPC_KIT || 'rnpc_campguard';
const NPC_PROFILES = [
{
name: 'guard',
allServers: true,
body: {
names: ['Camp Guard', 'Gate Guard'],
kits: [NPC_KIT],
prefab: 'scientistnpc_roam',
role: 'guard',
movement: { mode: 'wander', radius: 12 },
health: 300,
faction: 'wardens',
alertRadius: 30,
},
},
{
name: 'trader',
allServers: true,
body: {
names: ['Quartermaster'],
kits: [NPC_KIT],
prefab: 'scientistnpc_roam',
role: 'passive',
movement: { mode: 'stand', radius: 0 },
hurtByPlayers: false,
use: { mode: 'chat', lines: ['Back again, {player}?', 'Supplies are short this wipe.'], title: '', text: '' },
},
},
];
// One group the site authored, so the permissions screen shows the site doing something
// beside what the server already had. Its permissions are ones the rig's plugins register,
// and its member is the `player` account, through its linked Steam id.
const PERM_GROUP = {
name: 'vip',
title: 'VIP',
rank: 10,
permissions: ['backpacks.use', 'autodoors.use'],
members: ['player'],
};
// Who sees who is online, and the map's player layer. Both default to staff, which is right
// for a real community and wrong for a demo whose public pages exist to be looked at: with
// them at staff, the public feed leaves out every death and the map shows no one. The only
// players on the demo server are the stand-ins phase 18 staged, named by role (D80), so
// opening them to the public shows nobody's real name.
const RUST_VISIBILITY = { fleet: 'public', map: { fleet: { players: 'public' } } };
// A weekly wipe, so the server list has a next wipe to show: Thursday evening, the usual
// Rust community habit.
const RUST_WIPE = { wipeRule: 'weekly', wipeDay: 4, wipeTime: '19:00', wipeTz: 'America/Chicago' };
const siteSettings = GAME === 'rust' ? RUST_SETTINGS : SETTINGS;
const cast = GAME === 'rust' ? RUST_USERS : USERS;
// ── News, five-on-friday, the newsletter ───────────────────────────────────────────────
//
// Written as a small community's real output rather than lorem: a patch note, an event, a
@@ -312,12 +408,12 @@ async function login() {
async function settings() {
console.log('\nsite settings (D43 — the neutral demo identity)');
if (DRY) {
for (const [k, v] of Object.entries(SETTINGS)) say('~', `${k} = ${v}`);
for (const [k, v] of Object.entries(siteSettings)) say('~', `${k} = ${v}`);
return;
}
const res = await call('PUT', '/admin/settings', SETTINGS);
const res = await call('PUT', '/admin/settings', siteSettings);
if (!res.ok) return fail('settings', res);
for (const [k, v] of Object.entries(SETTINGS)) say('+', `${k} = ${String(v).slice(0, 60)}`);
for (const [k, v] of Object.entries(siteSettings)) say('+', `${k} = ${String(v).slice(0, 60)}`);
}
async function uoLink() {
@@ -358,7 +454,7 @@ async function users() {
if (!list.ok) return fail('list users', list);
const rows = Array.isArray(list.data) ? list.data : (list.data?.users ?? []);
const have = new Set(rows.map((u) => u.username));
for (const user of USERS) {
for (const user of cast) {
if (have.has(user.username)) {
say('=', `${user.username} (${user.role})`);
continue;
@@ -447,23 +543,175 @@ async function wiki() {
}
}
// ── The Rust steps ─────────────────────────────────────────────────────────────────────
/** The servers file, read once. The tokens in it are sent to the site and never printed. */
function rustServerList() {
const file = process.env.RG_RUST_SERVERS;
if (!file) return [];
return JSON.parse(readFileSync(file, 'utf8'));
}
async function rustServers() {
console.log('\nRust servers (Admin → Rust → Servers)');
const wanted = rustServerList();
if (wanted.length === 0) {
say('~', 'RG_RUST_SERVERS unset — leaving the server list alone');
return;
}
const now = await call('GET', '/admin/rust/servers');
if (now.status === 404) {
say('~', 'no /admin/rust route — the rust module is not installed');
return;
}
if (!now.ok) return fail('list servers', now);
for (const server of wanted) {
const have = (now.data?.servers ?? []).find((row) => row.id === server.id);
if (
have &&
have.sidecarBaseUrl === server.sidecarBaseUrl &&
have.enabled &&
have.schedule?.rule === RUST_WIPE.wipeRule
) {
say('=', `${server.id} at ${server.sidecarBaseUrl}`);
continue;
}
if (DRY) {
say('~', `${server.id} at ${server.sidecarBaseUrl}`);
continue;
}
const res = await call('PUT', `/admin/rust/servers/${encodeURIComponent(server.id)}`, {
name: server.name,
sidecarBaseUrl: server.sidecarBaseUrl,
// Omitted on an existing row, which is how the API says "keep the token" — so a re-run
// never needs the token file to hold a token it already sent.
sidecarToken: have ? undefined : server.sidecarToken,
enabled: true,
...RUST_WIPE,
});
if (!res.ok) {
fail(`save server ${server.id}`, res);
continue;
}
say('+', `${server.id} "${server.name}" at ${server.sidecarBaseUrl}`);
}
}
async function rustVisibility() {
console.log('\nvisibility (Admin → Rust → Visibility)');
const now = await call('GET', '/admin/rust/visibility');
if (!now.ok) return fail('read visibility', now);
if (now.data?.presence?.fleet === 'public' && now.data?.map?.fleet?.players === 'public') {
say('=', 'who is online and the map’s players are public');
return;
}
if (DRY) return say('~', 'would make who is online and the map’s players public');
const res = await call('PUT', '/admin/rust/visibility', RUST_VISIBILITY);
if (!res.ok) return fail('visibility', res);
say('+', 'who is online and the map’s players are public');
}
async function npcProfiles() {
console.log('\nRunicNPC profiles (Admin → Rust → NPCs)');
const now = await call('GET', '/admin/rust/npcs');
if (!now.ok) return fail('list NPC profiles', now);
const live = (now.data?.profiles ?? []).filter((profile) => !profile.replaced);
for (const profile of NPC_PROFILES) {
const have = live.find((row) => row.name === profile.name);
if (DRY) {
say('~', `profile ${profile.name}`);
continue;
}
// An existing profile is saved again rather than skipped, so a change to its body here
// reaches the demo on the next run. RunicNPC answers the push the same either way.
const res = have
? await call('PUT', `/admin/rust/npcs/profiles/${have.id}`, profile)
: await call('POST', '/admin/rust/npcs/profiles', profile);
if (!res.ok) {
fail(`${have ? 'save' : 'create'} profile ${profile.name}`, res);
continue;
}
say(have ? '=' : '+', `profile ${profile.name}${have ? ' (saved again)' : ''}`);
}
}
async function permGroup() {
console.log('\npermission group (Admin → Rust → Permissions)');
for (const server of rustServerList()) {
const base = `/admin/rust/permissions/servers/${encodeURIComponent(server.id)}`;
const now = await call('GET', base);
if (!now.ok) {
fail(`read permissions on ${server.id}`, now);
continue;
}
if (DRY) {
say('~', `${server.id}: group ${PERM_GROUP.name}`);
continue;
}
let id = (now.data?.groups ?? []).find((group) => group.name === PERM_GROUP.name)?.id;
if (id) {
say('=', `${server.id}: group ${PERM_GROUP.name}`);
} else {
const made = await call('POST', `${base}/groups`, {
name: PERM_GROUP.name,
title: PERM_GROUP.title,
rank: PERM_GROUP.rank,
});
if (!made.ok) {
fail(`create group ${PERM_GROUP.name} on ${server.id}`, made);
continue;
}
id = made.data.id;
say('+', `${server.id}: group ${PERM_GROUP.name}`);
}
// The permission set is replaced whole, so saving it again is the update.
const perms = await call('PUT', `/admin/rust/permissions/groups/${id}/permissions`, {
permissions: PERM_GROUP.permissions,
});
if (!perms.ok) fail(`grant ${PERM_GROUP.name}'s permissions`, perms);
else say('=', ` permissions ${PERM_GROUP.permissions.join(', ')}`);
for (const username of PERM_GROUP.members) {
const added = await call('POST', `/admin/rust/permissions/groups/${id}/members`, { username });
if (added.ok) say('=', ` member ${username}`);
else if (added.status === 409) say('=', ` member ${username} (already)`);
else fail(`add ${username} to ${PERM_GROUP.name}`, added);
}
}
}
// ── main ───────────────────────────────────────────────────────────────────────────────
console.log(DRY ? '\nseedDemo — DRY RUN, nothing will be written' : '\nseedDemo');
console.log(
`${DRY ? '\nseedDemo — DRY RUN, nothing will be written' : '\nseedDemo'} (${GAME})`,
);
await login();
await settings();
await uoLink();
await users();
await posts();
await wiki();
// The news and the wiki are written in one game's voice (a patch note about house decay, a
// champion spawn), so they belong to the UO demo. The Rust captures show none of them.
if (GAME === 'rust') {
await rustServers();
await rustVisibility();
await npcProfiles();
await permGroup();
} else {
await uoLink();
await posts();
await wiki();
}
console.log(
`\n${DRY ? 'would create' : 'created'} ${created}, already present ${existed}` +
(process.exitCode ? ' — with failures above' : ''),
);
console.log(
'\nWhat this does NOT seed, on purpose: teams, the marketplace, houses, points boards\n' +
'and the atlas. Those arrive from the shard over the bridge (D42) — start the sidecar\n' +
'and the shard, and they populate themselves.\n',
GAME === 'rust'
? '\nWhat this does NOT seed, on purpose: the feed, the leaderboard, who is online, clans\n' +
'and the map. Those arrive from the server over the bridge — start the server, and\n' +
'they populate themselves. PLAN.md §16 phase 18 says how its players were staged.\n'
: '\nWhat this does NOT seed, on purpose: teams, the marketplace, houses, points boards\n' +
'and the atlas. Those arrive from the shard over the bridge (D42) — start the sidecar\n' +
'and the shard, and they populate themselves.\n',
);

View File

@@ -13,6 +13,8 @@ import platform from '../data/platform.json';
* in the legal bar at the foot rather than in the columns: a legal link is not a thing a
* reader browses to alongside Features, it is a thing they go looking for, and the line
* that already carries the licence and the copyright is where people look.
* `/delete-account/` joined them for the same reason (D85): it is the address Google Play
* is given, and a player looking for it looks where the privacy link is.
*/
// `/beta` renders per request, so the footer it gets must read the mount rather than the
// value baked at build time. See `renderBrand` in src/lib/brand.mjs (phase 11).
@@ -59,6 +61,7 @@ const isExternal = (href: string) => href.startsWith('http');
<span class="site-footer__links">
<a href="/privacy/">Privacy</a>
<a href="/terms/">Terms</a>
<a href="/delete-account/">Delete account</a>
</span>
</p>
<p class="site-footer__meta">

View File

@@ -0,0 +1,37 @@
---
import platform from '../data/platform.json';
/**
* A worked example that belongs to one game, quoted on a core page (PLAN.md §16, D68).
*
* D63 keeps a game's vocabulary inside that game's section, but a core page sometimes needs a
* real example rather than an invented one: a module manifest, an event dimension, the flag
* that tells the installer which game it is setting up. §1 prefers the real thing, because an
* invented example is checked by nothing and goes stale without anybody noticing.
*
* So the example keeps its game's words and says whose they are. This prints the game's name
* above the block — the same bargain D67 strikes for a screenshot: a game's words are honest
* on a core page when the game is named right beside them. `scripts/checkTerms.mjs` reads the
* `game` attribute and allows that game's words, and only that game's, between the tags.
*
* The name comes from `platform.json` rather than from the caller, so the label cannot say
* one game while the attribute that the check reads says another.
*/
interface Props {
/** A key of `platform.json`'s `games`: `uo` or `rust`. */
game: keyof typeof platform.games;
}
const { game } = Astro.props;
const entry = platform.games[game];
if (!entry) {
throw new Error(
`GameExample: unknown game "${game}". Use a key of platform.json's games: ${Object.keys(platform.games).join(', ')}.`,
);
}
---
<figure class="game-example" data-game={game}>
<figcaption class="game-example__label">{entry.name}</figcaption>
<div class="game-example__body"><slot /></div>
</figure>

View File

@@ -0,0 +1,112 @@
---
import type { Capability } from '../data/capabilities.mjs';
/**
* A game's own feature list, with the argument for each — PLAN.md §16, phase 17.
*
* Rendered only by a game's page under `/modules/` (`GAME_ROUTES` in `checkTerms.mjs`),
* which is what lets the items be written in the game's own words. It is `/features/`'s
* card treatment (D20: the label and the detail, never the label alone), so a reader who has
* seen that page reads this one the same way.
*
* A feature with a `demoPath` gets the per-capability demo link of D25. The markup is the
* exact contract `scripts/checkBrand.mjs` enforces and `applyBrand.mjs` rewrites at boot —
* see the note in `/features/` before touching it. A stock build hides every one.
*
* `game` is the module's id, written as `data-demo-game` straight after the path: these
* links are into that module's pages, so they show only on a demo whose mounted
* `demoGames` names it (D83).
*/
interface Props {
title: string;
lede?: string;
game: string;
items: Capability[];
}
const { title, lede, game, items } = Astro.props;
---
<section class="page section feats">
<h2>{title}</h2>
{lede && <p class="prose feats__lede">{lede}</p>}
<ul class="feats__items">
{
items.map((item) => (
<li class="panel feats__item">
<h3>{item.label}</h3>
<p class="feats__detail">{item.detail}</p>
{item.demoPath && (
<a
class="demo-link"
href="" data-demo-url="" data-demo-path={item.demoPath} data-demo-game={game}
rel="noopener noreferrer"
>
See it running
</a>
)}
</li>
))
}
</ul>
</section>
<style>
.feats h2 {
margin: 0;
font-size: clamp(1.5rem, 3vw, 1.95rem);
}
.feats__lede {
margin: 0.85rem 0 0;
color: var(--muted);
}
.feats__items {
display: grid;
gap: 1rem;
margin: 1.75rem 0 0;
padding: 0;
list-style: none;
grid-template-columns: repeat(auto-fit, minmax(min(100%, 21rem), 1fr));
}
.feats__item {
display: flex;
flex-direction: column;
}
.feats__item h3 {
margin: 0 0 0.6rem;
color: var(--gold);
font-size: 1.04rem;
}
.feats__detail {
flex: 1;
margin: 0;
color: var(--muted);
font-size: 0.94rem;
}
/* As on /features/: a link rather than a button, and the flex item itself, so the
global rule that hides an empty demo link takes its margin with it. */
.demo-link {
display: inline-flex;
align-items: center;
gap: 0.35rem;
margin-top: 1rem;
color: var(--portal);
font-size: 0.88rem;
text-decoration-color: color-mix(in srgb, var(--portal) 40%, transparent);
}
.demo-link:hover {
color: var(--portal-bright);
}
.demo-link::after {
content: '\2197';
}
</style>

View File

@@ -28,6 +28,8 @@ const brand = renderBrand(Astro);
const links = [
{ href: '/features/', label: 'Features' },
{ href: '/docs/', label: 'Docs' },
// D78 (phase 17): the standalone RunicNPC page, for a Rust server owner who runs no site.
{ href: '/runicnpc/', label: 'RunicNPC' },
{ href: '/app/', label: 'App' },
{ href: '/community/', label: 'Community' },
];

View File

@@ -1,5 +1,6 @@
---
import { screenById, WEB, PHONE } from '../data/screens.mjs';
import platform from '../data/platform.json';
/**
* One screenshot, as a figure with its caption. PLAN.md §13 phase 9, D4 / D44.
@@ -44,9 +45,16 @@ const src = `/screens/${shot.id}.webp`;
// taken at one geometry (see screens.mjs), and `checkScreens.mjs` asserts the files really
// are that size, so these attributes cannot drift from the pixels.
const { width, height } = shot.family === 'web' ? WEB : PHONE;
// D67: a game's screen says whose it is. The name comes from `platform.json`, as
// GameExample's does, so the label cannot disagree with the tag the check reads.
const game = shot.game ? platform.games[shot.game] : null;
if (shot.game && !game) {
throw new Error(`Screenshot "${id}" is tagged game "${shot.game}", which platform.json does not have`);
}
---
<figure class="shot">
<figure class="shot" data-game={shot.game}>
<img
src={src}
alt={shot.alt}
@@ -55,7 +63,14 @@ const { width, height } = shot.family === 'web' ? WEB : PHONE;
loading="lazy"
decoding="async"
/>
{!bare && <figcaption>{shot.caption}</figcaption>}
{
(game || !bare) && (
<figcaption>
{game && <span class="shot__game">{game.name}</span>}
{!bare && shot.caption}
</figcaption>
)
}
</figure>
<style>
@@ -78,4 +93,18 @@ const { width, height } = shot.family === 'web' ? WEB : PHONE;
font-size: 0.9rem;
line-height: 1.5;
}
/* The game's name, ahead of the caption (D67). Styled here rather than with the global
chip, because the docs pages render this component without the marketing stylesheet. */
.shot__game {
display: inline-block;
margin-right: 0.5rem;
padding: 0.05rem 0.55rem;
border: 1px solid var(--line);
border-radius: var(--radius-pill);
color: var(--muted);
font-size: 0.76rem;
letter-spacing: 0.04em;
white-space: nowrap;
}
</style>

View File

@@ -0,0 +1,21 @@
---
import { Code } from '@astrojs/starlight/components';
import { runicnpcCalls } from '../data/runicnpc.mjs';
/**
* One RunicNPC call's signature, printed from `src/data/runicnpc.mjs` (PLAN.md §16, D62).
*
* The API page writes each call's prose by hand and prints its signature through this, so the
* signature a reader copies is the one `scripts/checkReference.mjs` holds against
* `docs` `main:runicnpc/API.md`. The check also requires exactly one of these per call.
*/
interface Props {
call: keyof typeof runicnpcCalls;
}
const { call } = Astro.props;
const sig = runicnpcCalls[call];
if (!sig) throw new Error(`Signature: "${call}" is not in runicnpcCalls (src/data/runicnpc.mjs).`);
---
<Code lang="csharp" code={`${sig.returns} ${call}(${sig.params})`} />

View File

@@ -0,0 +1,63 @@
---
import { games } from '../data/games/index.mjs';
/**
* "Supported games: Ultima Online · Rust" — PLAN.md §16, D63.
*
* The one place a core page names the games, and the way it hands a reader on to them. Core
* pages describe what a game module adds in core's words (D75); this strip is the link to
* the page where each game says it in its own. The names come from `platform.json` through
* `games/index.mjs`, so a third game appears here the day it is added there.
*/
interface Props {
/** Extra class for the caller's spacing. */
class?: string;
}
const { class: className } = Astro.props;
---
<p class:list={['games', className]}>
<span class="games__label">Supported games</span>
{
games.map((game, index) => (
<>
{index > 0 && <span class="games__sep" aria-hidden="true">·</span>}
<a class="games__link" href={game.href}>
{game.name}
</a>
</>
))
}
</p>
<style>
.games {
display: flex;
flex-wrap: wrap;
align-items: baseline;
gap: 0.35rem 0.65rem;
margin: 0;
font-size: 0.95rem;
}
.games__label {
color: var(--dim);
font-size: 0.78rem;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.games__label::after {
content: ':';
}
.games__sep {
color: var(--dim);
}
.games__link {
color: var(--gold);
font-weight: 600;
}
</style>

View File

@@ -0,0 +1,35 @@
---
/**
* A short description from a data file, rendered inline (PLAN.md §16, phase 16).
*
* Reference data in `src/data/` is plain strings, because a check reads the same file. Three
* inline marks are understood, and nothing else: `code`, **bold**, and [a link](/path/). The
* text is never parsed as HTML, so a description cannot inject markup.
*/
interface Props {
text: string;
}
const { text } = Astro.props;
type Token = { kind: 'text' | 'code' | 'strong'; value: string } | { kind: 'link'; value: string; href: string };
const tokens: Token[] = [];
const pattern = /`([^`]+)`|\*\*([^*]+)\*\*|\[([^\]]+)\]\(([^)\s]+)\)/g;
let last = 0;
for (const m of String(text ?? '').matchAll(pattern)) {
if (m.index > last) tokens.push({ kind: 'text', value: text.slice(last, m.index) });
if (m[1] !== undefined) tokens.push({ kind: 'code', value: m[1] });
else if (m[2] !== undefined) tokens.push({ kind: 'strong', value: m[2] });
else tokens.push({ kind: 'link', value: m[3], href: m[4] });
last = m.index + m[0].length;
}
if (last < text.length) tokens.push({ kind: 'text', value: text.slice(last) });
---
{tokens.map((t) =>
t.kind === 'code' ? <code>{t.value}</code>
: t.kind === 'strong' ? <strong>{t.value}</strong>
: t.kind === 'link' ? <a href={t.href}>{t.value}</a>
: t.value
)}

View File

@@ -1,5 +1,6 @@
---
import { screensOf, PHONE } from '../../data/screens.mjs';
import platform from '../../data/platform.json';
/**
* The app's screenshot strip. Reserved in phase 5 (D26), filled in phase 9.
@@ -38,14 +39,15 @@ const shots = screensOf('phone');
<section class="page section shots">
<h2>What it looks like</h2>
<p class="prose shots__lede">
Captured against a real deployment with real content, not mocked up. The app takes its
colours, type and navigation from the site it is connected to, so these show one
community's app rather than a neutral one.
Captured from the app against two demo deployments: one with a real Ultima Online
server behind it, and one with a real Rust server whose players are a demo cast. The
app takes its colours, type and navigation from the site it is connected to, so these
show one community's app rather than a neutral one.
</p>
<ul class="shots__grid">
{shots.map((shot) => (
<li class="shots__item">
<li class="shots__item" data-game={shot.game}>
<img
src={`/screens/${shot.id}.webp`}
alt={shot.alt}
@@ -54,7 +56,10 @@ const shots = screensOf('phone');
loading="lazy"
decoding="async"
/>
<p class="shots__caption">{shot.caption}</p>
<p class="shots__caption">
{shot.game && <span class="shots__game">{platform.games[shot.game].name}</span>}
{shot.caption}
</p>
</li>
))}
</ul>
@@ -91,6 +96,19 @@ const shots = screensOf('phone');
box-shadow: var(--shadow-card);
}
/* The game's name on a game's screen (D67), as Screenshot.astro prints it. */
.shots__game {
display: inline-block;
margin-right: 0.5rem;
padding: 0.05rem 0.55rem;
border: 1px solid var(--line);
border-radius: var(--radius-pill);
color: var(--muted);
font-size: 0.74rem;
letter-spacing: 0.04em;
white-space: nowrap;
}
.shots__caption {
margin: 0.85rem 0 0;
color: var(--dim);

View File

@@ -26,8 +26,8 @@ import platform from '../../data/platform.json';
<p class="eyebrow">Where the game stops</p>
<h2>A seam, with a version on it</h2>
<p class="prose">
The core site does not know what a shard is, what a guild is, or that Ultima Online
exists. Everything that does lives in an installable module on the other side of a
The core site does not know what game it serves, what that game calls a group of
players, or that Ultima Online and Rust exist. Everything that does lives in an installable module on the other side of a
declared interface — which is what makes "put your game on it" a shape rather than a
slogan.
</p>
@@ -123,8 +123,8 @@ import platform from '../../data/platform.json';
<p>
Core owns the Teams primitive — the roster, the forum, the notifications, the voice
channel — and does not own the <em>word</em>. A Team cannot be created in core at
all; it arrives from the module, which is why the UO module calls them guilds and
builds those pages itself. That is the pattern the whole interface is built on: core
all; it arrives from the module, which is why each module calls them by its own
game’s word and builds those pages itself. That is the pattern the whole interface is built on: core
supplies the machinery, the module supplies the meaning.
</p>
</section>

View File

@@ -9,7 +9,10 @@
* doing capacity planning, and "how many machines is this" is the first question they have.
*
* Drawn generically for the same reason the homepage's diagram is (D17) — "your game host",
* not "your ServUO box" — with the prose beside it naming the real components. The boundary
* not a particular game's server — with the prose beside it linking to each game's page,
* which names its real components (D75). Until phase 17 the caption named one game's and
* said two machines was also the maximum, which stopped being true when Rust shipped: one
* sidecar serves one server, so six servers means six sidecars. The boundary
* is the one drawn argument: everything above it is reachable because you published it, and
* everything below it is not reachable at all.
*
@@ -73,8 +76,10 @@
</svg>
<p class="diagram__caption">
Today the game server is a ServUO shard and the sidecar is uo-link. Two machines is
the minimum and also the maximum — nothing here scales by adding a third.
The sidecar and the bridge plugin are each game’s own — see
<a href="/modules/uo/">Ultima Online</a> and <a href="/modules/rust/">Rust</a>. Two
machines is the minimum. A community running several game servers runs a sidecar
beside each one, on whichever host that server already lives on.
</p>
</div>
@@ -92,10 +97,10 @@
<section>
<h3>The game host</h3>
<p>
The machine your game server is already on. One installer binary puts the plugin
into the server's tree, installs the sidecar beside it and registers the service —
then prints four values. It never contacts your website; you paste those four
values into the admin panel yourself, and that is the moment the two halves meet.
The machine your game server is already on. One installer binary puts the bridge
plugin into the server's tree, installs the sidecar beside it and registers the
service — then prints what the site needs. It never contacts your website; you enter
those values in the admin panel yourself, and that is the moment the two halves meet.
</p>
</section>

View File

@@ -1,6 +1,7 @@
---
import platform from '../../data/platform.json';
import { capabilityGroups, assertCapabilityCoverage } from '../../data/capabilities.mjs';
import { capabilityGroups } from '../../data/capabilities.mjs';
import { games, assertGameCoverage } from '../../data/games/index.mjs';
import SupportedGames from '../SupportedGames.astro';
/**
* The grouped capabilities (PLAN.md §10). All five groups, named only — the argument for
@@ -8,8 +9,10 @@ import { capabilityGroups, assertCapabilityCoverage } from '../../data/capabilit
* copy to keep true.
*
* The call below is the point of the exercise: it throws, and therefore fails the build, if
* the "Game intelligence" list and the module's own declared capabilities have drifted
* apart. `checkFacts.mjs` already keeps `platform.json` honest against the module manifest;
* either game's own feature list (`src/data/games/`) and its module's declared capabilities
* have drifted apart. The homepage names neither list — its module-supplied group is the
* neutral one, in core's words (D75) — but it is the page a reader meets first, so it is
* the page that should refuse to build when a game page is out of date. `checkFacts.mjs` already keeps `platform.json` honest against the module manifest;
* this makes the page honest against `platform.json`, which is the half that was missing.
*
* The "not built" line at the bottom is not a disclaimer bolted on — §2's absent-features
@@ -17,17 +20,18 @@ import { capabilityGroups, assertCapabilityCoverage } from '../../data/capabilit
* what exists while quietly omitting the well-known things that do not is the exact failure
* §1 is written to prevent.
*/
assertCapabilityCoverage(platform.games.uo.module.capabilities);
for (const game of games) assertGameCoverage(game.key);
---
<section class="page section caps">
<p class="eyebrow">What it does</p>
<h2>A community site, and a window into the game</h2>
<p class="prose caps__lede">
The core is game-agnostic: it does not know what a shard is. Everything that does arrives
as an installable <a href="/modules/">module</a>, which is why the same platform can carry
a different game without a fork.
The core is game-agnostic: it does not know what game you run. Everything that does
arrives as an installable <a href="/modules/">module</a>, which is why the same platform
carries two games without a fork.
</p>
<SupportedGames class="caps__games" />
<div class="caps__grid">
{
@@ -69,6 +73,10 @@ assertCapabilityCoverage(platform.games.uo.module.capabilities);
color: var(--muted);
}
.caps__games {
margin-top: 1.25rem;
}
.caps__grid {
display: grid;
gap: 1rem;

View File

@@ -4,7 +4,7 @@ import { brand } from '../../lib/brand.mjs';
/**
* The get-started CTA (PLAN.md §10, the `/` row), built around the trap in §10's
* "installation path": a "Runic Gateway install" is two independent installs. The installer
* binary sets up the shard side only and never contacts the website; the website is a
* binary sets up the game side only and never contacts the website; the website is a
* separate Docker deployment.
*
* That belongs on the homepage rather than being saved for the docs. It is the single
@@ -13,7 +13,9 @@ import { brand } from '../../lib/brand.mjs';
* project. Saying it here is what makes the docs a confirmation rather than a surprise.
*
* The two halves are ordered site-first because that is the order they must be done in: the
* shard side ends by pasting four values into the site's admin panel, which has to exist.
* game side ends by entering what the installer printed into the site's admin panel, which
* has to exist. Which screen that is belongs to the game module, so this says "the game
* module's screen" rather than naming one game's menu (D63).
*
* Both "read the docs" links point at `/docs/` rather than at a page inside the journey.
* Phases 7 and 8 write those pages and own their slugs; guessing one now would put a URL in
@@ -44,9 +46,10 @@ import { brand } from '../../lib/brand.mjs';
<div class="start__half">
<h3><span class="start__num">2</span> The game side</h3>
<p>
One binary, run on the machine the game server already lives on. It syncs the plugin,
installs the sidecar as a service, and prints four values. You paste those into
Admin → Shard, and the two halves find each other.
One binary, run on the machine the game server already lives on — or, for Rust, a
Pterodactyl egg. It puts the bridge plugin in place, installs the sidecar, and prints
what the site needs. You enter that on the game module’s screen in the admin panel,
and the two halves find each other.
</p>
</div>
</div>

View File

@@ -2,19 +2,27 @@
import Screenshot from '../Screenshot.astro';
/**
* The homepage's one screenshot. PLAN.md §13 phase 9, D4 / D44.
* The homepage's screenshots, one per game. PLAN.md §13 phase 9, D4 / D44; §16 phase 18.
*
* -----------------------------------------------------------------------------------------
* WHY ONE, AND WHY THIS ONE
* WHY ONE PER GAME, AND WHY THESE
* -----------------------------------------------------------------------------------------
* `DataPath` above it draws the claim — a private game server, a sidecar, a public site —
* and a diagram of a data path is a promise that the data arrives. This is the page where
* it arrives, captured from a deployment wired to a running shard, so the section directly
* under the diagram is the diagram's evidence.
* it arrives, captured from a deployment wired to a running game server, so the section
* directly under the diagram is the diagram's evidence.
*
* It is one game's screen, and says so (D76, taken in phase 17 under D67): the screenshot is
* tagged `uo` in `screens.mjs`, so it prints "Ultima Online" beside it and may keep that
* game's words in its alt and caption. A core screen was the alternative and was declined:
* the claim here is live game state on a public page, which no core screen shows. Phase 18
* added a Rust capture beside it, labelled the same way: the live map, because every pixel
* of it is the running server's — the Rust demo's players are a demo cast (D81), and the
* map shows none of them.
*
* A gallery here would compete with `Capabilities` further down, which is the part of the
* homepage that enumerates. So: one figure, the signature screen, and the rest of the set
* on `/features/` where each one sits beside the claim it supports.
* homepage that enumerates. So: one figure per game, its signature screen, and the rest of
* the set on each game's page under `/modules/`, where each sits beside the claim it supports.
*/
---
@@ -22,12 +30,16 @@ import Screenshot from '../Screenshot.astro';
<p class="eyebrow">What it looks like</p>
<h2>The other end of that diagram</h2>
<p class="prose looks__lede">
A demo deployment with a real shard behind it. The gold supply, the state of the link and
the player online in Britain are all read from the game server over the bridge. None of it
is typed in, and none of it is a mock-up.
Two demo deployments, each with a real game server behind it. On the first, the gold
supply, the state of the link and the player online are all read from an Ultima Online
server over the bridge. On the second, the map is the running Rust server's own: its
island, its monuments, and the events on it as they happen.
</p>
<Screenshot id="shard-status" />
<div class="looks__pair">
<Screenshot id="shard-status" />
<Screenshot id="rust-map" />
</div>
</section>
<style>
@@ -41,4 +53,11 @@ import Screenshot from '../Screenshot.astro';
max-width: 46rem;
color: var(--muted);
}
/* Side by side where there is room for two screenshots to stay readable, stacked below. */
.looks__pair {
display: grid;
gap: 0 1.5rem;
grid-template-columns: repeat(auto-fit, minmax(min(100%, 30rem), 1fr));
}
</style>

22
src/config/redirects.mjs Normal file
View File

@@ -0,0 +1,22 @@
/**
* Docs pages that moved, and where they went — PLAN.md §16, D60.
*
* Every page that moves keeps its old URL working, because the old URL is in somebody's
* bookmarks, in an installer's output and in search results. With the Node adapter these are
* not files in `dist/client`: the server answers each one with a real `301`.
*
* Its own file, rather than inline in `astro.config.mjs`, so that `test/headers.test.mjs` can
* read the same list and assert every entry against the running server — the config cannot be
* imported by plain Node, because Starlight ships TypeScript.
*
* Phase 14 moved the Ultima Online pages into their own group. `connect-a-game-server` did
* NOT move: its URL is now the game-neutral hand-off page, which is a better landing for an
* old link than a redirect into one game would be.
*/
export const docsRedirects = {
'/docs/administration/the-shard-connection': '/docs/ultima-online/the-shard-connection/',
'/docs/administration/client-files': '/docs/ultima-online/client-files/',
'/docs/reference/bridge-cfg': '/docs/ultima-online/bridge-cfg/',
'/docs/reference/sidecar-toml': '/docs/ultima-online/sidecar-toml/',
'/docs/reference/event-catalog': '/docs/ultima-online/event-catalog/',
};

View File

@@ -1,5 +1,6 @@
/**
* The documentation sidebar — PLAN.md §10 "Documentation", five groups, ~37 pages.
* The documentation sidebar — PLAN.md §10 "Documentation": five core groups, then one group
* per game after them (§16, D60).
*
* The pages themselves land in phases 7 and 8. This file exists in phase 1 because the
* shape of the journey is a design decision that is already made, and because a sidebar
@@ -22,7 +23,7 @@ export const docsSidebar = [
{ label: 'Install the site', slug: 'docs/getting-started/install-the-site' },
{ label: 'First run', slug: 'docs/getting-started/first-run' },
{ label: 'Install a game module', slug: 'docs/getting-started/install-a-game-module' },
{ label: 'Connect a game server', slug: 'docs/getting-started/connect-a-game-server' },
{ label: 'Connect your game server', slug: 'docs/getting-started/connect-a-game-server' },
{ label: 'Verify the whole stack', slug: 'docs/getting-started/verify-the-whole-stack' },
],
},
@@ -42,8 +43,6 @@ export const docsSidebar = [
{ label: 'Engagement rules', slug: 'docs/administration/engagement-rules' },
{ label: 'Message templates', slug: 'docs/administration/message-templates' },
{ label: 'Managing modules', slug: 'docs/administration/managing-modules' },
{ label: 'The shard connection', slug: 'docs/administration/the-shard-connection' },
{ label: 'Client files', slug: 'docs/administration/client-files' },
{ label: 'Maintenance and upgrades', slug: 'docs/administration/maintenance-and-upgrades' },
{ label: 'Troubleshooting', slug: 'docs/administration/troubleshooting' },
],
@@ -77,13 +76,62 @@ export const docsSidebar = [
items: [
{ label: 'Environment variables', slug: 'docs/reference/environment-variables' },
{ label: 'Installer CLI', slug: 'docs/reference/installer-cli' },
{ label: 'sidecar.toml', slug: 'docs/reference/sidecar-toml' },
{ label: 'Bridge.cfg', slug: 'docs/reference/bridge-cfg' },
{ label: 'HTTP API', slug: 'docs/reference/http-api' },
{ label: 'Shard event catalog', slug: 'docs/reference/event-catalog' },
{ label: 'Canonical documents', slug: 'docs/reference/canonical-documents' },
],
},
// One group per game, after Reference (PLAN.md §16, D60). Everything above this line is
// core and is held to core's words by checkTerms.mjs (D63, D64). A group whose label is a
// game's `name` in platform.json is that game's group, and may use that game's words — so
// the label is load-bearing: renaming it here without renaming the game turns it core.
{
label: 'Ultima Online',
items: [
{ label: 'The Ultima Online module', slug: 'docs/ultima-online' },
{ label: 'Connect a ServUO shard', slug: 'docs/ultima-online/connect-a-servuo-shard' },
{ label: 'Verify the bridge', slug: 'docs/ultima-online/verify-the-bridge' },
{ label: 'The shard connection', slug: 'docs/ultima-online/the-shard-connection' },
{ label: 'Client files', slug: 'docs/ultima-online/client-files' },
{ label: 'Troubleshooting', slug: 'docs/ultima-online/troubleshooting' },
{ label: 'Bridge.cfg', slug: 'docs/ultima-online/bridge-cfg' },
{ label: 'sidecar.toml', slug: 'docs/ultima-online/sidecar-toml' },
{ label: 'Shard event catalog', slug: 'docs/ultima-online/event-catalog' },
],
},
{
label: 'Rust',
items: [
{ label: 'The Rust module', slug: 'docs/rust' },
{ label: 'Install the bridge', slug: 'docs/rust/install-the-bridge' },
{ label: 'Connect the site', slug: 'docs/rust/connect-the-site' },
{ label: 'Verify the bridge', slug: 'docs/rust/verify-the-bridge' },
{ label: 'Linking Steam accounts', slug: 'docs/rust/linking-steam-accounts' },
{ label: 'Permissions and groups', slug: 'docs/rust/permissions-and-groups' },
{ label: 'Mod config from the site', slug: 'docs/rust/mod-config' },
{ label: 'Who sees who is online', slug: 'docs/rust/who-sees-who-is-online' },
{ label: 'Events, zones and rewards', slug: 'docs/rust/events-zones-and-rewards' },
{ label: 'Optional plugins', slug: 'docs/rust/optional-plugins' },
{ label: 'The live map', slug: 'docs/rust/the-live-map' },
{ label: 'Troubleshooting', slug: 'docs/rust/troubleshooting' },
{ label: 'sidecar.toml', slug: 'docs/rust/sidecar-toml' },
{ label: 'RunicGateway.json', slug: 'docs/rust/runicgateway-json' },
{ label: 'Event kinds', slug: 'docs/rust/event-kinds' },
// §16, D61/D72: RunicNPC is a subgroup of Rust, nested so it reads as part of the game.
{
label: 'RunicNPC',
items: [
{ label: 'RunicNPC', slug: 'docs/rust/runicnpc' },
{ label: 'Install RunicNPC', slug: 'docs/rust/runicnpc/install' },
{ label: 'Commands', slug: 'docs/rust/runicnpc/commands' },
{ label: 'NPC profiles', slug: 'docs/rust/runicnpc/npc-profiles' },
{ label: 'NPC placements', slug: 'docs/rust/runicnpc/npc-placements' },
{ label: 'Cost and caps', slug: 'docs/rust/runicnpc/cost-and-caps' },
{ label: 'Profile fields', slug: 'docs/rust/runicnpc/profile-fields' },
{ label: 'The API', slug: 'docs/rust/runicnpc/api' },
],
},
],
},
];
/**
@@ -105,7 +153,7 @@ export const plannedSidebar = {
'Install the site',
'First run',
'Install a game module',
'Connect a game server',
'Connect your game server',
'Verify the whole stack',
],
Administration: [
@@ -122,8 +170,6 @@ export const plannedSidebar = {
'Engagement rules',
'Message templates',
'Managing modules',
'The shard connection',
'Client files',
'Maintenance and upgrades',
'Troubleshooting',
],
@@ -148,10 +194,65 @@ export const plannedSidebar = {
Reference: [
'Environment variables',
'Installer CLI',
'sidecar.toml',
'Bridge.cfg',
'HTTP API',
'Shard event catalog',
'Canonical documents',
],
'Ultima Online': [
'The Ultima Online module',
'Connect a ServUO shard',
'Verify the bridge',
'The shard connection',
'Client files',
'Troubleshooting',
'Bridge.cfg',
'sidecar.toml',
'Shard event catalog',
],
// PLAN.md §16, D70 (phase 15). RunicNPC's subgroup lands in phase 16 (D61).
Rust: [
'The Rust module',
'Install the bridge',
'Connect the site',
'Verify the bridge',
'Linking Steam accounts',
'Permissions and groups',
'Mod config from the site',
'Who sees who is online',
'Events, zones and rewards',
'Optional plugins',
'The live map',
'Troubleshooting',
'sidecar.toml',
'RunicGateway.json',
'Event kinds',
{
RunicNPC: [
'RunicNPC',
'Install RunicNPC',
'Commands',
'NPC profiles',
'NPC placements',
'Cost and caps',
'Profile fields',
'The API',
],
},
],
};
/**
* A group's items as flat labels, a nested group's pages written `Group › Page` after the
* group's own label. Both trees go through this, so `checkSidebar.mjs` compares nested
* groups as strictly as top-level ones, and `checkTerms.mjs` reads every label.
*
* In `docsSidebar` a nested group is `{ label, items }`; in `plannedSidebar` it is
* `{ Label: [pages] }`.
*/
export function flatLabels(items) {
return items.flatMap((item) => {
if (typeof item === 'string') return [item];
if (Array.isArray(item.items)) return [item.label, ...flatLabels(item.items).map((l) => `${item.label} › ${l}`)];
if ('label' in item) return [item.label];
return Object.entries(item).flatMap(([label, pages]) => [label, ...flatLabels(pages).map((l) => `${label} › ${l}`)]);
});
}

View File

@@ -5,7 +5,7 @@ description: Local accounts and two-factor, SSO providers and the link-only poli
import { Aside } from '@astrojs/starlight/components';
**Admin → Authentication** has four tabs: Local Accounts, Google, Discord and Custom
**Admin → Authentication** has five tabs: Local Accounts, Google, Discord, Steam and Custom
Providers. One session model sits behind all of them — a web cookie, a mobile bearer token
and an SSO sign-in all produce the same session.
@@ -35,6 +35,19 @@ account is still a stranger.
Configuring Google here also unlocks **email delivery**, which reuses the same OAuth client
— see [Notifications and email](/docs/administration/notifications-and-email/).
### Steam
Steam signs people in with OpenID rather than OAuth, so it needs no client ID or secret — but
it does need a **Steam Web API key**, for the name and avatar Steam's sign-in does not carry,
and saving Steam as enabled without one is refused. It follows the same link-only policy, more
strictly: **Steam never creates an account**, whatever registration allows. A person may link
several Steam accounts, and each is listed on their account screen with its name, avatar and
Steam ID.
A game module can also be told which Steam accounts a signed-in person has proved are theirs,
which is how a game that knows its players by Steam account can recognise a member. The Rust
module uses it — see [Linking Steam accounts](/docs/rust/linking-steam-accounts/).
## Trusted devices
A second factor that asks on every sign-in on the same laptop trains people to click

View File

@@ -16,7 +16,7 @@ Two places hold configuration, and the line between them is not arbitrary.
The rule behind the split: **anything that needs a restart or a shell is environment;
anything an administrator should be able to change without either is in the panel.** That
is why the Discord bot token, the OAuth client secrets and the shard's auth token are *not*
is why the Discord bot token, the OAuth client secrets and the game module's sidecar token are *not*
environment variables — they are entered in the panel and stored encrypted.
## Settings

View File

@@ -27,7 +27,7 @@ glance.
<Aside type="caution" title="Publishing a news post announces it">
Publishing is what triggers the announcement pipeline — the Discord `#news` leg, and any leg
an installed module adds, such as the `uo` module's in-game town crier. It fires on
an installed module adds, such as the Ultima Online module's in-game town crier. It fires on
publication, so an accidental publish is an accidental announcement. See
[Notifications and email](/docs/administration/notifications-and-email/).
</Aside>

View File

@@ -168,8 +168,8 @@ which is where a person's record belongs.
A module declares its own triggers and its own audiences, in its own vocabulary, and it may
ship rules and message bodies to go with them. The Ultima Online module ships a large family
of them — houses falling to ruin, vendors running out of gold, a governor being seated, a
guild's fortunes — written in the voice of an in-world office rather than a system alert.
Team's fortunes — written in the voice of an in-world office rather than a system alert.
All of them arrive **disabled**, like every other seeded rule. Read the list in
**Admin → Engagement → Triggers**, turn on the ones your shard should send, and check the
**Admin → Engagement → Triggers**, turn on the ones your site should send, and check the
send log the first time each one fires.

View File

@@ -4,6 +4,7 @@ description: Author an event as phases and steps, price it against this deployme
---
import { Aside } from '@astrojs/starlight/components';
import GameExample from '../../../../components/GameExample.astro';
An **event** is a scheduled, bounded, audited change to a live game world. You write it once
as a sequence of phases, publish a version of it, put it on the calendar, and it runs — at
@@ -71,8 +72,13 @@ start doing things to your world.
Each row has two controls: whether the action is permitted on this deployment at all, and its
**per-run caps** — how much of a budget dimension one run may consume. Dimensions are
declared by the module (`uo.creatures`, `uo.bosses`, `uo.rewards` and so on), and consumption
is counted in the database with a conditional update, not checked in application code.
declared by the module, and consumption is counted in the database with a conditional
update, not checked in application code.
<GameExample game="uo">
The Ultima Online module declares `uo.creatures`, `uo.bosses`, `uo.rewards` and others —
one per kind of thing an event can spend.
</GameExample>
That distinction matters more than it sounds. A stolen admin session has already passed every
role check there is; it still cannot exceed the cap, because the cap is a condition on the
@@ -135,18 +141,30 @@ restart puts every borrowed value back too.
## The game server has its own switches
They live on the shard host, outside the site's reach, and the site cannot turn them on.
They live in the bridge plugin's config on the game server's host, not in the site's
database, and no event can turn them on.
**`EventsEnabled` is off by default, and it is a different switch from `AdminWriteEnabled`.**
Turning the admin plane on is consenting to staff moderation driven from a screen somebody is
looking at. Turning this on is consenting to the site changing and watching your world
unattended. One switch could not honestly express both.
**`EventsEnabled` is off by default**, in both games. Turning it on is consenting to the site
changing and watching your world unattended.
Beside it sit the game's own ceilings — how many creatures one call may spawn, how long a gate
may stand, how much one run may own in total, how often the world may be saved. **They refuse
rather than clamp**, for the same reason the caps do: a quietly shortened request leaves the
two halves disagreeing about what actually happened. See
[Bridge.cfg](/docs/reference/bridge-cfg/) for every key.
<GameExample game="uo">
`EventsEnabled` is a different switch from `AdminWriteEnabled`. Turning the admin plane on is
consenting to staff moderation driven from a screen somebody is looking at; turning events on
is consenting to unattended changes. One switch could not honestly express both. Every key
is in [`Bridge.cfg`](/docs/ultima-online/bridge-cfg/), which only the shard host can edit.
</GameExample>
<GameExample game="rust">
`EventsEnabled` is in each server's [`RunicGateway.json`](/docs/rust/runicgateway-json/). An
administrator can edit it on the host, or from the site's
[Mod config](/docs/rust/mod-config/) screen, which reaches the game host's config files
through the bridge.
</GameExample>
Beside it sit the game's own ceilings — how much one call may place, how long something it
creates may stand, how much one run may own in total. **They refuse rather than clamp**, for
the same reason the caps do: a quietly shortened request leaves the two halves disagreeing
about what actually happened.
## What players see

View File

@@ -102,7 +102,7 @@ Three rules for whatever proxy you use:
- **Terminate TLS at the proxy.** The app speaks HTTP; it is not meant to hold a
certificate.
## Upgrading the shard side
## Upgrading the game server side
A different deployment on a different host, and it moves on its own schedule:
@@ -111,22 +111,18 @@ sudo runicgateway update # re-resolves the bundle; --verify to see it first
sudo runicgateway doctor # confirm afterwards
```
`update` replaces the sidecar and restarts its service, re-syncs the overlay, and tells you
when ServUO needs restarting — it never restarts your shard itself. Because it resolves a
**bundle**, the sidecar and the plugin move together and cannot end up disagreeing about the
protocol.
`update` replaces the sidecar and restarts its service, redeploys the bridge plugin, and
tells you when the game server needs restarting — it never restarts your game server itself.
Because it resolves a **bundle**, the sidecar and the plugin move together and cannot end up
disagreeing about the protocol. Add the game's own flags as you did at install; see the
[Installer CLI](/docs/reference/installer-cli/).
<Aside type="caution" title="After you patch the UO client, press one more button">
Creature portraits, item pictures and the name table are read from that client, and the
site deliberately never re-reads them on its own — a restart does not, and neither does
`update`. They keep serving the old artwork until somebody presses *Update* on
**Admin → Client files**. It is one round trip when nothing has changed.
</Aside>
Each game can have its own day-two chores on top of this. Ultima Online's are in [its
group](/docs/ultima-online/client-files/#after-a-client-update).
<Aside type="note" title="Update the two sides in either order, but verify after each">
They are independent deployments joined by a version-checked contract: a mismatch is
rejected with a `409` rather than mis-parsed. So the worst case is a bridge that refuses to
pair until both sides are current — visible on
[the shard connection screen](/docs/administration/the-shard-connection/), and not silent
corruption.
pair until both sides are current — visible on the game module's connection screen, and
not silent corruption.
</Aside>

View File

@@ -7,7 +7,7 @@ import { Aside } from '@astrojs/starlight/components';
Every message your site sends — password resets, invitations, notifications — is a
**template** you can edit. They ship working, so a fresh site mails correctly before you
open this screen at all. You come here when you want it to sound like your shard.
open this screen at all. You come here when you want it to sound like your community.
**Admin → Engagement → Templates.**
@@ -105,7 +105,7 @@ Test sends are recorded in the send log like any other message, including when t
You do not start from a blank page. Pick a message that is close to what you want, press
**Duplicate**, and give the copy a key.
The **key** is how a rule refers to the template — `notify.house-idoc`, say. Lowercase
The **key** is how a rule refers to the template — `notify.team-welcome`, say. Lowercase
letters, digits, dots and dashes, and it cannot be changed later, so pick one that will
still make sense in a year.

View File

@@ -1,6 +1,6 @@
---
title: Moderation
description: Three screens that do three different jobs — Discord moderation, content reports, and appeals against a sanction.
description: Three screens that do three different jobs — Discord moderation, content reports, and appeals against a sanction — and what members can do for themselves.
---
import { Aside } from '@astrojs/starlight/components';
@@ -10,8 +10,8 @@ not overlap.
| Screen | Is about | Comes from |
|---|---|---|
| **Moderation** | Your **Discord** guild — bans, kicks, mutes, warnings, joins, leaves, filter and spam hits | the bot, captured live |
| **Reports** | **Team forum content** members have reported | the site |
| **Moderation** | Your **Discord** server — bans, kicks, mutes, warnings, joins, leaves, filter and spam hits | the bot, captured live |
| **Reports** | **Content** members have reported — Team forum threads and posts, and a game's chat lines where its module offers them | the site |
| **Appeals** | Sanctions people are asking you to reverse | the site |
## Moderation (Discord)
@@ -29,13 +29,20 @@ browsing the window.
## Reports
Reports raised by members about Team forum content. Two design decisions show through in
how this screen behaves:
Reports raised by members about Team forum threads and posts and, where a game module offers
it, the game's chat lines — the Rust module does, from the `⋯` menu on a chat line on the
site and a long press in the [app](/app/). Each report keeps a copy of what the item said when it was
reported, so an author editing it afterwards does not change what staff read. Three design
decisions show through in how this screen behaves:
- **They come to site staff, and a Team's own leaders never see them.** A leader moderates
their own forum, so a report *about a leader* has to reach someone above them.
- **Handling a report records a decision about the report.** It does not touch the content:
hiding or removing a post is done in the forum, or as a sanction against the account.
- **A report changes nothing on its own.** Filing one must never be a way to hide
something, so the reported item stays where it is until staff act.
- **Acting is a separate, deliberate step.** *Hide for everyone* on a report hides the item
from everybody except staff, who still see it marked *Hidden by staff* and can show it
again, and it records the report as actioned. Removing content outright, or sanctioning the
account, is still done in the forum or against the account.
The filters are *Open*, *Reviewing*, *Actioned*, *Dismissed* and *All*, and the count of
open reports sits at the top so the screen is glanceable.
@@ -46,6 +53,19 @@ that never empties stops being read, and the reporter's next report is the one t
matters.
</Aside>
## What members do for themselves
Two tools need no staff at all, and nothing about them reaches the queue:
- **Hide for me** takes one item out of that member's own view, on every device.
- **Block** takes everything a person writes — chat lines and forum content — out of the
blocker's view, on the site and in the app. The blocked person is not told. Staff cannot be
blocked, and a block whose target later becomes staff stops applying and says so. A game
player who has not linked a site account is blocked by their game identity, which turns
into a block on their account if they link one later.
A member undoes either from **Account → Blocked**.
## Appeals
An appeal is a request to reverse a sanction, filtered by *Open*, *Pending*, *Under

View File

@@ -82,7 +82,7 @@ at the wrong host.
Which legs exist depends on what has registered one:
- **Discord `#news`** is core's, and needs the bot below.
- **A module may add its own.** The `uo` module adds an in-game town crier, so a news post
- **A module may add its own.** The Ultima Online module adds an in-game town crier, so a news post
is announced to players who are logged into the game and never visit the site.
A leg brings its own settings with it — the town crier's duration is a module setting, not
@@ -90,7 +90,7 @@ a core one — which is why they are documented with the module rather than here
## The Discord bot
**Admin → Discord Bot**: enable it, give it the guild (server) ID and the bot token, and
**Admin → Discord Bot**: enable it, give it the **Guild (server) ID** and the bot token, and
save. The token is stored **encrypted in the database** and is never an environment
variable.

View File

@@ -9,8 +9,8 @@ Teams are a core platform primitive: membership, roles, forums, notifications, m
and the Discord integrations are all core's, and none of it knows what a Team *is* in your
game.
**Core cannot create a Team.** Teams arrive from the installed module — with the `uo`
module, they are the shard's guilds. On a deployment with no module, the Team machinery is
**Core cannot create a Team.** Teams arrive from the installed game module, which maps
whatever the game calls its groups of players onto a Team. On a deployment with no module, the Team machinery is
present and permanently empty. That is not a bug to work around; it is the contract that
lets the same forum, notification and moderation code serve any game.
@@ -25,15 +25,14 @@ reconciles them.
**Admin → Teams** shows a sync panel per module: last attempt, last success, consecutive
failures and the last error, with **Sync now** and **Resync now**.
The wording on that panel is exact and worth reading:
> Core has never had an answer it could trust. What is shown below is not a confirmed empty
> shard.
The wording on that panel is exact and worth reading. Until a sync has succeeded, it says
that core has never had an answer it could trust, and that the list below it is not a
confirmed empty one.
An empty list therefore means one of two very different things — there are no Teams, or
nobody could ask. The panel tells you which, and a *last success: never* with a *last
error* of `no uo-link configured` is the second. Fix
[the shard connection](/docs/administration/the-shard-connection/) and sync again.
nobody could ask. The panel tells you which: a *last success: never* with a *last error*
that names the game connection is the second. Fix the game module's connection to its game
server and sync again. Each game's group in the sidebar covers its own connection screen.
## Forums
@@ -105,8 +104,8 @@ event leaves the site.
**Voice channels** — gives each Team a Discord voice channel of its own, with access
granted by a per-Team role, so a Team's members can see and join theirs and nobody else
can. It needs the bot reachable, and members need a linked Discord account and guild
membership.
can. It needs the bot reachable, and members need a linked Discord account and membership of
your Discord server.
Its three settings deserve a thought each:
@@ -114,10 +113,10 @@ Its three settings deserve a thought each:
|---|---|
| **Minimum members** | How large a Team must be to get a channel. Every active member counts, linked account or not. |
| **Grace window (days)** | How long a Team keeps its channel after it stops qualifying. A Team that recovers inside the window keeps the same channel; zero removes it on the next pass. |
| **Staff roles** | Roles that can see and join every Team's channel. Guild administrators already can, so this is for staff who are not administrators. |
| **Staff roles** | Roles that can see and join every Team's channel. Discord server administrators already can, so this is for staff who are not administrators. |
<Aside type="caution" title="Voice channels are a per-guild ceiling, not a per-Team one">
Discord's role and channel limits apply to the whole guild, so a site with many small Teams
<Aside type="caution" title="Voice channels are a per-server ceiling, not a per-Team one">
Discord's role and channel limits apply to the whole Discord server, so a site with many small Teams
can exhaust them. The minimum-members setting is the lever that keeps the count sane, and
it is easier to raise it before provisioning than to unpick channels afterwards.
</Aside>

View File

@@ -67,50 +67,30 @@ deployment has nothing supervising it — `npm start` in a terminal, a container
## The game screens are empty or say offline
Work outwards from the game, and stop at the first check that fails.
Work outwards from the game, and stop at the first check that fails. The order is the same
for every game; the commands are each game's own.
1. **In game:** `[bridge status` — `connected=False` means the shard cannot reach the
sidecar.
2. **On the shard host:** `curl -s http://127.0.0.1:8080/health` — `plugin_connected: true`
is the value that matters.
3. **On the shard host:** `runicgateway doctor` — checks the install record, every overlay
file hash, the service, and that the sidecar and overlay agree on a protocol.
4. **On the site:** the [shard connection screen](/docs/administration/the-shard-connection/)
— its four indicators say which link is broken.
1. **On the game server:** the bridge plugin says whether it is connected to the sidecar.
2. **On the game server's host:** the sidecar's `/health` answers without a token, and
*plugin connected* is the value that matters.
3. **On the game server's host:** `runicgateway doctor` checks the install record, the
files it deployed, the service, and that the sidecar and the bridge plugin agree on a
protocol.
4. **On the site:** the game module's connection screen says which link is broken.
Two log lines with specific meanings: **`409`** is a protocol mismatch (set the Protocol
field to what `/health` reports), and **`401`** is the auth token (read the live one back
with `uo-link-sidecar --print-config`; do not retype it from a screenshot).
Two responses from a sidecar mean the same thing for every game: **`409`** is a protocol
mismatch (the sidecar refuses rather than mis-parsing), and **`401`** is the auth token.
<Aside type="note" title="“Nothing changed and it stopped working” usually means a ServUO update">
An update to the server tree can revert `Scripts.csproj`, at which point the plugin sits in
the tree and never compiles — and ServUO ignores the script build's exit code, so the boot
looks clean. `doctor` catches it by comparing file hashes against the install record.
</Aside>
## The bestiary has no pictures, or items show numbers
Those come out of the UO client on the shard host, and **nothing imports them on a
restart** — a button on **Admin → Client files** is the only thing that does. Check that
page first: it reports why rather than failing.
| What it says | What to do |
|---|---|
| Counts are zero and no import is recorded | Press *Update*. On a shard that was linked before this existed, nobody ever has. |
| *…set `AssetsEnabled` on the shard* | The asset plane is off in `Bridge.cfg`. It is a separate switch on purpose. |
| *The shard host cannot render images* | A Linux host with no `libgdiplus`. Install it and press *Update* again. Names are unaffected either way. |
| *The shard is busy with another client-file request* | Not a fault. Something ordinary holds the slot; it frees itself. |
| Pictures were fine and went blank | Check the uploads volume before anything else — the database still remembers pictures that are no longer on disk, and *Re-import everything* is the button for exactly that. |
Items reading as numbers rather than names is the same page, different section: it means the
cliloc table has not been imported. See [Client files](/docs/administration/client-files/).
Each game's group in the sidebar has its own troubleshooting page with the exact commands:
[Ultima Online](/docs/ultima-online/troubleshooting/) and [Rust](/docs/rust/troubleshooting/).
## Teams are missing
Check the sync panel on **Admin → Teams** before anything else: *last success: never* with
`no uo-link configured` means the shard connection, not the Team machinery. And on a site
with **no module installed**, an empty Team list is correct and final — core cannot create
a Team. See [Teams](/docs/administration/teams/).
an error naming the game connection means the module could not ask its game server, not
that the Team machinery is broken. And on a site with **no module installed**, an empty
Team list is correct and final — core cannot create a Team. See
[Teams](/docs/administration/teams/).
## Email and announcements never arrive

View File

@@ -97,8 +97,8 @@ A module that serves game data brings its **own** audience rules, and core does
them beyond the gates it hands over — `requireAuth`, `requireRole`, and the tier group
gates. See [The module API](/docs/modules/the-module-api/#registerroutes-and-the-tier-gate).
`module-uo`'s is the worked example, and it is a real boundary rather than a convenience
filter: an admin-configurable, per-feature and per-field audience ladder with **fail-closed
The Ultima Online module's is the worked example, and it is a real boundary rather than a
convenience filter: an admin-configurable, per-feature and per-field audience ladder with **fail-closed
defaults**, applied at routes, at SSE subscribe time, *and* at the navigation. All three,
because a surface that is filtered in only two of those places leaks through the third.

View File

@@ -114,10 +114,13 @@ something must not take that path.
are re-validated against the database on every request, so a demotion takes effect on the
next click.
The game's switches are the layer the site cannot reach: `EventsEnabled` and
`AdminWriteEnabled` live in a file on the shard host and are off out of the box, and the
game's own ceilings **refuse rather than clamp** — because a silently shortened request leaves
the two halves disagreeing about what happened.
The game's switches are the layer outside the site's own database: they live in the bridge
plugin's own config on the game server's host — `EventsEnabled`, in both games — and are off
out of the box. No event and no role check can turn one on. On Rust an administrator can
still edit that file from the game module's config screen, which reaches the host's config
files through the bridge, so there it is a separate deliberate act rather than an unreachable
one. The game's own ceilings **refuse rather than clamp** — because a silently shortened
request leaves the two halves disagreeing about what happened.
<Aside type="note" title="Stated plainly">
The module boundary is **not** a security boundary — a module runs in the same process with
@@ -135,7 +138,7 @@ That is why the caps and the leases matter more here than the role check does.
same versioned wire the game already speaks, through the same sidecar. Core still holds no
game connection.
- **[Teams](/docs/architecture/teams-architecture/)** — "this Team's members" is already a
registered audience, so a guild-scoped event needs no event-side feature at all.
registered audience, so an event scoped to one Team needs no event-side feature at all.
- **News** — an event does not write posts. A core action links an *existing* post to a run and
enqueues it through the announcement pipeline, so the in-game town crier and Discord arrive
as legs that already exist.

View File

@@ -1,34 +1,47 @@
---
title: Protocol versions
description: One number, declared in three repositories, that decides whether a shard and a sidecar are allowed to talk to each other.
description: One number per game, declared in three places, that decides whether a game server and a sidecar are allowed to talk to each other.
---
import { Aside } from '@astrojs/starlight/components';
import GameExample from '../../../../components/GameExample.astro';
import platform from '../../../../data/platform.json';
The loopback wire protocol between the game plugin and the sidecar is a **versioned
The loopback wire protocol between the bridge plugin and the sidecar is a **versioned
compatibility contract**, not a build dependency. Nothing compiles the three sides together,
so the number is what stops a mismatch from being discovered as corrupted data.
Each game has its own protocol, numbered independently: {platform.games.uo.name} is on
**{platform.games.uo.protocol}** and {platform.games.rust.name} on
**{platform.games.rust.protocol}**. The two numbers are not comparable — they version two
different wires. The examples below are the {platform.games.uo.name} bridge's; the
{platform.games.rust.name} bridge declares its number in the same three kinds of place.
different wires. Everything below holds for both.
## Three declaration sites
The same number is written down in three places, and they must move together.
The same number is written down in three places, and they must move together:
1. **The sidecar's source** declares `PROTOCOL_VERSION` — what the sidecar speaks.
2. **The bridge plugin's release manifest** declares `protocol` — what the plugin speaks.
3. **The bundle manifest** copies the plugin's number in CI, so a released pair carries its
own claim.
<GameExample game="uo">
| Where | What declares it |
|---|---|
| `link/sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.uo.protocol} — what the sidecar speaks |
| `servuo-plugins/overlay.toml` | `protocol`, currently {platform.games.uo.protocol} — what the plugin overlay speaks |
| The bundle manifest | Copied from `overlay.toml` by CI, so a released pair carries its own claim |
| `link` `sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.uo.protocol} |
| `servuo-plugins` `overlay.toml` | `protocol`, currently {platform.games.uo.protocol} |
</GameExample>
<Aside type="caution" title="Bump the overlay in the same PR as the emitters">
CI folds `overlay.toml` into the release manifest, and **the installer refuses to pair an
overlay and a sidecar whose protocol numbers disagree**.
<GameExample game="rust">
| Where | What declares it |
|---|---|
| `Rust-Link` `sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.rust.protocol} |
| `Rust-Plugins` `overlay.toml` | `protocol`, currently {platform.games.rust.protocol} |
</GameExample>
<Aside type="caution" title="Bump the plugin's manifest in the same PR as the emitters">
CI folds the plugin's manifest into the release manifest, and **the installer refuses to
pair a bridge plugin and a sidecar whose protocol numbers disagree**.
A bump that lands separately from the emitters does not fail loudly — it silently fails to
compose into a bundle, and the next release simply does not appear.
@@ -38,19 +51,28 @@ compose into a bundle, and the next release simply does not appear.
Two independent mechanisms, at two different boundaries.
**Sidecar ↔ website.** Every sidecar response carries `X-UOLink-Version`. A mismatch is
rejected with **`409`** rather than mis-parsed. The website's protocol expectation is
admin-managed, alongside the base URL and token, on the shard configuration screen.
**Sidecar ↔ website.** Every sidecar response carries its protocol version in a header. A
mismatch is rejected with **`409`** rather than mis-parsed, and the game module's admin
screen is where an administrator sees it.
**Overlay ↔ sidecar.** The installer resolves a **bundle** — an exact, protocol-checked
sidecar and overlay pair published by CI — and never "latest of each". That is the whole
**Bridge plugin ↔ sidecar.** The installer resolves a **bundle** — an exact,
protocol-checked pair of sidecar and bridge plugin published by CI — and never "latest of
each". That is the whole
reason bundles exist: two independently released components that must agree cannot be
allowed to be chosen independently.
## What a bump obliges
Changing a message shape means editing every side plus the specification. The most recent
bump — **8**, which taught the bridge to carry a game's own client files — touched four
Changing a message shape means editing every side plus the specification: the bridge plugin,
the sidecar, the game module, and the protocol document in `docs`.
**`website` is usually not on that list, and its absence is the interesting part.** Core
holds no game connection and names no game noun, so most protocol bumps do not reach it at
all. One reaches core only when what changes is the shape of something core owns — a ledger,
a place to store a picture — rather than a game noun.
<GameExample game="uo">
Protocol 8 taught the bridge to carry a game's own client files, and touched four
repositories:
| Repository | What had to change |
@@ -60,24 +82,23 @@ repositories:
| `module-uo` | The importers, the admin screen, and the pages that render a picture |
| `docs` | The protocol document and the integration guide |
**`website` is not on that list, and its absence is the interesting part.** Core holds no
game connection and names no game noun, so most protocol bumps do not reach it at all. The
one before this did, because what changed then was not a game *noun* but the shape of a
thing core owns the ledger for. This one did not reach core because everything it needed —
somewhere to put a picture — core already offered every module. Its entire share of eight
phases of work was a **deletion**: a developer tool it no longer needed.
Core's entire share of eight phases of work was a **deletion**: a developer tool it no longer
needed. Everything the bump needed — somewhere to put a picture — core already offered every
module.
</GameExample>
**A protocol bump can also require a store migration**, because the sidecar persists what it
forwards. That is not automatic, and it has happened once: version 4 added a column to a
table that already existed. Versions 5, 6, 7 and 8 needed none, because every frame is
persisted whole — a bump that only widens a frame, or adds a kind, or adds a guarantee about
how a command is executed, asks nothing of a store that defines no schema for a frame's
contents. That is the dumb-forwarder property paying for itself.
forwards. That is not automatic, and it is rare: every frame is persisted whole, so a bump
that only widens a frame, or adds a kind, or adds a guarantee about how a command is
executed, asks nothing of a store that defines no schema for a frame's contents. That is the
dumb-forwarder property paying for itself.
Version 8 puts it more sharply still. It is the largest bump this protocol has had, and it
moves megabytes of artwork rather than events — and it changed **no line** of the sidecar's
store, because the things it carries are answers to requests rather than events to keep. A
forwarder that holds no opinion about what it forwards has nothing to migrate.
<GameExample game="uo">
It has happened once: version 4 added a column to a table that already existed. Versions 5
to 8 needed none. Version 8 is the largest bump the protocol has had, and it moves megabytes
of artwork rather than events — and it changed **no line** of the sidecar's store, because
the things it carries are answers to requests rather than events to keep.
</GameExample>
## This is not the module API version
@@ -85,7 +106,7 @@ Two different numbers, versioning two different contracts, and confusing them is
| | Versions | Lives in | Checked |
|---|---|---|---|
| **`PROTOCOL_VERSION`** | The game ↔ sidecar wire | `link`, `servuo-plugins`, the bundle | `X-UOLink-Version`, and the installer's pairing check |
| **`PROTOCOL_VERSION`** | The game ↔ sidecar wire, one per game | The sidecar, the bridge plugin, the bundle | The sidecar's version header, and the installer's pairing check |
| **`MODULE_API_VERSION`** | The website ↔ module contract | `website`, and every module's `coreApi` | At module load, before the module's code runs |
A module that never talks to a game server has no protocol version at all. See [The module
@@ -113,11 +134,11 @@ What is worth inheriting is the **shape**:
## Canonical documents
Each game's protocol has its own record in the
[`docs` repository](https://gitea.whitlocktech.com/RunicGateway/docs). For Ultima Online,
[`link/v8.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v8.md)
is the current protocol's record, including its cross-repository obligations, and
[`link/v7.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v7.md)
the one before it;
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
§7 is the wire protocol, and
[`link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md)
the integration guide.
§7 is the wire protocol. For Rust,
[the Rust bridge protocol](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
is both.

View File

@@ -4,28 +4,49 @@ description: The whole platform in one place — what each repository is, what t
---
import { Aside } from '@astrojs/starlight/components';
import GameExample from '../../../../components/GameExample.astro';
The drawn version of this, for evaluators, is on
[Architecture](/architecture/). This page is the detailed account.
## Ten repositories, deployed independently
## Fourteen repositories, deployed independently
Nothing here is a monorepo. Each repository has its own history, its own CI and its own
release cadence; what binds them is a set of **versioned contracts**, not a build.
Seven of them are core, and serve every game:
| Repository | What it is |
|---|---|
| `website` | The Node/Express + MariaDB + React site. The only internet-facing web app |
| `Module-uo` | All the *Ultima Online* code, installed into the site as a module |
| `link` | The **uo-link sidecar**, in Rust — the only network-facing bridge component |
| `servuo-plugins` | The in-game plugin, C#, that feeds the sidecar |
| `installer` | Deploys the shard side: sidecar plus plugin overlay |
| `installer` | Deploys a game server's side: the bridge plugin, and the sidecar with its service |
| `Android-app` | Native Android client of the website API |
| `Integration-kit` | The instruction book for putting a different game on the platform |
| `docs` | Canonical design docs and the protocol spec |
| `docs` | Canonical design docs and the protocol specs |
| `runicgateway.com` | This site |
| `.profile` | The organisation landing page |
The other seven belong to a game. Each game has the same three: **a game module** that adds
its screens to the site, **a sidecar** that is the only network-facing part of its bridge,
and **a bridge plugin** that runs inside the game server and feeds the sidecar.
<GameExample game="uo">
| Repository | Its part |
|---|---|
| `Module-uo` | The game module |
| `link` | The sidecar, uo-link, in Rust |
| `servuo-plugins` | The bridge plugin, a C# overlay ServUO compiles at boot |
</GameExample>
<GameExample game="rust">
| Repository | Its part |
|---|---|
| `Module-Rust` | The game module |
| `Rust-Link` | The sidecar, rust-link, in Rust |
| `Rust-Plugins` | The bridge plugin, for Oxide and Carbon |
| `runicnpc-rust` | RunicNPC, an NPC plugin the bridge drives, which also works on its own |
</GameExample>
## The layers
```
@@ -59,9 +80,8 @@ particular game. Routes, tables, pages, navigation and push streams for a game a
[a module](/docs/modules/the-module-system/) the operator installed. Core provides the seams;
the module fills them.
That is why the architecture below describes `module-uo` as *the worked example* rather than
as part of the platform. It is the module every other module is measured against, not a
component core depends on.
That is why the architecture below describes a game module as something core *loads* rather
than as part of the platform. There are two, and core depends on neither.
## The invariants
@@ -69,29 +89,29 @@ These hold across repository boundaries, and every one of them is load-bearing.
### The game is never network-reachable
The ServUO shard **dials out** over loopback TCP `127.0.0.1:7788`, newline-delimited JSON,
to the sidecar. The sidecar is the listener; the game opens no port. Only the sidecar is
exposed, and only the website's backend talks to it.
The game server's bridge plugin **dials out** to the sidecar over loopback TCP,
newline-delimited JSON, on `127.0.0.1`. The sidecar is the listener; the game opens no port.
Only the sidecar is exposed, and only the website's backend talks to it.
See [The bridge](/docs/architecture/the-bridge/).
### A wedged sidecar can never stall the game
On the C# side, `Emit()` enqueues onto a **bounded, drop-oldest** queue and returns
immediately. It never touches the socket from the game's core thread. Every world read
happens on the core thread; a dedicated writer thread drains the queue.
In the bridge plugin, `Emit()` enqueues onto a **bounded, drop-oldest** queue and returns
immediately. It never touches the socket from the game's main thread. Every world read
happens on the main thread; a dedicated writer thread drains the queue.
Dropping game events is strictly better than pausing the game to deliver them.
### The website degrades rather than fails
The sidecar REST client never throws — every call returns `{ ok, data, status }`. The public
site still renders with the shard shown offline.
site still renders with the game shown offline.
That guarantee covers **reading the configuration too**: resolving the admin-managed config
decrypts a stored token, which throws if the ciphertext cannot be authenticated (a rotated
`SECRET_ENC_KEY`, or a database dump restored under a different key). That is caught inside
the client and reported as unavailable, so a wrong key degrades the shard surface instead of
the client and reported as unavailable, so a wrong key degrades the game's screens instead of
500-ing it — and the admin config screen keeps working, which is the screen you need in order
to recover.
@@ -128,7 +148,7 @@ variables](/docs/reference/environment-variables/).
## A deploy is two independent installs
Worth stating plainly, because it is the single most common misunderstanding: **the
installer binary sets up the shard side only, and never contacts the website.** The website
installer binary sets up the game server side only, and never contacts the website.** The website
is a separate Docker deployment on, usually, a different machine.
The [installation path](/docs/getting-started/requirements/) walks both in order.

View File

@@ -1,12 +1,13 @@
---
title: Teams architecture
description: Teams is a contract, not a surface — how core owns guilds, clans and corporations without ever learning what one is called.
description: Teams is a contract, not a surface — how core owns every game's groups of players without ever learning what one is called.
---
import { Aside } from '@astrojs/starlight/components';
Most games have groups: guilds, clans, corporations, tribes, crews. Runic Gateway supports
them as a **core platform primitive**, while core itself never learns what yours is called.
Most games have groups of players, and every game has its own word for them. Runic Gateway
supports them as a **core platform primitive**, the **Team**, while core itself never learns
what your game calls one.
The administrator's view is [Teams](/docs/administration/teams/).
@@ -25,7 +26,8 @@ fill** — `registry.declareModuleSlot(id, name, { core })`, with core offering
rather than naming slots.
<Aside type="caution" title="Why the direction matters">
The first version had core's fills naming three of `module-uo`'s slots **literally**. It
The first version had core's fills naming three of the first game module's slots
**literally**. It
worked for exactly one module and silently did nothing for any other game — an empty page
with nothing logged.

View File

@@ -15,11 +15,11 @@ understanding before you build one for another game.
## The shape
```
ServUO shard ──dials out──▶ uo-link sidecar ──HTTP + WS──▶ website
(C# plugin) 127.0.0.1:7788 (Rust) bearer + version (module)
newline JSON
▲ │
└──────── the game opens NO port ──────┘
game server ──dials out──▶ sidecar ──HTTP + WS──▶ website
(bridge plugin) 127.0.0.1 bearer + version (game module)
newline JSON
▲ │
└────────── the game opens NO port ───────┘
```
Three properties fall out of that diagram, and each is a rule rather than an
@@ -27,7 +27,7 @@ implementation detail.
## 1. The game dials out
**The sidecar is the listener. The game connects to it.** The shard opens no port at all,
**The sidecar is the listener. The game connects to it.** The game server opens no port at all,
and nothing on the internet can reach it even in principle.
This inverts the intuitive design — you would expect the thing with the data to serve it —
@@ -41,9 +41,9 @@ loopback TCP.
This is the constraint the plugin is built around.
On the C# side, `Emit()` **enqueues onto a bounded, drop-oldest queue and returns
immediately**. It never touches the socket from the game's core thread. Every world read
happens on the core thread; a dedicated writer thread drains the queue.
In the bridge plugin, `Emit()` **enqueues onto a bounded, drop-oldest queue and returns
immediately**. It never touches the socket from the game's main thread. Every world read
happens on the main thread; a dedicated writer thread drains the queue.
<Aside type="caution" title="Dropping events beats pausing the game">
If the queue fills, the oldest events are discarded. That is the correct trade: a game
@@ -54,7 +54,7 @@ Design your own plugin the same way. The game thread must never block on I/O —
socket, not on a lock held by a writer, not on a DNS lookup.
</Aside>
Inbound commands get the mirror rule: **every inbound handler marshals to the core thread
Inbound commands get the mirror rule: **every inbound handler marshals to the main thread
before touching world state.**
## 3. The sidecar persists before it forwards
@@ -77,66 +77,58 @@ than accumulating history.
**Point-in-time reads and commands** go over **REST**, through a client that never throws.
**Bulk reads** — a game's own client artwork, its string table, its spawn files — are the
newest and the least obvious. They go over the request/reply path in **pages**, with **one
**Bulk reads** — a game's own files, such as its client artwork or its string table — are
the newest and the least obvious, and so far only one game's bridge needs them. They go over the request/reply path in **pages**, with **one
request in flight at a time** and a hard cap on how large a single line may be.
<Aside type="note" title="Why bulk data must not ride the event stream">
It is the tempting shortcut, and it is wrong for a structural reason rather than a
performance one: the sidecar **persists every event and broadcasts it to every connected
client**. That is exactly what you want for "a house went IDOC" and exactly what you do not
client**. That is exactly what you want for "a player logged in" and exactly what you do not
want for hundreds of megabytes of artwork, which is an *answer to a question somebody
asked* rather than news.
Sending it as replies instead is what let the same bump move megabytes without the sidecar's
store changing by a line. The single slot is the other half: it is what keeps the queue
Sending it as replies instead is what lets a protocol bump move megabytes without the
sidecar's store changing by a line. The single slot is the other half: it is what keeps the queue
between the game and the writer thread shallow, so rule 2 above still holds while a
transfer is running.
</Aside>
Every call carries `Authorization: Bearer <token>` and an `X-UOLink-Version` header. **A
Every call carries `Authorization: Bearer <token>` and a protocol-version header. **A
protocol mismatch fails fast with `409`** rather than being mis-parsed — see [Protocol
versions](/docs/architecture/protocol-versions/).
## What the shard can say
## What a game server can say
The catalog spans sessions and identity, character state, economy and commerce, housing and
IDOC, combat and PvP, progression, cheat detection and staff audit, and server lifecycle.
A representative line looks like:
Each game has its own event catalog, because each game has its own things worth telling a
website about. Every catalog has the same structure, though: kinds the module declares,
each one either safe for the public stream or kept to the admin one.
```json
{"t":1752,"kind":"vendor.sale",
"buyer":{"serial":"0x1A2B","acct":"PerryAdimn"},
"owner":{"serial":"0x33C1","acct":"Feng"},
"item":{"serial":"0x4001A2","type":"Longsword","amount":1},
"price":75000,"commission":3750}
```
The full catalog is the [Shard event catalog](/docs/reference/event-catalog/).
- **Ultima Online:** [its event catalog](/docs/ultima-online/event-catalog/), in the Ultima Online group
- **Rust:** [its event kinds](/docs/rust/event-kinds/), in the Rust group
## Two design details worth stealing
**`server.hello` is per-connection, not per-boot.** The sidecar restarts independently of
the game, so anything it needs up front must be re-sent on **every** connect. An earlier
draft emitted a "started" event once at boot; a sidecar that came up second never received
it and had no idea which shard it was attached to.
it and had no idea which game server it was attached to.
It carries a `bootId` — a GUID generated at server start, stable across sidecar reconnects
and changed on every game restart. That is how the sidecar tells *"I reconnected"* (keep
cached state) from *"the game restarted"* (discard it).
**Rosters are sets, not signatures.** Guild membership is compared as a set rather than
folded into a checksum, because a sum can collide: one member joining and another leaving
between two sweeps offset each other, and the guild reads as unchanged. A set can also be
*differenced*, which is what makes per-member leave events possible for a game that raises
no event for leaving.
On a guild's **first** sweep there is no prior set, so nothing is reported as leaving — an
unknown roster becoming known is not 155 people leaving at once.
**Rosters are sets, not signatures.** A bridge that reports a Team's members should send
the membership as a set rather than fold it into a checksum, because a sum can collide: one
member joining and another leaving between two sweeps offset each other, and the Team reads
as unchanged. A set can also be *differenced*, which is what makes per-member leave events
possible for a game that raises no event for leaving. The Ultima Online bridge does exactly
this; its [event catalog](/docs/ultima-online/event-catalog/#rosters-are-sets-not-signatures)
has the details.
## Building one for another game
The bridge is not UO-specific in shape, only in vocabulary. Chapters 3 and 4 of [the
Both games' bridges have this shape; only their vocabulary differs. Chapters 3 and 4 of [the
Integration Kit](/docs/modules/the-integration-kit/) cover the sidecar and the game-side
plugin, and they are the two parts where the mistakes are most expensive.

View File

@@ -1,139 +1,52 @@
---
title: Connect a game server
description: The installer binary on the shard host — what it deploys, what it asks, and the four values it prints for the website.
title: Connect your game server
description: The second install, on the machine that runs your game server — what every game's has in common, and where each game's own steps are.
---
import platform from '../../../../data/platform.json';
import { Aside, Steps } from '@astrojs/starlight/components';
This is the second of the two installs, and it happens on the machine that runs your game
server. One binary deploys the plugin, installs the sidecar, registers its service, and
prints four values for you to paste into the website.
server. It never contacts your website, and it never starts or stops your game server.
It never contacts your website, and it never starts or stops your shard.
Every game's version of this step has the same shape:
## What gets deployed
| # | Component | Where it goes |
|---|---|---|
| 1 | **The plugin overlay** — C# source ServUO compiles at boot | into your ServUO tree |
| 2 | **The uo-link sidecar** — a small Rust service | a system directory, plus a service |
| 3 | **A record of the run** | `install.json`, with per-file hashes and backups |
1. **The bridge plugin** goes onto the game server, where the game's own plugin system loads
it.
2. **The sidecar** goes onto the same host, as a service. It is the only part of the bridge
that listens on a network.
3. **You paste what the install prints into the site** — the sidecar's address and its auth
token, plus whatever else that game's screen asks for — on the game module's admin screen.
```
ServUO shard ──loopback TCP 127.0.0.1:7788──► uo-link sidecar ──HTTP + WebSocket──► website
game server ──loopback, dials out──► sidecar ──HTTP + WebSocket──► website
```
The shard **dials out**. It never listens for the website and is never reachable from the
internet; only the sidecar is exposed, and only to your site.
The game server **dials out** to the sidecar over loopback. It never listens for the website
and is never reachable from the internet; only the sidecar is exposed, and only to your
site.
## Install
The [installer](/docs/reference/installer-cli/) ({platform.releases.installer}) does all of
this for both games, told which one it is setting up. It installs a **bundle** — an exact,
protocol-checked pair of sidecar and bridge plugin — never "the latest of each".
<Steps>
## Pick your game
1. **Download the binary for your OS, and `SHA256SUMS`**, from the
[installer releases page](https://gitea.whitlocktech.com/RunicGateway/installer/releases)
({platform.releases.installer}).
Releases are **unsigned** — there is no code-signing certificate, so that checksum file
is the whole trust anchor. Check it:
```bash
sha256sum -c SHA256SUMS --ignore-missing
chmod +x runicgateway-installer-linux-x86_64
```
On Windows, `(Get-FileHash .\runicgateway-installer-windows-x86_64.exe -Algorithm SHA256).Hash`
and compare. Windows will also show a SmartScreen prompt on first run, for the same
reason.
2. **Stop the shard.** `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit, so
the installer refuses to deploy under a running server.
3. **Run it, elevated.**
```bash
sudo ./runicgateway-installer-linux-x86_64 install
```
Add `--verify` first if you want to see every change it would make and write nothing.
It asks four things: your ServUO root, whether to apply the optional patch tier, the
hostname your website should use to reach this machine, and your site's URL (used only
to print a link at the end).
4. **Read the summary.** It reports the overlay sync file by file, the sidecar binary and
its verified hash, the config and database paths, and the service state. Then it says
what you must do next — restart ServUO yourself, because it will not do that for you.
</Steps>
<Aside type="note" title="It installs a bundle, not “latest of each”">
The three components version independently but must agree on one wire protocol, so what it
resolves is a **bundle**: an exact, protocol-checked pair of sidecar and overlay versions
({platform.games.uo.bundle.tag} today — sidecar {platform.games.uo.bundle.sidecar}, overlay {platform.games.uo.bundle.overlay}).
`--bundle <tag>` pins an exact past combination, so a reinstall in six months reproduces
today's install rather than tomorrow's.
</Aside>
## The patch tier is optional
Most of the plugin is *added* files, which is why the base install is a safe copy. Two
features need edits to stock ServUO sources, and those are opt-in, off unless you say yes,
and refused where the target lines are not stock. Skipping the tier costs you vendor-sale
events and in-game moderation audit forwarding; everything else works.
The tier is written and tested against stock ServUO {platform.games.uo.bundle.servuoMin}. On any
other version it is unsupported and untested, and the prompt makes you answer past a
warning.
## Paste the four values into the site
A successful run ends by printing the one step it cannot do for you:
```
Base URL http://shard.example.com:8080
WebSocket URL ws://shard.example.com:8080/ws
Protocol version 4
Auth token 4f9c… (also in sidecar.toml)
```
Every value comes from asking the installed sidecar itself, so it cannot drift from what
the service actually runs.
On the site, sign in as an administrator and open **Shard (uo-link)** in the admin
sidebar — `/admin/uo/link`. Tick *Enable the shard integration*, paste **Base URL**,
**WebSocket URL**, **Auth token** and **Protocol**, and save. The ingest client restarts
immediately.
<Aside type="caution" title="Installer v0.1.0 prints an older path for that screen">
v0.1.0 prints `…/admin/shard`. Since the shard screens became part of the `uo` module — and
a module owns one path segment wherever it appears — the screen moved to
**`/admin/uo/link`**.
The old path does not fail visibly: the site has no route for it, so it sends you to the
dashboard, and that looks like the link worked. The four values you were just told to paste
then have nowhere to go. Use the sidebar, or the path above.
Fixed in **v0.1.1**, which prints the real path. Only matters if you are running the older
binary.
</Aside>
The token is encrypted at rest and **never returned to any client** — losing it means
reading it back from `sidecar.toml` on the shard host, not from the website.
| Game | Its steps |
|---|---|
| **{platform.games.uo.name}** | [Connecting the server](/docs/ultima-online/connect-a-servuo-shard/), then [verifying its bridge](/docs/ultima-online/verify-the-bridge/), in the Ultima Online group |
| **{platform.games.rust.name}** | [Installing the bridge](/docs/rust/install-the-bridge/) — the installer, a Pterodactyl egg, or by hand — then [connecting the site](/docs/rust/connect-the-site/), in the Rust group |
## If the website is on a different machine
The sidecar binds `127.0.0.1:8080`, reachable only from the shard host. If the site runs
elsewhere, widen the bind and then narrow the access:
The sidecar listens on `127.0.0.1` by default, reachable only from the game server's host.
If the site runs elsewhere, widen the sidecar's web bind and then narrow the access:
1. Set `[web] bind` in `sidecar.toml` to `0.0.0.0:8080` and restart the service.
2. **Firewall that port to your website's address only.** The auth token is always on, but
1. **Firewall that port to your website's address only.** The auth token is always on, but
it travels as a plain bearer token — the sidecar speaks HTTP, not HTTPS.
3. If the two hosts are not on a trusted network, put the sidecar behind a TLS reverse
2. If the two hosts are not on a trusted network, put the sidecar behind a TLS reverse
proxy or a VPN link and give the website the `https://` / `wss://` URLs.
Leave `[shard] bind` on `127.0.0.1:7788`. That socket accepts *inbound commands to the
**Leave the sidecar's game-facing socket on loopback.** It accepts *inbound commands to the
game*, and being loopback-only is what makes that safe.
Next: [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) — because a

View File

@@ -6,12 +6,19 @@ description: Everything game-specific is a module. Installing one, what it adds,
import platform from '../../../../data/platform.json';
import { Aside, Steps } from '@astrojs/starlight/components';
Core knows nothing about any game. Every game-specific screen — shard status, the map
atlas, the player marketplace, character sheets — comes from a **module**, a directory on a
mounted volume that the server loads at start.
Core knows nothing about any game. Every game-specific screen — a game server's live
status, its map, its leaderboards, its players' characters — comes from a **game module**, a
directory on a mounted volume that the server loads at start.
Today there is one: **`uo`**, for ServUO shards, published as
[`Module-uo`](https://gitea.whitlocktech.com/RunicGateway/Module-uo) ({platform.releases['Module-uo']}).
There are two, both built inside this project, and a site runs **one** of them:
| Game | Module | Latest release |
|---|---|---|
| **{platform.games.uo.name}** | [releases](https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases) | {platform.releases['Module-uo']} |
| **{platform.games.rust.name}** | [releases](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/releases) | {platform.releases['Module-Rust']} |
What each one adds is in its own group in the sidebar:
[Ultima Online](/docs/ultima-online/) and [Rust](/docs/rust/).
## Install it
@@ -22,9 +29,8 @@ Today there is one: **`uo`**, for ServUO shards, published as
2. **Paste the URL of a release's install manifest** into *Release install-manifest URL*
and press **Install**.
For the current `uo` release that is the `module-uo-<version>.json` asset on
[its releases page](https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases).
The site downloads the bundle, checks it against the `sha256` the manifest declares, and
Every module release carries one: a `.json` asset named after the module and its
version, on the releases page linked above. The site downloads the bundle, checks it against the `sha256` the manifest declares, and
unpacks it onto the modules volume.
There is no catalog to browse, deliberately: a catalog would make core's release cadence
@@ -50,28 +56,21 @@ must be in the allowlist at the bottom of the same screen — re-checked on ever
It is seeded with `gitea.whitlocktech.com`, and an empty list forbids every install.
</Aside>
## What the `uo` module adds
## What a module adds
Watch the log at the restart and you will see exactly what it mounted:
Watch the log at the restart and you will see exactly what it mounted: its routes, its
database schema, and the line that says it started. Its screens appear in the navigation,
and its admin screens in the admin sidebar.
```
[uo] registered routes: public:/shard,/atlas admin:/shard,/uo-link player:/shard
[modules] schema ensured for module "uo"
[modules] module "uo" started
```
Its capabilities are {platform.games.uo.module.capabilities.join(', ')} — the shard console, the
map atlas, the player-vendor marketplace, city governors, guilds, houses and IDOCs, champion
boards, and the cliloc strings that make item names readable.
A module owns **one path segment** wherever it appears, so its pages live under `/uo/…`,
`/admin/uo/…` and `/player/uo/…`. That boundary is visible in the URL on purpose.
A module owns **one path segment** wherever it appears, so a module with the id `<id>` has
its pages under `/<id>/…`, `/admin/<id>/…` and `/player/<id>/…`. That boundary is visible
in the URL on purpose.
<Aside type="caution" title="A module with no game server behind it is empty, not broken">
Installing `uo` does not connect anything. Its screens exist and report the shard as
Installing a module does not connect anything. Its screens exist and report the game as
offline until you
[connect a game server](/docs/getting-started/connect-a-game-server/) — which is the same
thing the public site does when the shard goes down, and is designed to be unremarkable.
[connect your game server](/docs/getting-started/connect-a-game-server/) — which is the same
thing the public site does when the game goes down, and is designed to be unremarkable.
</Aside>
## The declarative alternative

View File

@@ -93,7 +93,7 @@ it down. Docker Compose is the supervisor here, and this line is what makes it o
## Two variables worth reading twice
**`SECRET_ENC_KEY`** encrypts secrets at rest — OAuth client secrets, the Discord bot
token, the shard's auth token. In production the server **refuses to start** without it.
token, the game module's sidecar token. In production the server **refuses to start** without it.
Changing it later does not re-encrypt anything: what was stored under the old key can no
longer be read, and every stored secret has to be entered again.

View File

@@ -3,11 +3,10 @@ title: Requirements
description: What you need on the website host, and what you need on the game server host, before you begin.
---
import platform from '../../../../data/platform.json';
import { Aside } from '@astrojs/starlight/components';
Two hosts, two lists. They can be the same machine, but they are separate deployments and
have nothing in common except the four values you will paste between them.
have nothing in common except the few values you will paste between them.
## The website host
@@ -29,41 +28,28 @@ mounts and the reverse-proxy notes all read that way.
## The game server host
Only if you are connecting a game server. Today that means a ServUO shard, which is what
the [`uo` module](/docs/getting-started/install-a-game-module/) and the installer support.
Only if you are connecting a game server. Each game lists what its own host needs on its
connect page, because each game's server asks for different things. These hold for every
game:
| Requirement | Detail |
|---|---|
| **A working ServUO install** | It must currently boot and compile scripts cleanly. The installer deploys onto a healthy shard; it does not repair a broken one. |
| **ServUO {platform.games.uo.bundle.servuoMin}** *(patch tier only)* | The base install works on any reasonably current ServUO. The optional patch tier is written and tested against stock {platform.games.uo.bundle.servuoMin}; on any other version it is unsupported, and skipping it still leaves you with a working bridge. |
| **`libgdiplus`** *(Linux shard hosts only)* | Only needed for **artwork**. ServUO runs under Mono on Linux, and the library it decodes sprites with is a thin layer over this one — in the decode path, not merely the encode. Without it creature portraits and item pictures stay empty, and names and the spawn atlas are unaffected because neither touches a pixel. `sudo apt-get install libgdiplus`; `doctor` checks for it. **Windows hosts need nothing.** |
| **The shard stopped** | `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit. The installer refuses to deploy under a running shard. |
| **Administrator / root** | It writes into system directories and registers a service. |
| **Outbound HTTPS** | To fetch the bundle and its two artifacts. No Gitea account and no git client are needed. |
| **The sidecar on the same host as the shard** | The shard connects to `127.0.0.1:7788`. Splitting them is not supported — that loopback socket *is* the trust boundary for inbound commands. |
| **A working game server** | It must boot and load plugins cleanly before you start. The installer deploys onto a healthy server; it does not repair a broken one. |
| **Administrator / root** | The installer writes into system directories and registers a service. |
| **Outbound HTTPS** | To fetch the bundle and its artifacts. No Gitea account and no git client are needed. |
| **The sidecar on the same host as the game server** | The bridge plugin dials the sidecar over loopback. That loopback socket *is* the trust boundary for inbound commands to the game, so the two are never split across machines. |
<Aside type="note" title="You do not need to install a game client for this">
You already have one. A ServUO shard cannot boot without a UO client — it resolves one at
startup to read the world's own data — so the artwork, the animations and the name table
the site shows are already sitting on that host. The shard reads them there and hands the
results over the bridge; nothing is converted on a desktop and nothing is uploaded. See
[Client files](/docs/administration/client-files/).
</Aside>
<Aside type="caution" title="Back up before the shard install">
The overlay overwrites `Scripts/Scripts.csproj`, a stock file, and the optional patch tier
edits stock sources. A copy of `Scripts/` and `Config/` costs nothing and is the difference
between an experiment and a gamble. The installer keeps its own backups too — see
[Connect a game server](/docs/getting-started/connect-a-game-server/).
</Aside>
Then the game's own list: [Ultima Online](/docs/ultima-online/connect-a-servuo-shard/#what-the-shard-host-needs),
or [Rust](/docs/rust/install-the-bridge/#before-you-begin).
## What you do not need
- **A Gitea account.** Everything the installers fetch is a public release asset.
- **A build toolchain.** Not on either host. The site pulls images; the module arrives as a
verified tarball; the shard plugin is C# source that ServUO itself compiles at boot.
- **An inbound port on the game host** — for the *game*. The shard never listens for the
website. If the website runs on a different machine from the shard, the **sidecar** needs
to be reachable by the website, and that is the one hole you will open deliberately.
verified tarball; the bridge plugin is source that the game server compiles itself.
- **An inbound port on the game host** — for the *game*. The game server never listens for
the website. If the website runs on a different machine from the game server, the
**sidecar** needs to be reachable by the website, and that is the one hole you will open
deliberately.
Next: [Install the site](/docs/getting-started/install-the-site/).

View File

@@ -1,110 +1,53 @@
---
title: Verify the whole stack
description: Four checks, one per link in the chain, that distinguish "files copied" from "the bridge works".
description: Four checks, one per link in the chain, that distinguish "files copied" from "the bridge works" — the same four for every game.
---
import { Aside, Steps } from '@astrojs/starlight/components';
import { Aside } from '@astrojs/starlight/components';
A successful install is not a working bridge, and the failure is quiet in a specific way:
**ServUO shells out to `dotnet build`, prints the output, ignores the exit code, and
reloads the existing `Scripts.dll`.** A broken script build looks exactly like a clean boot.
A successful install is not a working bridge. Files can be in the right place and the game
server can boot cleanly while nothing reaches the site, and the site is *designed* to keep
working when the game is unreachable — so a broken bridge does not announce itself.
So verify each link in the chain, in order. Each check tells you which one to fix.
So verify each link in the chain, in order, starting at the game. Each check tells you which
link to fix.
<Steps>
| # | The link | What you check | What "working" means |
|---|---|---|---|
| 1 | **The bridge plugin loaded** | The game server's own console or log at boot | The plugin announces itself, with the sidecar address it will dial |
| 2 | **The game server reached the sidecar** | The bridge plugin's status command, on the game server | It reports itself connected, and is not dropping events |
| 3 | **The sidecar is healthy** | `curl -s http://127.0.0.1:<port>/health` on the game server's host. It needs no token | *plugin connected* is true. It is the one value in the whole sequence that distinguishes "files copied" from "the bridge works" |
| 4 | **The website is ingesting** | The game module's connection screen, under **Admin** | It reads connected, and live events start arriving within seconds |
1. **The plugin compiled — watch the boot output.**
The order is the same for every game. The commands and the screen names are not, so each
game has its own page with the exact steps:
Start your shard the way you always do. You want the build to succeed *and* the bridge
to announce itself:
- **Ultima Online:** [Verify the bridge](/docs/ultima-online/verify-the-bridge/)
- **Rust:** [Verify the bridge](/docs/rust/verify-the-bridge/)
```
Core: Compiling scripts...
Build succeeded.
[Bridge] enabled=True endpoint=127.0.0.1:7788 queueCap=10000 …
```
## Two responses that mean the same for every game
If you scrolled past it, force the question:
```bash
dotnet build Scripts/Scripts.csproj -c Release -p:Platform=x64 # must be 0 errors
```
2. **The shard is connected — ask it in game.**
As an administrator:
```
[bridge status
```
It reports `connected=True depth=0 sent=… dropped=0`. `connected=False` means the shard
cannot reach the sidecar. `dropped` climbing means the sidecar is wedged and the shard
is shedding events rather than stalling — which is what it is designed to do, and why a
broken bridge never freezes your game.
`[bridge reload` re-reads `Bridge.cfg` without a restart; `[bridge sweepnow` forces one
pass of every stream.
3. **The sidecar is healthy — ask it over HTTP.**
`/health` needs no auth, so it is safe to curl on the shard host:
```bash
curl -s http://127.0.0.1:8080/health
```
```json
{"status":"ok","protocol":4,"plugin_connected":true,"database":"ok","uptime":"2m"}
```
**`plugin_connected: true` is the one that matters.** It is the only value in this whole
sequence that distinguishes "files copied" from "the bridge works".
4. **The website is ingesting — look at the shard screen.**
On the site, open **Shard (uo-link)** (`/admin/uo/link`). The header should read
**Connected**, with *Shard link: up* and *WS ingest: online*, and the live feed at the
bottom should start showing events within seconds rather than sitting on
*Waiting for shard events…*.
Then check the public side: the shard status page should stop reporting the game as
offline.
</Steps>
## When one of them fails
| What you see | What it means |
| What the site logs | What it means |
|---|---|
| Shard boots clean, nothing reaches the site | The classic silent failure — a stale `Scripts.dll`. Run the `dotnet build` line above and read the errors. |
| `[bridge` is not a command | The plugin did not compile, or the bridge is disabled in `Bridge.cfg`. |
| `connected=False` | The sidecar is not listening on `127.0.0.1:7788`. Check the service, and that `[shard] bind` matches `Host`/`Port` in `Bridge.cfg`. |
| `/health` is fine locally, the site says offline | The website cannot reach port 8080 — bind address or firewall. The site is *designed* to render normally with the shard down, so this fails quietly. |
| The site logs `409` from the sidecar | Protocol mismatch. Set the Protocol field to what `/health` reports rather than guessing; the sidecar rejects rather than mis-parsing. |
| `401` from the sidecar | Wrong or missing token. Read the live one back with `uo-link-sidecar --print-config`; do not retype it from a screenshot. |
| `409` from the sidecar | Protocol mismatch. The sidecar and the game module disagree on a wire protocol, and the sidecar refuses rather than mis-parsing. Set the protocol to what `/health` reports, or update whichever side is behind. |
| `401` from the sidecar | Wrong or missing token. Read the live one back on the game server's host rather than retyping it from a screenshot. |
<Aside type="note" title="`runicgateway doctor` answers most of this in one command">
Run on the shard host, it checks the install record, the ServUO tree, every overlay file
hash, the patch tier, the sidecar, its service, `/health`, that the sidecar and overlay
agree on a protocol, and — on Linux — that the host can decode an image at all. Its output is the first thing anyone helping you will ask for. It
exits non-zero when a check failed, so a monitoring system can run it too.
</Aside>
<Aside type="note" title="A bridge can be green and still show no artwork">
Creature portraits and item pictures are a separate switch and a separate import, so a
perfectly healthy bridge shows a bestiary of text until somebody presses *Update* on
**Admin → Client files**. That is the expected first-run state, not a fault — see [Client
files](/docs/administration/client-files/).
Run on the game server's host, it checks the install record, the files it deployed, the
sidecar, its service, `/health`, and that the sidecar and the bridge plugin agree on a
protocol. Its output is the first thing anyone helping you will ask for. It exits non-zero
when a check failed, so a monitoring system can run it too.
</Aside>
## What "working" looks like a week later
- The public shard page shows live status, and the admin dashboard shows events arriving.
- `dropped` in `[bridge status` stays at zero. A climbing number means the sidecar is
wedged, not that the shard is unhealthy.
- `doctor` is still green after a shard update — that is what catches an overlay file
reverted by hand or by a ServUO upgrade.
- The game module's public pages show live status, and the admin dashboard shows events
arriving.
- The bridge plugin is not dropping events. A climbing drop count means the sidecar is
wedged, not that the game server is unhealthy: the plugin sheds events rather than
stalling the game, which is what it is designed to do.
- `doctor` is still green after a game server update. That is what catches a deployed file
that an update put back to stock.
You have finished the installation path. From here,
[Administration](/docs/administration/configuration/) covers running the site day to day.

View File

@@ -8,7 +8,7 @@ import platform from '../../../data/platform.json';
Runic Gateway puts a private game server's live state on a public website without ever
exposing the game to the internet.
The shard dials **out** to a small sidecar over loopback; the sidecar is the only
The game server dials **out** to a small sidecar over loopback; the sidecar is the only
network-facing component, and only the website's backend is allowed to talk to it. The
website degrades gracefully when the game is down, and sensitive events never reach the
public event stream.
@@ -49,8 +49,8 @@ Worth stating before anything else, because it is a real trap: a Runic Gateway i
two independent deployments.
1. **The site** is a Docker deployment — the website, a database, and a game module.
2. **The shard side** is the installer binary, run on the game server's host. It sets up
the plugin overlay and the sidecar, and it never contacts the website.
2. **The game server side** is the installer binary, run on the game server's host. It sets
up the bridge plugin and the sidecar, and it never contacts the website.
They meet at the values the installer prints, pasted into the game module's connection
screen, and at the game's wire protocol, which both sides check before they will pair.
@@ -69,12 +69,15 @@ you should expect to see before you move on:
2. [Install the site](/docs/getting-started/install-the-site/) — Docker Compose, pull-only
3. [First run](/docs/getting-started/first-run/) — the first admin, and maintenance → live
4. [Install a game module](/docs/getting-started/install-a-game-module/) — what makes the game screens exist
5. [Connect a game server](/docs/getting-started/connect-a-game-server/) — the installer, on the shard host
5. [Connect your game server](/docs/getting-started/connect-a-game-server/) — the installer, on the game server's host
6. [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) — proving it works, rather than assuming
Then **Administration** covers running it: configuration, branding, content, users,
authentication, Teams, scheduled events, moderation, notifications, modules, the shard
connection, upgrades, and what to do when something is wrong.
authentication, Teams, scheduled events, moderation, notifications, modules, upgrades, and
what to do when something is wrong.
Everything that belongs to one game has its own group at the end of the sidebar, after
**Reference**: [Ultima Online](/docs/ultima-online/) and [Rust](/docs/rust/).
## Where the truth lives

View File

@@ -50,7 +50,7 @@ Before any of them, the kit points at the [Rust dry
run](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust-dryrun.md)
— a complete module designed on paper for a second game, and the shortest honest picture of
the whole job. That module has since been built for real, as
[`Module-Rust`](https://gitea.whitlocktech.com/RunicGateway/Module-Rust), so the dry run now
[the Rust module](https://gitea.whitlocktech.com/RunicGateway/Module-Rust), so the dry run now
reads as the plan beside a finished result.
## The template is built, not just quoted
@@ -58,7 +58,7 @@ reads as the plan beside a finished result.
Chapters 1 and 2 quote `template/`, a real module that CI builds against a pinned core. The
code in those chapters is **a tree that is proved rather than prose that looks like one**.
Chapters 3 and 4 cite `uo-link` and `servuo-plugins` by file and identifier rather than by
Chapters 3 and 4 cite the Ultima Online sidecar and bridge plugin by file and identifier rather than by
line number, deliberately: those repositories move for their own reasons, and a line number
in a book is wrong the moment they do.
@@ -90,7 +90,7 @@ pin moves.
<Aside type="note" title="It has already earned its keep">
Writing the chapters against 1.6.0 found that core's inverted-slot fills named three of
`module-uo`'s slots **literally** — so the mechanism worked for that one module and silently
the first game module's slots **literally** — so the mechanism worked for that one module and silently
did nothing for any other game, producing an empty page with nothing logged.
That is exactly the class of defect a book written for an audience outside this org exists

View File

@@ -5,6 +5,7 @@ description: Every key in module.json, what the loader does with each, and why a
import { Aside } from '@astrojs/starlight/components';
import platform from '../../../../data/platform.json';
import GameExample from '../../../../components/GameExample.astro';
`module.json` sits at the root of your bundle. The loader reads it synchronously, before
anything else about your module runs.
@@ -15,12 +16,15 @@ module that boots and mysteriously does half its job.
## A complete manifest
A real one, the Ultima Online module's, with the values that change every release elided:
<GameExample game="uo">
```json
{
"id": "uo",
"name": "Ultima Online",
"version": "1.0.0",
"coreApi": "^1.0.0",
"version": "…",
"coreApi": "…",
"server": "server/index.js",
"client": { "entry": "client/dist/entry.js" },
"schema": "server/db/schema.sql",
@@ -31,9 +35,10 @@ module that boots and mysteriously does half its job.
"player": ["/shard"]
},
"extensions": ["admin.users.detail"],
"capabilities": ["shard", "atlas", "market"]
"capabilities": ["shard", "atlas", "market", "…"]
}
```
</GameExample>
## The keys
@@ -64,9 +69,10 @@ register exactly.
`mounts` governs your **server** routes. Your SPA pages are registered separately by the
client half, and *those* are namespaced under your module id.
That is why `module-uo` declares `admin: ["/shard", "/uo-link"]` while its admin screen
lives at `/admin/uo/link`. Two different mechanisms, and [the module
system](/docs/modules/the-module-system/) explains why the split is deliberate.
That is why the manifest above declares `admin` prefixes that are not its admin screens'
URLs: the first is where its API routes live, the second is where the SPA puts its pages. Two
different mechanisms, and [the module system](/docs/modules/the-module-system/) explains why
the split is deliberate.
</Aside>
## `capabilities` is for feature detection
@@ -92,7 +98,7 @@ Use a caret range against the oldest core you actually support and test against.
exactly buys nothing and strands you on the next additive release.
<Aside type="note" title="Not the same number as the protocol version">
`coreApi` versions the **website module contract**. `PROTOCOL_VERSION` versions the **shard
`coreApi` versions the **website module contract**. `PROTOCOL_VERSION` versions **a game's
wire** and says nothing about a website module. See [Protocol
versions](/docs/architecture/protocol-versions/).
</Aside>

View File

@@ -4,9 +4,10 @@ description: What a module is, why the platform is built this way, and the one r
---
import { Aside } from '@astrojs/starlight/components';
import GameExample from '../../../../components/GameExample.astro';
Runic Gateway's core knows nothing about any particular game. Everything that makes the
site a *Ultima Online* site — the shard status, the atlas, the market, the guild pages —
site one game's site — that game's live status, its map, its leaderboards, its own pages —
lives in a **module**, installed onto a running deployment.
This section is the builder's track. If you only want to install one, that is
@@ -69,21 +70,26 @@ worked around with a deeper import.
## The URL rule, and its one exception
**A module owns one path segment wherever it appears.** For a module with id `uo`:
**A module owns one path segment wherever it appears.** A module with the id `<id>` has its
public pages under `/<id>/…`, its admin pages under `/admin/<id>/…`, and its player pages
under `/player/<id>/…`.
**API routes are the exception, and keep their exact paths.** A surface that existed before
it moved into a module keeps the API path it always had. This is why the Android app and
the Discord bot needed no API changes at the cutover.
<GameExample game="uo">
| Surface | Path |
|---|---|
| Public pages | `/uo/shard`, `/uo/atlas`, `/uo/market` |
| Admin pages | `/admin/uo/link`, `/admin/uo/visibility` |
| Player pages | `/player/uo/…` |
**API routes are the exception, and keep their exact paths.** The shard admin API is still
`/api/v1/admin/shard/*`, not `/api/v1/admin/uo/shard/*`. This is why the Android app and
the Discord bot needed no API changes at the cutover.
| The shard admin API — the exception | `/api/v1/admin/shard/*`, not `/api/v1/admin/uo/shard/*` |
</GameExample>
<Aside type="caution" title="This distinction has already cost real time">
The installer printed `<site>/admin/shard` — the pre-module path — well after the screen
had moved to `/admin/uo/link`. It was not caught quickly because **the old path does not
The installer kept printing the first game's pre-module admin path well after the screen had
moved under the module's segment. It was not caught quickly because **the old path does not
404**: the SPA has no route for it, so it redirects to the dashboard and looks like it
worked.

View File

@@ -4,6 +4,7 @@ description: Where the normative specifications live — the documents that win
---
import { Aside } from '@astrojs/starlight/components';
import GameExample from '../../../../components/GameExample.astro';
import { canonicalDocs } from '../../../../data/reference.mjs';
Everything on this site is a **summary**. These are the documents it summarises, and where
@@ -14,15 +15,21 @@ A documentation site that quietly re-specifies a contract becomes a second sourc
and second sources of truth drift. Every page here links out for exactly this reason, and
this page is the index of what it links to.
One page is a deliberate exception: [RunicNPC's API](/docs/rust/runicnpc/api/) is carried in
full, because its readers are plugin authors outside this project. Its every signature and field
name is checked against `runicnpc/API.md` on every build, and that document still wins.
If you find a disagreement, it is worth reporting — it means a check is missing.
</Aside>
## The documents
The platform's own, which every deployment shares:
<table>
<thead><tr><th>Document</th><th>Answers</th></tr></thead>
<tbody>
{Object.entries(canonicalDocs).map(([docPath, why]) => (
{Object.entries(canonicalDocs.core).map(([docPath, why]) => (
<tr key={docPath}>
<td>
<a href={`https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/${docPath}`}>
@@ -35,6 +42,44 @@ If you find a disagreement, it is worth reporting — it means a check is missin
</tbody>
</table>
And each game's, which only matter if you run that game:
<GameExample game="uo">
<table>
<thead><tr><th>Document</th><th>Answers</th></tr></thead>
<tbody>
{Object.entries(canonicalDocs.uo).map(([docPath, why]) => (
<tr key={docPath}>
<td>
<a href={`https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/${docPath}`}>
<code>{docPath}</code>
</a>
</td>
<td>{why}</td>
</tr>
))}
</tbody>
</table>
</GameExample>
<GameExample game="rust">
<table>
<thead><tr><th>Document</th><th>Answers</th></tr></thead>
<tbody>
{Object.entries(canonicalDocs.rust).map(([docPath, why]) => (
<tr key={docPath}>
<td>
<a href={`https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/${docPath}`}>
<code>{docPath}</code>
</a>
</td>
<td>{why}</td>
</tr>
))}
</tbody>
</table>
</GameExample>
Every path above is checked to still exist on every build, so a document that is renamed or
moved turns this page red rather than leaving a dead link.
@@ -45,14 +90,14 @@ moved turns this page red rather than leaving a dead link.
- **"Why is the module system like this?"** → `MODULE_SYSTEM.md`.
- **"What does this API return?"** → your own deployment's `/api/docs`, then
`BACKEND_DESIGN.md` §4.
- **"What can the shard send?"** → `link/PLAN.md` §5, and `v8.md` for the current
protocol — which is also where the asset plane is specified.
- **"What can a game server send?"** → that game's protocol document, in its table above.
- **"What may a scheduled event do to the world?"** → `website/EVENTS.md` for the model,
`MODULE_API.md` for the verbs a module may declare, and `link/ADMIN_CONTROLS.md` for what
the site may ask a game to do at all.
- **"Who may see this?"** → `SHARD_VISIBILITY.md` for the administrator's view,
`modules/uo/API.md` §4 for the specification.
- **"How do I set a shard up?"** → `installer/INSTALL.md`.
- **"Who may see this?"** → core's roles in `BACKEND_DESIGN.md`; a game's own audience
rules are in that game's module documents.
- **"How do I set a game server up?"** → `installer/INSTALL.md`, and that game's install
guide.
## Where they live

View File

@@ -35,7 +35,7 @@ The first boot is also when your admin account is written, so `ADMIN_USERNAME` a
## The three worth reading twice
**`SECRET_ENC_KEY`** encrypts secrets at rest — OAuth client secrets, the Discord bot token,
the shard's auth token. Changing it does **not** re-encrypt anything: what was stored under
the game module's sidecar token. Changing it does **not** re-encrypt anything: what was stored under
the old key can no longer be read, and every stored secret has to be entered again.
**`COOKIE_SECURE=auto`** decides `Secure` per request, which is what lets one deployment
@@ -53,7 +53,7 @@ a complete `.env` alongside its Compose file. Afterwards,
[Configuration](/docs/administration/configuration/) covers what is env-configured and what
is not.
**Most settings are not here.** Branding, navigation, theming and the shard connection are
**Most settings are not here.** Branding, navigation, theming and the game connection are
**admin-managed and live in the database**, deliberately — so changing them does not mean
redeploying a container.

View File

@@ -60,8 +60,9 @@ loses access immediately rather than at token expiry.
## The sidecar's API is a different thing
The uo-link sidecar exposes its own small REST and WebSocket surface, reached **only** by the
website's backend. It carries `X-UOLink-Version` and answers `409` on a protocol mismatch.
Each game's sidecar exposes its own small REST and WebSocket surface, reached **only** by the
website's backend. It carries its protocol version in a header and answers `409` on a
protocol mismatch.
It is not part of this API and is not served from your site. See [The
bridge](/docs/architecture/the-bridge/).

View File

@@ -4,13 +4,14 @@ description: The four commands the installer offers, what each does to a host, a
---
import { Aside } from '@astrojs/starlight/components';
import GameExample from '../../../../components/GameExample.astro';
import { installerCommands } from '../../../../data/reference.mjs';
The installer is one binary per operating system that deploys the **shard side only**. It
never contacts the website.
The installer is one binary per operating system that deploys the **game server side
only**: the bridge plugin, and the sidecar with its service. It never contacts the website.
Downloads and the walkthrough are [Connect a game
server](/docs/getting-started/connect-a-game-server/). This page is the command surface.
The walkthrough is [Connect your game server](/docs/getting-started/connect-a-game-server/),
which hands off to each game's steps. This page is the command surface.
## The commands
@@ -25,47 +26,67 @@ server](/docs/getting-started/connect-a-game-server/). This page is the command
`doctor`, `update` and `uninstall` are the day-two commands.
## Telling it which game
One binary serves both games. A flag says which one a run is about, and each game has flags
of its own:
<GameExample game="uo">
```bash
runicgateway-installer install --game servuo --servuo /path/to/ServUO
```
`--game servuo` is the default, so a ServUO run can leave it out.
</GameExample>
<GameExample game="rust">
```bash
runicgateway-installer install --game rust --rust /srv/rust --server-id main
```
One sidecar serves one Rust server, so `--server-id` is required on install. The Rust flags
are refused on a run that is not `--game rust`, rather than silently ignored. The whole Rust
install, including a Pterodactyl egg for hosts the installer cannot run on, is in
[its group](/docs/rust/install-the-bridge/).
</GameExample>
## Rehearsing a run
Two mechanisms, and they answer different questions.
```bash
runicgateway-installer install --servuo /path/to/ServUO --verify
```
**`--verify` writes nothing.** It reports what would change — the diff against the ServUO
tree — which is the right thing to run first against a shard that has players on it.
```bash
RUNICGATEWAY_STATE_DIR=/tmp/rehearsal runicgateway-installer install --servuo …
```
**`--verify` writes nothing.** On `install` and `update` it reports every change the run
would make and stops, which is the right thing to run first against a game server that has
players on it.
**`RUNICGATEWAY_STATE_DIR` relocates everything the installer writes** — state, data, and
the sidecar binary — *and suppresses service registration*. That is how a full run is
exercised without root, and it is what the project's own tests use.
```bash
RUNICGATEWAY_STATE_DIR=/tmp/rehearsal runicgateway-installer install …
```
## What an install actually does
1. Resolves a **bundle** — an exact, protocol-checked sidecar and overlay pair published by
CI. Never "latest of each"; see [Protocol
1. Resolves a **bundle** — an exact, protocol-checked pair of sidecar and bridge plugin
published by CI. Never "latest of each"; see [Protocol
versions](/docs/architecture/protocol-versions/).
2. Syncs the plugin overlay into the ServUO tree, backing up whatever it is about to
2. Deploys the bridge plugin onto the game server, backing up whatever it is about to
overwrite.
3. Offers the opt-in patch tier.
4. Installs the sidecar and registers its service.
5. Prints four values to paste into the site's shard screen.
3. Installs the sidecar and registers its service.
4. Records what it deployed, with per-file hashes, so `doctor` can tell later whether
anything changed.
5. Prints the values to paste into the game module's admin screen on the site.
<Aside type="caution" title="Installer v0.1.0 prints an older path in step 5">
It names `<site>/admin/shard`. The screen moved to **`/admin/uo/link`** when the shard
surface became part of the `uo` module. Fixed in v0.1.1.
</Aside>
Each game adds its own steps: the Ultima Online install, for one, offers an optional patch
tier, covered in [its group](/docs/ultima-online/connect-a-servuo-shard/).
## Platforms
Linux `x86_64`, Linux `aarch64`, and Windows `x86_64`.
**macOS and Windows-on-ARM are deliberately absent**: the game server and the sidecar must
share a host, and no ServUO host is either.
share a host, and no game server the platform supports runs on either.
Releases are **unsigned**, and `SHA256SUMS` is the trust anchor — verify before running.
Windows will show a SmartScreen prompt, which is expected for an unsigned binary.

View File

@@ -0,0 +1,108 @@
---
title: Connect the site
description: Adding a Rust server to the site on Admin → Rust servers, what the Test button's answers mean, and the rest of a server's settings — its wipe schedule, world-event credit and chat titles.
---
import { Aside } from '@astrojs/starlight/components';
Every Rust server the site follows is one row on **Admin → Rust servers**
(`/admin/rust/servers`). A row tells the site where that server's sidecar is; the sidecar
itself lives on the game host, put there by [Install the bridge](/docs/rust/install-the-bridge/).
## Add a server
Press **Add a server** and fill in four values:
| Field | Value |
|---|---|
| **Id** | The server id — the installer's `--server-id`, or the egg's variable. It must equal `ServerId` in the plugin's config |
| **Name** | Anything. Players see it |
| **Sidecar address** | The sidecar URL the installer or the console printed, such as `http://10.0.0.5:8090` |
| **Sidecar token** | The token, from the sidecar's own config |
**The id is permanent.** It is in every link to the server and the site will not change it
later. It is deliberately not the hostname: you will rename a server for a season, and its
history must not go with the name. Changing the plugin's `ServerId` after the site has seen it
strands everything recorded under the old one.
**The token is write-only.** It is stored encrypted and never shown again once saved; the row
says only *token stored*. Saving the form with the field blank keeps the stored token, so
renaming a server does not mean re-pasting a credential.
## Test it
**Test the sidecar** asks the sidecar for its health and reports what came back. A working
server answers *The sidecar answered (protocol N)*, and its row reads online, with its
player count, the protocol and *last seen just now*. *The sidecar answered, but the game's
plugin is not connected to it* means the site's half works and the game's does not — go to
[Verify the bridge](/docs/rust/verify-the-bridge/).
A wrong address, a wrong token and a mismatched protocol all look the same from the public
site — *the server is offline* — so the Test button is what tells them apart. A failure reads
*The sidecar did not answer:* followed by one of these:
| Status | What is wrong | Where to look |
|---|---|---|
| `no-token` | The form was saved without one | This screen |
| `unauthorized` | The token does not match | The sidecar's config on the game host |
| `protocol-mismatch` | The sidecar and the module speak different protocols | Update whichever is behind |
| `timeout` | The sidecar answered too slowly, or not at all | The sidecar's own log |
| `transport-error` | Nothing is listening at that address | The address, the firewall, whether the sidecar runs |
| `http-<code>` | Something answered, and it was not a sidecar | Usually a reverse proxy in front of the wrong thing |
Within a poll interval the server appears at `/rust`.
## If the site is on another machine
The installer's sidecar listens on `127.0.0.1`, reachable only from the game host. Put a TLS
reverse proxy or a VPN link in front of it and give the site that URL — the token is a plain
bearer token, and the sidecar speaks HTTP. The egg's sidecar listens on its allocation, which
the network can reach, so firewall it to your site's address.
<Aside type="caution" title="Leave the game bind on loopback">
The sidecar's other socket, the one the bridge plugin dials, takes commands for the game
server and has no token. Being loopback-only is what makes that safe. Only the web bind ever
moves.
</Aside>
## The rest of a server's settings
**Edit** on a row opens the same form, plus:
- **Enabled** and **Order** — whether the site follows the server, and where it sits in the
list.
- **Wipe schedule.** *No schedule*, *Forced wipe only* (Facepunch's monthly forced wipe, the
first Thursday of the month at 19:00 UK time), *Weekly* or *Every other week*, on a day,
time and time zone you choose. A **one-off wipe** covers a delayed or extra one. It is a
forecast: the next wipe shows on the server's public page. The wipe itself is whatever the
game reports, which is what splits the leaderboard and the history.
- **Who downs a helicopter or a Bradley.** *Killing blow* (the default), *Last hit*, *Most
damage*, or *Everyone who hurt it*. It decides whose name the feed shows and who it counts
for, from the moment you save.
**Optional mods** on a row lists what the bridge found on that server — BetterChat,
PopupNotifications, Economics, Backpacks, TruePVE, Dynamic PVP, Dangerous Treasures, Guarded
Crate, ZLevels, RaidableBases — with each one's version and what it lets the site do there.
[Optional plugins](/docs/rust/optional-plugins/) explains each.
### Chat titles
**Chat titles** on a row gives titles to the top players of the current wipe, one rule per
stat: *the top 1 by guarded crates cleared earns "Warden"*. Up to ten rules a server; a stat
of zero earns nothing, so a fresh wipe has no titles until somebody plays. Titles show beside
the name on the leaderboard, and in game chat where BetterChat is installed.
Below the servers, **Category titles** sets each stat's default title once for every server,
and **Announcement voice** lets news posts and event announcements said in game chat wear the
title and colours of one permission group that has a chat style. That style is set on the
group, in [Permissions and groups](/docs/rust/permissions-and-groups/#chat-styles).
Next: [Verify the bridge](/docs/rust/verify-the-bridge/).
## Canonical documents
[`rust-link/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INSTALL.md#connect-the-website)
and [`rust-link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INTEGRATION.md)
§3 hold the connection and the Test button's answers;
[`modules/rust/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/PLAN.md)
is the module's design of record.

View File

@@ -0,0 +1,106 @@
---
title: Event kinds
description: Every kind of event a Rust server can tell the site, in three classes — public, presence and staff — and why the module, not the game, decides which is which.
---
import { Aside } from '@astrojs/starlight/components';
import platform from '../../../../data/platform.json';
import { rustEventKinds } from '../../../../data/reference.mjs';
What a Rust server tells the site, unprompted, as things happen in the world — every kind the
bridge sends through protocol {platform.games.rust.protocol}, and who may see each.
**Not to be confused with a scheduled event.** That is a thing you put on the calendar and run —
see [Events, zones and rewards](/docs/rust/events-zones-and-rewards/). The two meet: what happens
here is what a phase can wait for.
The exact wire shapes are in the protocol specification and are **not** restated here. This page
is the map and the security model.
## The module decides, not the game
The wire carries no visibility field. **A boundary is enforced by the side that serves, never
declared by the side that sends**: a field the game stamped on each frame would be a boundary that
a compromised — or merely out-of-date — game host could widen. So the Rust module holds the lists
below, and they are **default-deny**: a kind it has never heard of, from a newer bridge, is not
public until somebody classifies it.
These three lists are checked against the module's own on every build. A kind moved between
classes upstream turns this page red.
## Public
Anybody may see these. Some are filtered field by field for each viewer — a world event's player
name only for the presence audience, a Steam id and a position only for staff — but the kind
itself is public.
<table>
<thead><tr><th>Kind</th><th>What it says</th></tr></thead>
<tbody>
{Object.entries(rustEventKinds.public).map(([kind, what]) => (
<tr key={kind}><td><code>{kind}</code></td><td>{what}</td></tr>
))}
</tbody>
</table>
## Presence
Public kinds that say a **named** player was on the server at a given moment. Their audience is an
operator's choice on [Who sees who is online](/docs/rust/who-sees-who-is-online/), and it is **staff
only** until somebody widens it.
<table>
<thead><tr><th>Kind</th><th>What it says</th></tr></thead>
<tbody>
{Object.entries(rustEventKinds.presence).map(([kind, what]) => (
<tr key={kind}><td><code>{kind}</code></td><td>{what}</td></tr>
))}
</tbody>
</table>
`player.death` and `player.chat` are here on purpose. They are the kill feed and the chat — the
content a feed exists for — and each says *this person was on at 12:03* as plainly as a connect
does.
<Aside type="note" title="Gathering is counted, not sent">
A tree is hit hundreds of times a minute. One frame per swing would make the bridge the most
expensive thing on the server, so the plugin keeps a per-player tally and sends `player.tally`
once a minute, on disconnect and at shutdown. The leaderboard is exact and the wire is quiet. The
rule behind it: if a hook can fire more than once a second per player, it is a counter, not an
event.
</Aside>
## Staff
Admins and moderators, and nobody else, at any setting.
<table>
<thead><tr><th>Kind</th><th>What it says</th></tr></thead>
<tbody>
{Object.entries(rustEventKinds.staff).map(([kind, what]) => (
<tr key={kind}><td><code>{kind}</code></td><td>{what}</td></tr>
))}
</tbody>
</table>
Bans, unbans, login attempts and approvals carry **IP addresses**, and `player.reported` carries the text of one player's
complaint about another. They are stored because an operator chasing ban evasion needs them; they
reach no page below admin, and the sidecar's raw history that holds them is bounded by
`retain_days` in [`sidecar.toml`](/docs/rust/sidecar-toml/).
Clan membership changes are staff kinds on the server's feed, but not hidden from the clan: they
reach a clan's own members through its [Team](/docs/administration/teams/) feed, where core decides
who is a member.
## Every frame says when and where
Every frame carries the server's id and the **wipe** it happened in — derived by the plugin from
the save's creation time, absent on a server that has never saved. A wipe splits a server's history
rather than ending it, which is how the leaderboard is per wipe while a player's totals survive.
## Canonical documents
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§8 defines the catalogue and every later section adds to it;
[`server/catalogue.js`](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/src/branch/main/server/catalogue.js)
in the module is the classification this page is checked against.

View File

@@ -0,0 +1,104 @@
---
title: Events, zones and rewards
description: What the Rust module adds to core's scheduled events — its steps, the values an event may borrow, zone presets, and the switch on each server that has to be on first.
---
import { Aside } from '@astrojs/starlight/components';
An event is core's: phases, steps, a schedule, a dry run, and a record of what happened — see
[Scheduled events](/docs/administration/events/). This page is what the Rust module puts into
that editor, and what a Rust server needs before any of it can run.
## First, switch it on
Each server's bridge plugin has **`EventsEnabled`**, and it is **off** until you turn it on —
in [`RunicGateway.json`](/docs/rust/runicgateway-json/), from
[Mod config](/docs/rust/mod-config/) or on the host. It gates everything an event writes: a
borrowed value, a zone, a crate, an NPC, a tally, a line in chat.
Letting staff moderate from a screen they are looking at and letting a schedule change the world
at four in the morning are different consents, so this is its own switch. Turning it off never
strands anything: giving back what an event took, and cleaning up what it placed, always work.
<Aside type="note" title="A server's own ceilings">
The same file holds how much one step may do on that server — crates, NPCs, people rewarded,
tallies at once, the length of a chat line, world events called. **A step over a bound is
refused, never trimmed to fit.** An operator may lower each bound; none can be raised past the
plugin's own ceiling.
</Aside>
## The steps
Picked from the step's **Action** list, beside core's own:
| Group | Step | What it does |
|---|---|---|
| **The world** | Open a zone | A ZoneManager zone, at a monument or coordinates, with flags from a [preset](#zone-presets), messages on entering and leaving, and optionally a dome |
| | Place crates | Crates, barrels and supply drops |
| | Place NPCs | Rust's scientists and guards, or [RunicNPC profiles](/docs/rust/runicnpc/npc-profiles/) — placed through RunicNPC |
| | Call a world event | Rust's own: a patrol helicopter, an airdrop, the cargo ship, a Bradley, the Travelling Vendor and the rest |
| **Counting** | Start counting participants | A tally of who is present in a zone or on the server, by seconds present, kills, or both |
| | Record participants | Reads the tally into the run, so later steps can reward from it |
| **Rewards** | Reward a kit | A Kits kit, as a credit the player redeems |
| | Pay coins | Economics coins |
| | Bigger backpack | Lends a larger Backpacks size until the event ends |
| | Permissions until the event ends | Lent, and taken back at the end |
| | Permissions for good | Given, and kept. Needs a tick saying you are sure |
| | Reward by console command | Commands run once per recipient, with `{steamid}` and `{name}` filled in |
| **Saying it** | Say it in game chat | A line in chat, or a popup where PopupNotifications is installed |
| **Optional plugins** | Start a Dangerous Treasures event | |
| | Place a guarded crate | |
| | Spawn a raid base | A RaidableBases base that is the event's own |
| **Anything else** | Run console commands | Free text, as typed at the server console, with commands to run when the event ends. Needs a tick saying you are sure |
The optional-plugin steps need their plugin on the server; [Optional
plugins](/docs/rust/optional-plugins/) covers each. Every reward step picks its recipients the same
way: everyone who scored, the top N, a minimum score, N drawn at random, the top X per cent — or
every player with a [linked Steam account](/docs/rust/linking-steam-accounts/), with no tally at
all, for something like a kit weekend. A recipient need not be linked otherwise: rewards go to
Steam accounts, and one who is offline gets theirs on their next time in.
**What an event places is the event's.** At its end, the run gives back what it borrowed and
removes what it placed — its zones, crates, NPCs, and a raid base it spawned. A server restart in
the middle does not lose track: the plugin keeps the registry on disk, and something that outlives
its deadline is removed and recorded as *expired*.
## Values an event may borrow
Core's **Borrow a value** step holds a setting for the length of the event and gives it back at
the end. Rust lends four kinds of value, on each server:
- **Decay rate**
- **Population** — an animal or vehicle population
- **Spawn scalar**
- **Group permission** — a permission on a group, which the [permission
mirror](/docs/rust/permissions-and-groups/) leaves alone while the lease holds
## Zone presets
**Admin → Rust zone presets** (`/admin/rust/zones`) holds named sets of ZoneManager flags and
settings. Core's step editor has single-value fields, so a zone's flags are ticked here, and an
event's *Open a zone* step offers the presets in its **Options** field. Picking one **copies** it
into the step, so changing a preset later does not change an event already published.
The screen lists each server's ZoneManager version, how many flags it has, and whether domes are
available. None ship with the module: what an arena is differs by server. Who is exempt from a
flag is a `zonemanager.ignoreflag.*` permission, set on the permissions page. Where TruePVE is
installed, a zone can also turn PvP protection off inside it, or name a TruePVE ruleset.
## Triggers
A phase can advance when something happens in the game, and the vocabulary of *something* is
the module's trigger catalog. Rust's includes a server wiping, coming online or going offline, a
new kills leader, a raided base, a guarded crate landing or being cleared, a treasure event
starting or being won, and a RunicNPC boss appearing, changing phase or dying. The same catalog
drives [Engagement rules](/docs/administration/engagement-rules/).
## Canonical documents
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§14 to §16 and §20 are leases, world verbs, rewards and the step editor on the wire;
[`website/EVENTS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md)
is core's event system, and
[`modules/rust/PLAN_REDESIGNS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/PLAN_REDESIGNS.md)
the design of the step editor and the zones.

View File

@@ -0,0 +1,102 @@
---
title: The Rust module
description: What the rust module adds to a site, the pieces that connect it to a Rust server running Oxide or Carbon, and where each page in this group fits.
---
import platform from '../../../../data/platform.json';
The `rust` module turns a Runic Gateway site into a *Rust* community's site. It follows any
number of Rust servers, each running **Oxide** or **Carbon**. Everything in this group is
specific to it; the rest of the documentation is core, and describes the platform in core's
own words.
## The pieces
| Piece | What it is | Release |
|---|---|---|
| **The module** | [`Module-Rust`](https://gitea.whitlocktech.com/RunicGateway/Module-Rust) — every Rust screen on the site | {platform.releases['Module-Rust']} |
| **The sidecar** | [`Rust-Link`](https://gitea.whitlocktech.com/RunicGateway/Rust-Link), the **rust-link sidecar** — the only part of the bridge that listens on a network | {platform.games.rust.bundle.sidecar} |
| **The bridge plugin** | [`Rust-Plugins`](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins) — `RunicGateway.cs`, one file that runs unchanged on Oxide and Carbon, plus its optional helpers | {platform.games.rust.bundle.plugin} |
| **RunicNPC** | [`runicnpc-rust`](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust) — our NPC plugin, which the bridge drives for every NPC an event places. **Required** | {platform.games.rust.bundle.runicnpc} |
The sidecar, the bridge plugin and RunicNPC are installed together on the game host as a
**bundle** — {platform.games.rust.bundle.tag} today, speaking protocol
{platform.games.rust.protocol}. A bundle is an exact set CI has checked, never "the latest of
each". **One sidecar serves one Rust server**: a community running six servers runs six
sidecars, each with its own port, database and token, and the site holds six rows.
The bundle needs Oxide {platform.games.rust.bundle.oxideMin} or Carbon
{platform.games.rust.bundle.carbonMin} or newer, and the uMod plugins
{platform.games.rust.bundle.requiresPlugins.join(' and ')}. RunicNPC will not load without
Kits, so a server without it cannot place NPCs in an event.
## What the module adds
Install it from **Admin → Modules** like any module — the install manifest is the
`module-rust-<version>.json` asset on
[its releases page](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/releases). It
needs Module API {platform.games.rust.module.coreApi}.
**For visitors**, at `/rust`: every server as it last reported itself, and a page per server
with six tabs.
| Tab | What it shows |
|---|---|
| **Feed** | Kills, chat, comings and goings, the server's own story, RunicNPC bosses, and Rust's world events — cargo, helicopters, airdrops — as they happen. A signed-in member can report a chat line, hide it for themself or block the player from its `⋯` menu, and staff can hide a line for everyone ([Moderation](/docs/administration/moderation/)) |
| **Leaderboard** | Per wipe: kills, deaths, NPC kills, structures, time played, and the chat titles players have earned |
| **Online** | Who is on right now |
| **Map** | The [live map](/docs/rust/the-live-map/): the server's own map picture, with layers |
| **Wipes** | Every wipe the site has seen. The next one, once the server has a wipe schedule, is in the page's header |
| **Clans** | Each clan's name, colour, score and members |
A server's **clans are the site's [Teams](/docs/administration/teams/)**, so a clan gets a
page, a feed for its members, and core's Team notifications. Who may see a clan's roster —
and who may see a named player at all — is an operator's choice, set on
[Who sees who is online](/docs/rust/who-sees-who-is-online/).
**For players**, at `/player/rust`: linking a Steam account, what they can do in game, their
NPC kills, coins and backpack. See [Linking Steam accounts](/docs/rust/linking-steam-accounts/).
**For staff**, seven screens in the admin sidebar, each covered in this group:
| Sidebar row | Page here |
|---|---|
| Rust servers | [Connect the site](/docs/rust/connect-the-site/) |
| Rust permissions | [Permissions and groups](/docs/rust/permissions-and-groups/) |
| Rust mod config | [Mod config from the site](/docs/rust/mod-config/) |
| Rust visibility | [Who sees who is online](/docs/rust/who-sees-who-is-online/) |
| Rust zone presets | [Events, zones and rewards](/docs/rust/events-zones-and-rewards/) |
| Rust NPC profiles | [NPC profiles](/docs/rust/runicnpc/npc-profiles/), in the RunicNPC subgroup |
| Rust NPC placements | [NPC placements](/docs/rust/runicnpc/npc-placements/), in the RunicNPC subgroup |
The module also adds a **Rust** section to each user's page under **Admin → Users** (their
linked Steam accounts, permissions, coins and backpack), Rust steps and triggers to core's
[Scheduled events](/docs/administration/events/), and Rust triggers to
[Engagement rules](/docs/administration/engagement-rules/) — *your base was raided*, *a server
wiped*, *a new kills leader* and more.
Its capabilities are {platform.games.rust.module.capabilities.join(', ')}.
Until a server is connected, its pages exist and report it as offline. That is the same
thing the public site does when a server goes down, and it is designed to be unremarkable:
every list, count and last-reported time comes from what the site stored.
## In this group
| Page | Read it when |
|---|---|
| [Install the bridge](/docs/rust/install-the-bridge/) | Setting a Rust server up: the installer, a Pterodactyl egg, or by hand |
| [Connect the site](/docs/rust/connect-the-site/) | Adding the server to the site, and the rest of its settings |
| [Verify the bridge](/docs/rust/verify-the-bridge/) | Proving the server, the sidecar and the site are really talking |
| [Linking Steam accounts](/docs/rust/linking-steam-accounts/) | Joining a player's Steam account to their site account |
| [Permissions and groups](/docs/rust/permissions-and-groups/) | Granting permissions and managing groups from the site |
| [Mod config from the site](/docs/rust/mod-config/) | Editing your plugins' config files without a file manager |
| [Who sees who is online](/docs/rust/who-sees-who-is-online/) | Deciding what the public sees: names, rosters, map layers |
| [Events, zones and rewards](/docs/rust/events-zones-and-rewards/) | Running scheduled events on a Rust server |
| [Optional plugins](/docs/rust/optional-plugins/) | What each supported uMod plugin adds, and two that catch operators out |
| [The live map](/docs/rust/the-live-map/) | What the map shows, and where the picture comes from |
| [Troubleshooting](/docs/rust/troubleshooting/) | Something on the game side is wrong |
| [sidecar.toml](/docs/rust/sidecar-toml/) | Changing the sidecar's binds, token, store or history |
| [RunicGateway.json](/docs/rust/runicgateway-json/) | Changing the bridge plugin's own settings and bounds |
| [Event kinds](/docs/rust/event-kinds/) | Knowing what the server can tell the site, and who may see each |
| [RunicNPC](/docs/rust/runicnpc/) | Our NPC plugin: placing NPCs, their profiles, and its API for other plugins — eight pages of its own |

View File

@@ -0,0 +1,161 @@
---
title: Install the bridge
description: Setting a Rust server up for the site — with the installer, from a Pterodactyl egg, or by hand — and what each puts where.
---
import { Aside } from '@astrojs/starlight/components';
import platform from '../../../../data/platform.json';
This happens on the machine that runs your Rust server. It puts three things there — the
bridge plugin, the sidecar and RunicNPC — from one bundle, {platform.games.rust.bundle.tag}
today, and prints what the site needs. It never contacts your site, and it never starts or
stops your game server.
```
Rust server ──loopback, dials out──► rust-link sidecar ──HTTP + WebSocket──► your site
```
The game server opens no port for the bridge: the plugin dials the sidecar on `127.0.0.1`.
## Before you begin
- **Oxide or Carbon is installed, and the server has started once with it**, so its
directories exist. A vanilla server has nothing to load a plugin with. Oxide
{platform.games.rust.bundle.oxideMin} or Carbon {platform.games.rust.bundle.carbonMin} or
newer — never both in one tree.
- **Kits and ZoneManager**, from uMod. The bridge runs without them and names what is missing,
but rewards and zones need them, and **RunicNPC will not load without Kits**. Nothing here
installs them.
- **The site has the Rust module**, and you are an administrator on it.
## Three ways, one result
| | Use it when |
|---|---|
| [**The installer**](#the-installer) | The server runs on Linux with systemd, or on Windows |
| [**The Pterodactyl egg**](#the-pterodactyl-egg) | The server runs on a Pterodactyl panel |
| [**By hand**](#by-hand) | Neither fits, or you want to place every file yourself |
## The installer
The [Runic Gateway installer](/docs/reference/installer-cli/), {platform.releases.installer},
told it is setting up Rust. Run it as root, or from an elevated PowerShell:
```bash
sudo ./runicgateway-installer-linux-x86_64 install --game rust --rust /srv/rust --server-id main
```
```powershell
.\runicgateway-installer-windows-x86_64.exe install --game rust --rust D:\rust --server-id main
```
`--rust` is the server root, the directory holding `RustDedicated`. **`--server-id` is
required**: it is the id the site will know this server by — lowercase letters, digits and
`-`, up to 64 — and it is permanent (see [Connect the site](/docs/rust/connect-the-site/)).
Add `--verify` to see everything it would do and write nothing.
A run resolves the bundle, detects Oxide or Carbon from the server itself, and refuses a tree
that has both or neither. It writes the plugin's config with just `ServerId` and `Port`,
**only if there is none** — an existing config is never rewritten, and one that names a
different server stops the run. It installs the sidecar and registers its service, places the
plugin, its helpers and RunicNPC, and prints what the site needs. Both frameworks load a
plugin the moment it lands, so on a running server the bridge comes up at once.
**More than one server on a host:** run it once per server, each with its own `--rust` and
`--server-id`. Each gets its own service, config, database, game port (from 7799) and web
port (from 8090), and they share one sidecar binary.
| | Linux | Windows |
|---|---|---|
| The sidecar binary, shared | `/usr/bin/runicgateway-rust-link` | `%ProgramFiles%\RunicGateway\rust-link-sidecar.exe` |
| One server's sidecar config — **holds its token** | `/etc/runicgateway/rust/<id>.toml`, mode 600 | `%ProgramData%\RunicGateway\rust\<id>\sidecar.toml` |
| One server's service | `runicgateway-rust@<id>.service` | `RunicGatewayRust-<id>` |
The full list, including the database and the install record, is in the
[Rust bridge install guide](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INSTALL.md#where-everything-lands).
## The Pterodactyl egg
Each Rust-Link release carries **`egg-rust-runicgateway.json`**: the panel's *Rust Autowipe*
egg with the bridge added. A panel administrator imports it under **Admin → Nests → Import
Egg**. When you create a server from it, these variables matter:
| Variable | |
|---|---|
| **Modding Framework** | `oxide` or `carbon`. `vanilla` installs no bridge |
| **Runic Gateway: server id** | The id on the site. Read **once**, when the plugin writes its first config; changing it later changes nothing |
| **Runic Gateway: sidecar port** | **One of this server's allocations.** A port the server was not allocated binds, but is never reachable |
| **Runic Gateway: sidecar token** | Leave blank, and the sidecar generates one. Anyone who can see this server's startup variables can read a token typed here |
| **Runic Gateway: bundle** | Blank takes the current bundle; a tag pins one |
The install checks every file against the bundle's checksums before it places any of them.
The **first boot** prints the generated token in the console, **once**, and a line with what
the site needs:
```
[rust-link] Admin -> Rust -> Servers: server id 'main', sidecar URL http://<this node's address>:21009 (listening on 0.0.0.0:21009)
```
The sidecar runs inside the server's container and stops with it.
- **Updating is a reinstall**, with *Regen Server* off to keep the map. A restart never
fetches anything, so it can never change the protocol under a site that has not been
updated.
- **A wipe keeps the bridge's history.** The egg moves `rust-link/` out of the way while
`REMOVE_FILES` runs, so no delete list can reach the database or the token.
## By hand
1. **Pick the bundle.** The current one is
[`v2/rust/current.json`](https://gitea.whitlocktech.com/RunicGateway/installer/src/branch/bundles/v2/rust/current.json)
on the installer's `bundles` branch. It names the sidecar for your platform, the plugin
tarball and RunicNPC's, each with a `sha256`.
2. **Download and verify** each against its checksum.
3. **The plugin:** copy `RunicGateway.cs` into `oxide/plugins/` or `carbon/plugins/`, with
every other `.cs` the tarball's `manifest.json` lists beside it, and `RunicNPC.cs` from
its own tarball. To name the server, create `oxide/config/RunicGateway.json` (Carbon:
`carbon/configs/RunicGateway.json`) first, holding `{ "ServerId": "<id>", "Port": 7799 }`.
Without it the plugin calls the server `main`.
4. **The sidecar:** put the binary somewhere stable, give it a
[`sidecar.toml`](/docs/rust/sidecar-toml/), and run
`rust-link-sidecar --print-config --config <file>` once — it generates the token, saves
it, and prints it.
5. **Run it** under your supervisor with `--config <file>`, as an unprivileged user that can
write the database directory. On Windows the same `.exe` runs as a service.
<Aside type="caution" title="Do not create RunicNPC's data folder yourself">
RunicNPC makes `data/RunicNPC/` on its first load. One made from outside the game — a panel's
file manager, say — may not be writable by it.
</Aside>
## The helpers beside the plugin
The bundle ships three optional helpers beside the plugin, and the installer and the egg
place all three. By hand, the tarball's `manifest.json` lists them in `files`:
- **`RunicGatewayZones.cs`** lets ZoneManager count a player already standing in an event
zone when it opens or comes back after a restart, and enforce the flags of a zone opened
after it loaded. Without it, events still score everybody, but a zone's flags — PvP off,
no building — may not hold.
- **`RunicGatewayDomes.cs`** lets the bridge ask ZoneDomes for a dome over an event zone.
Without it, zones open without one.
- **`RunicGatewayRaids.cs`** lets an event spawn a RaidableBases base of its own and despawn
just that base when the event ends; see
[Optional plugins](/docs/rust/optional-plugins/#raidablebases).
## Day two
| | |
|---|---|
| `doctor --game rust` | Per server: the framework, whether each deployed file is still the one deployed, RunicNPC (a **failure** when missing — it is required), the required uMod plugins, the service, and `/health` through to *plugin connected* |
| `update --game rust` | Moves the sidecar and every server's plugin to the current bundle, together — they share one binary |
| `uninstall --game rust` | Removes the service, the plugin, its helpers and RunicNPC. **Keeps the plugin's config** and RunicNPC's data, because they name the server. `--purge` also removes the token and the database |
Next: [Connect the site](/docs/rust/connect-the-site/).
## Canonical documents
[`rust-link/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INSTALL.md)
is the operator guide, and its flags, paths and egg variables are the authority;
[`installer/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md)
covers the installer itself.

View File

@@ -0,0 +1,79 @@
---
title: Linking Steam accounts
description: How a player joins their Steam account to their site account — a code from /link in game, or Steam sign-in — and how staff undo a wrong link.
---
import { Aside } from '@astrojs/starlight/components';
A Rust player is a Steam account. A site member is a site account. **Linking** joins the two,
and it is what lets the site say *this member is that player*: their own page shows their
kills, coins and backpack, a clan becomes a [Team](/docs/administration/teams/) whose members
the site knows, and an event can reward a member by name.
## Two ways to link
**From the game, with a code.** The player page at `/player/rust` walks a player through it:
1. Join any of the community's Rust servers and type **`/link`** in chat.
2. The server answers with a **six-character code** that only that player can see. It lasts
five minutes.
3. Type it on `/player/rust`. It works once.
Typing a code that only reached one player into a signed-in browser is the proof that the
person at the browser is the person in the game. **The code never crosses the bridge**: what
the server tells the site is only that somebody asked for one.
**By signing in with Steam.** When an administrator has turned on Steam under
[Authentication](/docs/administration/authentication/#steam), a member who links Steam to
their site account from their account page has linked that Steam account for Rust too. It is
the same link, reached through Steam's own sign-in rather than through the game.
## What a link is
- **Fleet-wide.** A code from any of your servers links for all of them, and a member's
totals on their page are summed across every server and every wipe.
- **One owner at a time.** A Steam account belongs to one site account. If somebody links the
wrong account, the site refuses to move it — including through Steam sign-in, which refuses a
Steam account that is already another member's Rust link.
- **Kept by the site, not the game.** Nothing about a link is stored on the game host.
- **A member may hold several Steam accounts.**
## Undoing a link
- **The player:** **`/unlink`** in game asks the site to let go.
- **Staff:** **Admin → Users**, open the member, and the **Rust** section lists each linked
Steam account with an **Unlink** button. It is the way back for a player who linked the
wrong account and cannot reach it in game, and it is recorded in the activity log.
<Aside type="note" title="Unlinking Steam sign-in leaves the Rust link in place">
Removing Steam from a member's sign-in methods stops them signing in with it, and nothing
else. The Rust link is removed on the Rust side — `/unlink`, or the Rust section of the
member's page — so a member who only meant to stop using Steam to sign in does not lose
their history.
</Aside>
## What a linked player sees
On `/player/rust`: their linked Steam accounts, what they can do in game (the permissions
the site has given them on each server), the NPCs they have killed this wipe, their coins on
each server, and their backpack — once something is linked. Staff are sent to the admin
area rather than the player portal, and see the same facts for anybody from that member's
page.
## What staff see
On a member's page under **Admin → Users**, the Rust section shows each linked Steam account
with when it was linked and last played, and kills, deaths and time played per server. Below
it, staff can grant the member permissions, deposit, withdraw or set their coins on each
server, and open their backpack.
A link request and an unlink are **staff-only** [event kinds](/docs/rust/event-kinds/):
together they name a Steam account beside a site account's activity, and *this player is
that person* is not a public page's business.
## Canonical documents
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§9 is the link on the wire, and
[`website/STEAM_SIGNIN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/STEAM_SIGNIN.md)
is Steam sign-in, including how it meets the Rust link.

View File

@@ -0,0 +1,76 @@
---
title: Mod config from the site
description: Admin → Rust mod config — editing your plugins' config files on the game host from the site, with a backup, a watched reload, and an automatic undo.
---
import { Aside } from '@astrojs/starlight/components';
**Admin → Rust mod config** (`/admin/rust/config`) edits the configuration files on the game host
itself, read live through the bridge. It works for whatever plugins you have installed, because
it generates its form from the values it finds in each file.
## What it lists
Pick a server, and the screen names the directory it is reading — `oxide/config` or
`carbon/configs`, or wherever your framework was told to keep them — and lists the files there,
**grouped by the plugin each one probably belongs to**, with whether that plugin is loaded and
its version.
**The data directory is not listed, on purpose.** `oxide/data` and `carbon/data` hold live state
— kit cooldowns, zone definitions, the permission store itself — not settings. Editing them from
a web form edits your players' cooldowns, and the running plugin writes over the change on its
next save anyway. The one exception is RaidableBases' **profiles**, which live under its data
directory but are settings, and are listed beside its config as *Profile · …*.
## Editing a file
Open a file and it shows as a form (**Settings**), or as **Raw JSON** for a change the form does
not suit. Then choose what to **Reload** — the site suggests the plugin the file belongs to, and
*nothing — just write the file* is an option. A folder name is convention rather than contract,
so the guess is a field you can change, not an assumption.
**Save and reload** then:
1. backs the file up,
2. writes it,
3. reloads the plugin you named, and watches the reload,
4. and if the plugin does not come back, **puts the old file back on its own**, and shows you
the line from the server's log that says why.
A typo costs you a few seconds, not a plugin. The answer you see is one of:
- *Saved, and the plugin reloaded.*
- *The plugin did not come back, so the old file was put back automatically.*
- *…and it did not come back on the old file either. It is down: check the server console.* —
the old file was broken too, which is worth knowing before anything else.
- *The server never said how the reload went* — the bridge itself was reloaded, or the link
dropped. Re-read the file to see what is on disk.
A reload fails on evidence — the framework's log saying the plugin did not compile or start —
and a reload that says nothing at all is called lost only once a fixed ceiling has passed.
**Recent changes**, at the bottom, is every save, including the ones that did not land: what
changed, field by field, and whether it was applied or rolled back.
<Aside type="caution" title="The bridge's own file is special">
`RunicGateway.json` is editable here, except **`Host`, `Port` and `ServerId`**, which are shown
read-only. Changing them from the site would cut the link carrying the change, or strand every
row the site holds for the server — edit them on the host. And the bridge cannot be reloaded
from here, for the same reason. See [RunicGateway.json](/docs/rust/runicgateway-json/).
</Aside>
<Aside type="caution" title="RaidableBases: restart, never reload">
Change RaidableBases' config, then **restart the server** instead of reloading the plugin. A
reload can leave its live raids broken until a restart. See
[Optional plugins](/docs/rust/optional-plugins/#raidablebases).
</Aside>
`rg.config` at the server console prints which directory the site is reading, the log it
watches, a reload in progress, and what the last write from the site did.
## Canonical documents
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§11 and §19.1 are configuration on the wire;
[`modules/rust/OPERATING.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/OPERATING.md#plugin-configuration-plugins-configuration)
has uMod's own page on plugin configuration.

View File

@@ -0,0 +1,93 @@
---
title: Optional plugins
description: The uMod plugins the Rust module recognises beyond the required two, what each one adds to the site, and the two — RaidableBases and Guarded Crate — that catch operators out.
---
import { Aside } from '@astrojs/starlight/components';
import platform from '../../../../data/platform.json';
The bridge needs {platform.games.rust.bundle.requiresPlugins.join(' and ')}, and RunicNPC. Everything
below is optional: install what your server wants, and the site notices. The bridge reports what it
finds when it connects and whenever a plugin loads or unloads, and **Optional mods** on a row of
[Admin → Rust servers](/docs/rust/connect-the-site/#the-rest-of-a-servers-settings) prints it —
each plugin's version, and what it lets the site do on that server.
**Runic Gateway never ships or modifies any of these.** They are their authors' plugins, installed
the way uMod's own guide describes, and a server without one simply lacks that feature.
| Plugin | What the site does with it |
|---|---|
| **BetterChat** | Shows [chat titles](/docs/rust/connect-the-site/#chat-titles) and [group chat styles](/docs/rust/permissions-and-groups/#chat-styles) in game chat. Titles still show on the leaderboard without it |
| **PopupNotifications** | Lets news, event lines and zone messages arrive as a popup. Without it a popup falls back to chat, or is refused with a reason |
| **Economics** | Coins: the *Pay coins* step, the *Richest* title, and balances on a member's page that staff can adjust |
| **Backpacks** | Shows a player's backpack, and lets an event lend a bigger size |
| **TruePVE** | Lets an event's zone turn PvP protection off, or name a ruleset |
| **Dynamic PVP** | Its PvP zones — around a downed helicopter, a Bradley, cargo — appear in the feed and on the map |
| **Dangerous Treasures** | Its events appear in the feed and on the map, earn the *Treasure Hunter* title, and a step may start one |
| **Guarded Crate** | Its crates appear in the feed and on the map, earn the *Warden* title, and a step may place one. [Needs NpcSpawn](#guarded-crate) |
| **RaidableBases** | Its bases appear in the feed and on the map, earn the *Warlord* title, and a step may spawn one that is the event's own. [Read this first](#raidablebases) |
| **ZLevels Remastered** | An event may lend its XP boosts, which are permissions |
| **ZoneDomes** | A dome over an event's zone, through the bridge's domes helper |
PopupNotifications has a recommended look — a banner across the top of the screen — which the
installer and the egg write only where its config is missing or still its own defaults. The
[install guide](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INTEGRATION.md#24-the-recommended-popupnotifications-look-optional)
has the config.
**Clans is not on the list, deliberately.** A server's clans come from Rust's own clan system,
which that plugin never touches, so installing it would split your players across two unrelated
clan systems.
## RaidableBases
Either edition works, the paid or the free one. The bridge's **raids helper**,
`RunicGatewayRaids.cs`, installed beside the plugin by default, is what lets an event spawn a base
of its own — at a spot, with its own settings and lock — and despawn only that base when the event
ends. Without it a base an event spawned despawns on its own timer. Difficulty, profile and base
names in the step editor come from RaidableBases itself, so they are whatever your copy has.
Two of RaidableBases' own behaviours catch operators out:
<Aside type="caution" title="Change its config with a restart, never a reload">
After a reload of RaidableBases on a running server, its list of live raids can hold an empty
entry, and every hook that walks the list fails: damage to a base, its SAM sites, players'
commands, and the purchase command, so a purchase does nothing and charges nothing. Only a full
server restart clears it. It is RaidableBases' own bug. Edit its config — from
[Mod config](/docs/rust/mod-config/) with *nothing* chosen to reload, or on the host — then restart
the server.
</Aside>
<Aside type="caution" title="Back up before switching editions">
Putting the free edition in place of the paid one rewrites the profiles a paid base pack installed,
and drops their bases from them. Going back to the paid edition does not bring them back. Back up
RaidableBases' config and data folders first.
</Aside>
## Guarded Crate
Guarded Crate **needs NpcSpawn** for its guards, and NpcSpawn is not on uMod: it is a free download
from Codefling. Install it before Guarded Crate:
1. Put `NpcSpawn.cs` in the plugins directory.
2. Put the archive's `data/Images/` files in the data directory's `Images` folder. **Without them
NpcSpawn unloads itself.**
3. Leave `data/NpcSpawn/` for NpcSpawn to create. A folder made by a panel's file manager may not be
writable by the game.
4. Install Guarded Crate from uMod.
**NpcSpawn contacts its author's server when it loads**: it calls a version server and downloads
clothing images. If your server may not reach the internet, or you do not want it to, know that
before installing it.
Without NpcSpawn, the *Place a guarded crate* step is refused with a reason — the bridge checks,
because Guarded Crate would otherwise drop a crate with no guards. Its events are rows in its data
file (Easy, Medium, Hard and Elite as it ships), and the site offers whatever names that file holds.
**A crate placed by an event is kept when the event ends**: Guarded Crate has no way to end one
event without ending them all.
## Canonical documents
[`modules/rust/OPERATING.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/OPERATING.md)
holds the RaidableBases and Guarded Crate notes in full;
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§18 and §20 are each plugin on the wire.

View File

@@ -0,0 +1,93 @@
---
title: Permissions and groups
description: Admin → Rust permissions — the site holds every server's permissions and groups, pushes them into Oxide or Carbon, and decides what happens to a change made in game.
---
import { Aside } from '@astrojs/starlight/components';
import Screenshot from '../../../../components/Screenshot.astro';
**Admin → Rust permissions** (`/admin/rust`) is where the site holds every permission and group
on each server: what was there before the site, what is made here, and what is changed in the
game. It reads each server's own permission store and pushes the site's set back into it, so
every plugin you already run honours it — Kits, ZoneManager, anything that asks Oxide or
Carbon whether a player has a permission. Nothing is configured twice, and nothing is asked of
those plugins.
## The first sync imports
A server's first sync **imports everything** in its store, so taking the site into use loses
nothing an operator had already set up at the console. Until then the server is marked *not
imported yet*. After that, the site's set is the one that holds.
**A wipe loses nothing.** The site pushes the whole set again when the server comes back, so a
wipe script that clears the data directory costs a minute, not your permissions.
## In-game changes
An operator will still grant something at the console during an incident. What happens to it is
a per-server choice:
| Mode | A change made in the game |
|---|---|
| **auto-adopt** | Becomes the site's own, for that server |
| **adopt** | Waits under *Waiting for a person*, to be adopted or undone |
| **revoke** | Is undone at the next sync |
The chip beside the mode says when the server last synced. **Sync now** pushes at once.
## Players
The **Players** tab lists everybody who holds something on the selected server; pressing Enter in
its search reaches every player the server has seen. A player shows their site account, when they
have [linked one](/docs/rust/linking-steam-accounts/).
Pick one, and their permissions are listed by the plugin that registers them, with **Grant all**
and **Revoke all** per plugin. Tick **Grant on every server** to make a grant fleet-wide rather
than for this server only. Chips on a permission explain what you are looking at:
| Chip | Meaning |
|---|---|
| *not registered here* | No loaded plugin on this server registers it, so it cannot be granted — Oxide and Carbon silently do nothing for an unknown name. Load the plugin and the grant lands by itself |
| *revoked here only* | Granted on every other server, and taken away on this one |
| *from an event* | An event gave it, and the event's end takes it back |
| *waiting for their first connection* | The server has never seen this player. A grant to them lands when they first join; every sync pushes it again |
## Groups
The **Groups** tab lists the server's groups with their member counts, and **Create** makes a
new one. Each group has four tabs:
- **Permissions**, laid out as a player's are.
- **Players** — who is in it. Every player who connects is in `default`, so it lists nobody.
A player the server has never seen cannot be put in a group yet; the site says the membership
is waiting, and it lands on their first connection.
- **Settings** — the group's title, its rank and its parent group, whose permissions it
inherits.
- **Servers.** A group belongs to one server unless it is **shared**. A shared group carries the
same permissions and players on every server it is on — including servers added later, if you
tick that — and a change made in one game gives that server its own copy.
<Screenshot id="admin-rust-permissions" />
### Chat styles
A group's **Settings** tab has a **Chat style (BetterChat)** section. Give a group a style and
BetterChat, where it is installed, shows its members' titles, colours and sizes as you set them
here, with a priority deciding between a player's groups. A group with a style can also be the
**announcement voice** on [Admin → Rust servers](/docs/rust/connect-the-site/#chat-titles), so
news and event lines in game chat wear its title.
<Aside type="note" title="rg.perms at the server console">
Prints what the last sync did. It is the fastest way to tell *that permission does not exist
here* from *that player has never been seen here* — both look like "the site says they have it
and the game disagrees" from the other end.
</Aside>
## Canonical documents
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§10 and §19.9 are the permission mirror on the wire;
[`modules/rust/OPERATING.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/OPERATING.md#permissions-plugins-permissions)
has uMod's own guide to permissions and groups, and
[`CARBON.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/CARBON.md)
how Carbon's store differs.

View File

@@ -0,0 +1,74 @@
---
title: RunicGateway.json
description: The bridge plugin's own config file on the Rust server — every key, which three the site will not edit, and the event bounds that refuse rather than trim.
---
import { Aside } from '@astrojs/starlight/components';
import { rustPluginConfig } from '../../../../data/reference.mjs';
The bridge plugin's config, written by the framework as `oxide/config/RunicGateway.json`, or
`carbon/configs/RunicGateway.json` on Carbon. The plugin fills in every key it is missing on
load, so a config written by an older version shows the newer keys after the first load with the
new one — which is what lets [Mod config](/docs/rust/mod-config/) show a switch before anybody needs
it.
**Where the first one comes from.** The installer writes one holding just `ServerId` and `Port`,
and only when there is none. On a Pterodactyl egg, the plugin's first load takes the server id from
the `RUSTLINK_SERVER_ID` variable. After that the file is canonical, and changing either source
changes nothing.
## The keys
<table>
<thead><tr><th>Key</th><th>What it is for</th></tr></thead>
<tbody>
{Object.entries(rustPluginConfig).flatMap(([group, keys]) => [
<tr key={group}><th colspan="2">{group}</th></tr>,
...Object.entries(keys).map(([name, k]) => (
<tr key={name}>
<td><code>{name}</code>{k.readOnlyFromSite ? <><br /><small>read-only from the site</small></> : null}</td>
<td>{k.why}</td>
</tr>
)),
])}
</tbody>
</table>
This list is checked against the plugin's own source on every build.
<Aside type="caution" title="Three keys are the host's">
`Host`, `Port` and `ServerId` are read-only in the site's config editor. Changing the first two
from the site would cut the link carrying the change; changing `ServerId` would strand every row
the site holds for this server. **`ServerId` is permanent** — it is not the hostname, so a server
can be renamed for a season without losing its history.
</Aside>
## The event bounds
`EventsEnabled` ships **off**. While it is off the site may still list and give back what events
hold, so switching it off never strands anything; it may not borrow, place, count, pay or say
anything new. See [Events, zones and rewards](/docs/rust/events-zones-and-rewards/).
Saved from [Mod config](/docs/rust/mod-config/), **`EventsEnabled` takes effect at once**. The
bridge never reloads itself, so its other settings apply at its next reload — a server restart,
or a reload at the console.
Each `EventsMax…` key is how much **one step** may do on this server — or, for
`EventsMaxWorldCalls`, one run, and for `EventsMaxTallies`, the whole server at once. Two rules
hold for all of them:
- **An operator may lower a bound, never raise it** past the plugin's own ceiling. A value above it
is brought down to it when the plugin loads.
- **A step over a bound is refused, never trimmed to fit.** An event that does less than its
author wrote, quietly, is worse than one that says it cannot.
The two `Map…` keys are different: a map answer over its bound is cut short and says so, because a
read has nobody to refuse.
## Canonical documents
The `PluginConfig` class in
[`RunicGateway.cs`](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins/src/branch/main/overlay/oxide/plugins/RunicGateway.cs)
is the authority;
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§6.1 describes the file and §14 to §17 each key as it arrived.

View File

@@ -0,0 +1,362 @@
---
title: The API
description: RunicNPC's API for other Oxide and Carbon plugins, in full — every call, every hook it raises, and the shapes of an NPC, a placement and a route.
---
import { Aside, Code } from '@astrojs/starlight/components';
import platform from '../../../../../data/platform.json';
import Signature from '../../../../../components/Signature.astro';
import Ticks from '../../../../../components/Ticks.astro';
import {
runicnpcOwners,
runicnpcHooks,
runicnpcListKeys,
runicnpcPlacementKeys,
runicnpcRouteKeys,
} from '../../../../../data/runicnpc.mjs';
<Aside title="The specification is normative">
This page carries RunicNPC's API in full, for plugin authors. Its specification is
[`docs/runicnpc/API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/runicnpc/API.md),
and where the two ever disagree, that wins. Every signature and every field name below is
checked against it on every build, so a call, hook or field that changes there turns this site
red until this page follows.
</Aside>
This is **API version {platform.runicnpc.api}**, shipped in RunicNPC
{platform.releases['runicnpc-rust']}. RunicNPC works without Runic Gateway, and so does
everything on this page.
## Calling it
RunicNPC is called by name through `Call`, like any Oxide or Carbon plugin API. Every call is
prefixed `RunicNpc_`, so no hook of another plugin is ever matched by accident.
<Code
lang="csharp"
code={[
'[PluginReference] private Plugin RunicNPC;',
'',
'int api = RunicNPC?.Call<int>("RunicNpc_ApiVersion") ?? 0;',
`if (api < ${platform.runicnpc.api}) { /* too old for this caller: say so */ }`,
'',
'BasePlayer npc = RunicNPC.Call("RunicNpc_Spawn", position, "warden", "plugin:MyPlugin", null) as BasePlayer;',
].join('\n')}
/>
**The API version moves when a call or a raised hook changes shape**, not on every release. The
release's manifest carries it too, so an installer can refuse a RunicNPC too old for its caller
before it is loaded. Check it before relying on a call.
**A call that cannot do what it was asked returns null, 0 or false, and says why in the server
log.** Calls that change data return the reason as a string instead, and null means success.
## Owners
Every NPC has an owner, and the owner decides how long it lives.
<table>
<thead><tr><th>Owner</th><th>Who uses it</th><th>Lifetime</th></tr></thead>
<tbody>
{Object.entries(runicnpcOwners).map(([owner, o]) => (
<tr key={owner}><td><code>{owner}</code></td><td><Ticks text={o.who} /></td><td><Ticks text={o.lifetime} /></td></tr>
))}
</tbody>
</table>
## Spawning and removing
### RunicNpc_ApiVersion
<Signature call="RunicNpc_ApiVersion" />
The API version: {platform.runicnpc.api}.
### RunicNpc_Spawn
<Signature call="RunicNpc_Spawn" />
Spawns one NPC now, or returns null.
- `owner` must be `run:<id>` or `plugin:<name>`.
- `overrides` may change any [profile field](/docs/rust/runicnpc/profile-fields/) for this NPC
only, in the profile's own shape, or be null. For example:
`{"health": 500, "names": ["Captain"], "movement": {"mode": "route:gate", "radius": 0}}`.
Arrays are replaced, not merged, and the merged profile is checked like a saved one.
- A roamer must stand on Rust's navmesh, within 3 m across and 2 m up or down of `at`. A sentry
may stand anywhere.
- It is refused until the map's navmesh is built, which takes 8–10 minutes on a map's first boot.
It is refused for an unknown or refused profile, a bad owner, an override that fails, a spot off
the navmesh, a cap an admin has set, or a navmesh not built yet.
### RunicNpc_Despawn
<Signature call="RunicNpc_Despawn" />
Removes one NPC by its net id, and returns 1, or 0 if it is not one of RunicNPC's. A placement's
NPC comes back after its respawn delay. **For a boss, it also removes the adds that boss
summoned**, even once the boss is dead, and counts them in what it returns: whoever placed the
boss knows only the boss's net id.
### RunicNpc_DespawnOwner
<Signature call="RunicNpc_DespawnOwner" />
Removes every NPC of `owner`, and returns how many it removed.
### RunicNpc_IsRunicNpc
<Signature call="RunicNpc_IsRunicNpc" />
Whether `entity` is one of RunicNPC's NPCs.
### RunicNpc_ProfileOf
<Signature call="RunicNpc_ProfileOf" />
The name of its profile, or null.
### RunicNpc_CostWarning
<Signature call="RunicNpc_CostWarning" />
The [cost warning](/docs/rust/runicnpc/cost-and-caps/) for the NPCs the server plans, plus
`adding`: what they add to a server frame, idle and fighting, and how slowly each then reacts. A
caller that adds NPCs should show it to whoever added them.
## Listing NPCs
### RunicNpc_List
<Signature call="RunicNpc_List" />
The live NPCs of `owner`, or of every owner when it is null. Each row has:
<table>
<thead><tr><th>Key</th><th>Type</th><th>What it is</th></tr></thead>
<tbody>
{Object.entries(runicnpcListKeys).map(([key, k]) => (
<tr key={key}><td><code>{key}</code></td><td><code>{k.type}</code></td><td><Ticks text={k.what} /></td></tr>
))}
</tbody>
</table>
## Orders for one NPC
### RunicNpc_Escort
<Signature call="RunicNpc_Escort" />
One of RunicNPC's NPCs escorts `target`: a player, or any other entity — a crate it guards, a
vehicle. It keeps within a few metres, never targets it, and fights whoever damages it. **When the
target dies, is destroyed or, for a player, leaves the server**, it walks back to its spot,
carries on as its profile does there, and `OnRunicNpcEscortEnded` is raised. A null `target`
stops it. Null on success; refused for a sentry, which never moves, and for a player who is not on
the server.
### RunicNpc_Ally
<Signature call="RunicNpc_Ally" />
Allies one NPC to `clan` (the game's own clan id), `team` (a Rust team id) or `player` (a Steam
id: that player, and their team if they have one), or to nobody with `none`. It **never targets**
the ally's people, and **defends them and what they own** — building blocks, doors, deployables:
whoever damages one of them within its leash is fought. Rust's own clans and teams only. Null on
success; refused for a clan or team the server does not have.
### RunicNpc_Tether
<Signature call="RunicNpc_Tether" />
Holds one NPC inside a ZoneManager zone: it never chases or wanders out, and if it ends up outside
— pushed, or the zone moved — it forgets the fight and walks home. A null `zone` frees it. Refused
for a sentry, on a server without ZoneManager, for a zone the server does not have, and for a zone
that does not hold the NPC.
## Profiles and factions
### RunicNpc_Profiles
<Signature call="RunicNpc_Profiles" />
`{"managed": bool, "profiles": {name: profile, …}, "factions": [pair, …], "refused": {name: reason, …}}`.
`managed` is whether a site manages this server. A refused profile is kept in the file but never
spawns — a kit the server lacks, for example. `factions` is the faction table. Every field of a
profile is on [Profile fields](/docs/rust/runicnpc/profile-fields/).
### RunicNpc_SetProfiles
<Signature call="RunicNpc_SetProfiles" />
Replaces the whole profile set with `all` (`{name: profile, …}`), as a site does on every push,
and **marks the server managed**: from then on, the console commands that edit profiles are
refused. It returns the profiles refused and why; the rest are in use at once. A placement whose
profile has gone waits, and spawns again when the profile returns.
### RunicNpc_Factions
<Signature call="RunicNpc_Factions" />
The faction table: `[{"a": "bandits", "b": "guards", "relation": "hostile"}, …]`, one row per
pair, meaning both ways. A pair not listed is neutral, and a faction is always allied to itself.
### RunicNpc_SetFactions
<Signature call="RunicNpc_SetFactions" />
Replaces the faction table, as a site does with every push, and **marks the server managed**.
Null on success; otherwise the first problem, and the old table is kept. Refused: a pair of one
faction with itself; a pair of `scientists` and `animals`, because RunicNPC does not change how
Rust's own NPCs treat each other; a relation other than `hostile`, `neutral` or `allied`; and a
pair given twice, in either order.
## Placements
A **placement** is a spot where a profile's NPCs stand and come back after they die. It is saved;
its NPCs never are. Its keys:
<table>
<thead><tr><th>Key</th><th>What it is</th></tr></thead>
<tbody>
{Object.entries(runicnpcPlacementKeys).map(([key, what]) => (
<tr key={key}><td><code>{key}</code></td><td><Ticks text={what} /></td></tr>
))}
</tbody>
</table>
```json
{
"profile": "warden",
"position": { "x": 100.0, "y": 12.5, "z": -340.0 },
"yaw": 90,
"count": 3,
"respawn": 300,
"respawnMode": "each",
"movement": { "mode": "route:gate", "radius": 0 }
}
```
A placement whose profile or zone has gone **waits**, and spawns again when it returns. **If the
ground under a placement goes later** — a player-built floor destroyed — a live NPC is put on the
nearest navmesh within 2 s, and the placement respawns its NPCs on the nearest navmesh until its
spot is walkable again. Rust itself would leave such an NPC standing in the air.
### RunicNpc_Placements
<Signature call="RunicNpc_Placements" />
Each placement as `{id, placement, alive, waiting, lastError, note}`: `placement` is its JSON,
`alive` how many of its NPCs are alive, and `waiting` why it cannot spawn now, or null. `note` is
set while its NPCs stand somewhere other than its spot because the ground there went, and null
otherwise.
### RunicNpc_AddPlacement
<Signature call="RunicNpc_AddPlacement" />
**Creates a placement and names it as `/rnpc place` does**: the profile's name and the first free
number, `warden-3`. It is checked and refused exactly as `/rnpc place` is, with the same
sentences, so a placement made by another plugin or a website and one made in game never disagree.
- `placement` has no id. **A `position` without `y` is a point on the map**: it is put on the
ground there by a ray down onto terrain and rock, never a building or a tree, then checked
against the navmesh like any other. A point off the map, or under water, is refused.
- The answer is `{id, position, built, cost}` — the name given, where it landed, whether that spot
is on something players built, and the cost warning — or `{error}`, the sentence `/rnpc place`
would have said.
### RunicNpc_SetPlacement
<Signature call="RunicNpc_SetPlacement" />
Adds or replaces a placement with the id you give. Null on success, or the reason. Replacing one
removes its NPCs and spawns them again from the new values. Every set logs the cost warning.
A roamer's spot must be on Rust's navmesh, within 2 m up or down, when it is set; otherwise the
answer says how far off it is. The check is skipped while the map's navmesh is still being built,
and for a profile that does not exist yet.
### RunicNpc_RenamePlacement
<Signature call="RunicNpc_RenamePlacement" />
Renames a placement, as `/rnpc rename` does: its live NPCs keep living under the new name. Null on
success, or why not — no such placement, the name taken, or not a name.
### RunicNpc_RespawnPlacement
<Signature call="RunicNpc_RespawnPlacement" />
Removes a placement's NPCs and spawns them again at once, as `/rnpc respawn` does. Returns how
many, or `-1` if there is no such placement.
### RunicNpc_RemovePlacement
<Signature call="RunicNpc_RemovePlacement" />
Removes a placement and its NPCs.
## Routes
A route is a line of points an NPC walks. An NPC joins a route at its nearest point.
<table>
<thead><tr><th>Key</th><th>What it is</th></tr></thead>
<tbody>
{Object.entries(runicnpcRouteKeys).map(([key, what]) => (
<tr key={key}><td><code>{key}</code></td><td><Ticks text={what} /></td></tr>
))}
</tbody>
</table>
```json
{ "points": [ { "x": 1, "y": 2, "z": 3 }, { "x": 4, "y": 2, "z": 6 } ], "loop": true }
```
### RunicNpc_Routes
<Signature call="RunicNpc_Routes" />
Every route, as `{name: route, …}`.
### RunicNpc_SetRoute
<Signature call="RunicNpc_SetRoute" />
Adds or replaces a route. Every point must be on Rust's navmesh. Null on success, or the reason.
**Unlike `/rnpc path`, it does not check that an NPC can walk from each point to the next**: a leg
Rust cannot path leaves the NPC standing at the last point it reached, so a caller that builds
routes should check its own legs.
### RunicNpc_RemoveRoute
<Signature call="RunicNpc_RemoveRoute" />
Removes a route. Placements that walk it wait until it exists again.
## Hooks it raises
Every hook is called on every plugin, and **none of them answers**: a return value is ignored.
<table>
<thead><tr><th>Hook</th><th>When</th></tr></thead>
<tbody>
{Object.entries(runicnpcHooks).map(([hook, h]) => (
<tr key={hook}><td><code>{`${hook}(${h.params})`}</code></td><td><Ticks text={h.when} /></td></tr>
))}
</tbody>
</table>
## Its files
`data/RunicNPC/profiles.json` (the profiles, the faction table and whether a site manages them),
`placements.json` and `routes.json`, under `oxide/` or `carbon/`. From a plugin, change them
through the calls above rather than the files. See [Install RunicNPC](/docs/rust/runicnpc/install/#its-files)
for every file and who writes it.
<Aside type="caution" title="A Kits reload reloads RunicNPC">
RunicNPC requires Kits, so both frameworks reload RunicNPC with it, and every NPC it had spawned is
lost. Placements come back; NPCs a plugin or an event spawned do not, and `OnRunicNpcDespawned` is
not raised for them.
</Aside>

View File

@@ -0,0 +1,104 @@
---
title: Commands
description: Every /rnpc chat command and rnpc.* console command RunicNPC answers, the two permissions they need, and the options for placing NPCs.
---
import Ticks from '../../../../../components/Ticks.astro';
import {
runicnpcCommands,
runicnpcPermissions,
runicnpcPlaceOptions,
} from '../../../../../data/runicnpc.mjs';
export const Commands = ({ section }) => (
<table>
<thead><tr><th>Command</th><th>Does</th><th>Needs</th></tr></thead>
<tbody>
{Object.entries(runicnpcCommands[section]).map(([usage, c]) => (
<tr key={usage}>
<td><code>{c.console ? `rnpc.${usage}` : `/rnpc ${usage}`}</code></td>
<td><Ticks text={c.does} /></td>
<td>{c.perm.startsWith('runicnpc.') ? <code>{c.perm}</code> : c.perm}</td>
</tr>
))}
</tbody>
</table>
);
## How commands are reached
- **In chat:** `/rnpc <verb> …`. `/rnpc` alone lists the verbs you are allowed to use.
- **In a console:** `rnpc.<verb> …`, in a player's F1 console, the server console or RCON. The
same code answers both, with the same permissions.
- **Four verbs answer only in a console** — `profile`, `faction`, `status` and `reload`. In chat
they tell you to open F1.
- **The server console has every permission.** It has no position, so placing there takes `at=`
and `yaw=` instead of where you look.
The verbs, the permissions and the placing options on this page are checked against the plugin's
own source on every build.
## Permissions
<table>
<thead><tr><th>Permission</th><th>Grants</th></tr></thead>
<tbody>
{Object.entries(runicnpcPermissions).map(([perm, grants]) => (
<tr key={perm}><td><code>{perm}</code></td><td><Ticks text={grants} /></td></tr>
))}
</tbody>
</table>
On a Runic Gateway server both show in **Admin → Rust permissions** like any plugin's, and the
site grants them there — see [Permissions and groups](/docs/rust/permissions-and-groups/).
## Placements
A **placement** is a spot where a profile's NPCs stand and come back after they die. It is saved
on the server and survives restarts. Placements made in game are named after their profile and a
number, `bandit-1`, and can be renamed. The site's [placements screen](/docs/rust/runicnpc/npc-placements/)
edits the same list.
<Commands section="Placements" />
### Options for `place` and `here`
`key=value`, in any order: `/rnpc place raider count=3 respawn=600 mode=group`.
<table>
<thead><tr><th>Option</th><th>Means</th><th>Default</th></tr></thead>
<tbody>
{Object.entries(runicnpcPlaceOptions).map(([key, o]) => (
<tr key={key}><td><code>{key}=</code></td><td><Ticks text={o.means} /></td><td><Ticks text={o.default} /></td></tr>
))}
</tbody>
</table>
**Every placement is checked against Rust's navmesh.** A roamer must stand on it; only a sentry,
or a passive NPC that stands, may stand off it. On a player-built floor the placement is made with
a warning: if the floor is destroyed, the NPCs fall back to the nearest navmesh, and return to
their spot once it is rebuilt. Every command that adds NPCs answers with the
[cost warning](/docs/rust/runicnpc/cost-and-caps/).
## Routes
A route is a line of points an NPC walks, recorded in game where you walk, one point at a time.
A recording is kept in memory only: a reload of RunicNPC discards it. A placement walks one with
`move=route:<name>`.
<Commands section="Routes" />
## At the console
**On a Runic Gateway server the site manages the profiles and the faction table.** There,
`rnpc.profile create`, `set` and `delete`, and `rnpc.faction set` and `clear`, are refused with
"managed by its website"; `show` and `list` still answer. On a server with no site, they are how
profiles are made: see [Profile fields](/docs/rust/runicnpc/profile-fields/) for every field
`set` takes.
<Commands section="At the console" />
A boss block or a press-E block is added with its defaults by `set <name> boss on` or
`set <name> use on`, and removed with `none`. Their fields are then set one at a time —
`boss.spawnLine The Juggernaut has risen!` — and a list of objects as JSON:
`boss.phases [{"at":0.5,"line":"…"}]`. Setting `role passive` also turns `hurtByPlayers` off.

View File

@@ -0,0 +1,79 @@
---
title: Cost and caps
description: What RunicNPC's NPCs cost a Rust server, measured rather than guessed, the warning that says so wherever NPCs are added, and the caps an operator can set.
---
import Ticks from '../../../../../components/Ticks.astro';
import { runicnpcConfig } from '../../../../../data/runicnpc.mjs';
**RunicNPC has no caps by default.** Instead, everything that adds NPCs answers with what the
server's RunicNPC NPCs will then cost: `/rnpc place`, the site's
[placements screen](/docs/rust/runicnpc/npc-placements/), an event's *Place NPCs* step, the API's
`RunicNpc_CostWarning`, and the end of `rnpc.status`. A server's owner knows their hardware and
their players; a number someone else picked would be wrong for most of them.
## The cost warning
It reads like this:
```
RunicNPC: 100 NPC(s) on this server. Measured on a test server, they add about 3 ms to every
server frame while idle with a player near enough to wake them, and about 0.5 ms once they sleep
with nobody near. If all fight at once they add about 9 ms, and Rust's shared 2 ms AI budget then
lets each react only every 3 s. …
```
What it means:
- **Idle NPCs are cheap, and sleeping ones cheaper.** NPCs that stand, wander or patrol with
nobody to fight add a little to a frame. One with no player within its sleep distance — 160 m
unless its profile says otherwise — walks home and sleeps, and then costs about a sixth of what
it did awake.
- **Fighting NPCs hit Rust's AI budget before the frame rate.** All of Rust's human NPCs, its own
scientists included, share one AI budget of 2 ms a frame (`aithinkmanager.framebudgetms`). With
many fighting at once, each reacts less often. The server stays smooth, and the NPCs get slower
to react.
- **Fighting other NPCs costs about what fighting players does.** That is a faction setting, and
off unless a profile opts in. On a map whose own AI is busy, each then reacts less often still;
the warning says by how much once any profile fights NPCs.
## Where the figures come from
They are measured, not guessed: 100 of the released NPC on both frameworks, on a 6000 map, as what
they add to the median server frame of the same session's empty server. Beside them is Rust's own
scientist, measured the same day.
| 100 NPCs, over an empty server | RunicNPC on Oxide | RunicNPC on Carbon | Rust's scientist (Oxide / Carbon) |
|---|---|---|---|
| Idle, a player near enough to keep them awake | +2.7 to +2.9 ms | +1.5 ms | +1.0 / +1.0 ms |
| Idle, asleep with nobody within 160 m | — | +0.5 ms | — |
| Fighting 20 players | +7.2 ms | +9.0 ms | +7.5 / +8.0 ms |
**Fighting costs what Rust's own AI costs.** The warning uses the worst figure in each row,
rounded up: 3 ms awake, 0.5 ms asleep and 9 ms fighting, per 100. The awake figure on Oxide is
higher than it should be, and is being worked on in
[runicnpc-rust#13](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust/issues/13). Your
server's own figures depend on its CPU, its map and its players.
## Caps
To cap them anyway, set any of these in `config/RunicNPC.json` (Carbon: `configs/RunicNPC.json`)
and reload RunicNPC. Every cap is 0, meaning none, until you set it.
<table>
<thead><tr><th>Key</th><th>What it limits</th></tr></thead>
<tbody>
{Object.entries(runicnpcConfig).map(([key, what]) => (
<tr key={key}><td><code>{key}</code></td><td><Ticks text={what} /></td></tr>
))}
</tbody>
</table>
These keys are checked against the plugin's own source on every build.
**A spawn over a cap is refused, naming the cap**, whether it came from `/rnpc`, the site, an
event step or another plugin.
**The bridge has its own bound too.** On a Runic Gateway server, `EventsMaxNpcs` in the bridge
plugin's [RunicGateway.json](/docs/rust/runicgateway-json/) limits how many NPCs one event step may
place — whatever RunicNPC's caps allow.

View File

@@ -0,0 +1,75 @@
---
title: RunicNPC
description: Runic Gateway's own NPC plugin for Rust — what it is, how it works with and without a Runic Gateway site, and where each page about it fits.
---
import platform from '../../../../../data/platform.json';
**RunicNPC** is an NPC plugin for Rust, on Oxide and Carbon, written by this project. It puts
NPCs where you want them, with the kit, health, aim, ranges and behaviour you give them, and
brings them back after they die. It is one file, `RunicNPC.cs`, compiled by the framework from
source like any uMod plugin.
| | |
|---|---|
| **Release** | {platform.releases['runicnpc-rust']}, from [`runicnpc-rust`](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust/releases) |
| **API version** | {platform.runicnpc.api} |
| **Runs on** | Oxide {platform.runicnpc.oxideMin} or Carbon {platform.runicnpc.carbonMin}, or newer |
| **Needs** | {platform.runicnpc.requiresPlugins.join(' and ')}. ZoneManager is optional, for holding NPCs inside a zone |
## Two ways to run it
**On its own.** RunicNPC runs on any Rust server, with no Runic Gateway site anywhere. You place
NPCs in game with `/rnpc`, edit their profiles at the console, and other plugins drive it through
its [API](/docs/rust/runicnpc/api/). Nothing on this page beyond this section is needed to use it
that way.
**On a Runic Gateway server.** There it is **required**, and installed with the bridge from the
same bundle. Every NPC an event places is RunicNPC's, Rust's own scientists included. The site
then owns the NPC **profiles** and the **faction table**, and pushes them to each server; the
console commands that would edit them are refused with "managed by its website". **Placements
stay the server's**: they are made in game or from the site's map, and both see the same list.
## What it is made of
- **A profile** is a named description of an NPC: its names and kits, its role, how it moves, how
hard it is, whom it fights, and optionally a boss's phases, what pressing E on it does, and its
own loot. See [Profile fields](/docs/rust/runicnpc/profile-fields/).
- **A placement** is a spot where a profile's NPCs stand and come back after they die. It is saved
on the server and survives restarts. **The NPCs themselves are never saved**: at boot, each
placement spawns fresh ones.
- **A route** is a line of points, recorded in game, that an NPC walks.
- **An owner.** Every NPC has one, and the owner decides how long it lives: a placement, an event
run, or another plugin. An event's NPCs go when the event is torn down, and another plugin's go
when it unloads.
**The roles.** A *roamer* moves, chases and fights. A *sentry* stands still and shoots. A *guard*
holds its spot, chases within its leash and walks back. A *passive* NPC never fights, and pressing
E on it says a line or opens a window — a quest-giver or a quartermaster. Any role but passive can
be a **boss**: a health bar at the top of the screen, phases as its health falls, and lines said
in game.
**Factions.** With no faction settings an NPC fights players only. Profiles can be put on sides,
made hostile to Rust’s scientists or animals, or to each other; through the API, one NPC can
also be allied to a clan, a team or a player, and defend what they own.
**On a Runic Gateway site** RunicNPC's NPCs also show up elsewhere: their names in a server’s
[feed](/docs/rust/), NPC kills on the leaderboard, bosses and event NPCs on the
[live map](/docs/rust/the-live-map/), and a step's "3 of 8 left" on a running event's page. An
event places them with its *Place NPCs* step and can wait on them dying or on a boss's health; see
[Events, zones and rewards](/docs/rust/events-zones-and-rewards/).
**It never phones home.** RunicNPC makes no network call, downloads nothing and scans nothing at
boot.
## In this group
| Page | Read it when |
|---|---|
| [Install RunicNPC](/docs/rust/runicnpc/install/) | Putting it on a server, with or without Runic Gateway, and after a Rust update |
| [Commands](/docs/rust/runicnpc/commands/) | Placing NPCs and recording routes in game, and the console |
| [NPC profiles](/docs/rust/runicnpc/npc-profiles/) | Authoring profiles and the faction table on the site |
| [NPC placements](/docs/rust/runicnpc/npc-placements/) | Placing NPCs from the site's map |
| [Cost and caps](/docs/rust/runicnpc/cost-and-caps/) | Knowing what NPCs cost a server, and capping them |
| [Profile fields](/docs/rust/runicnpc/profile-fields/) | Every field of a profile, for the editor, the console and the API alike |
| [The API](/docs/rust/runicnpc/api/) | Writing a plugin that spawns, orders or listens to RunicNPC's NPCs |

View File

@@ -0,0 +1,115 @@
---
title: Install RunicNPC
description: Putting RunicNPC on a Rust server — from the Runic Gateway bundle, or by hand on a server with no site — its files, and what to check after a Rust update.
---
import { Aside, Code } from '@astrojs/starlight/components';
import platform from '../../../../../data/platform.json';
## What it needs
| | |
|---|---|
| **Oxide {platform.runicnpc.oxideMin} or Carbon {platform.runicnpc.carbonMin}**, or newer | The builds it is known good on. Its release manifest states them, and the installer checks them |
| **[Kits](https://umod.org/plugins/kits)** | **Required.** A profile equips its NPCs with Kits kits, and RunicNPC declares `// Requires: Kits`, so neither framework loads it without Kits |
| **[ZoneManager](https://umod.org/plugins/zone-manager)** | Optional. Only holding NPCs inside a zone uses it |
**Kits and ZoneManager are reported, never installed.** The installer's `doctor` says when either
is missing; you install them from uMod.
<Aside type="caution" title="Do not reload Kits while an event runs">
RunicNPC requires Kits, so both frameworks reload RunicNPC whenever Kits reloads, and every NPC it
had spawned is gone. Placements come back on their own; an event's NPCs do not.
</Aside>
## On a Runic Gateway server
There is nothing to do by hand. RunicNPC is part of the Rust bundle — {platform.games.rust.bundle.tag}
carries RunicNPC {platform.games.rust.bundle.runicnpc} — beside the bridge plugin and the sidecar,
and it arrives the way they do. See [Install the bridge](/docs/rust/install-the-bridge/).
- **The installer** places `RunicNPC.cs` beside the bridge plugin, checked against the bundle's
checksum, and refuses a bundle without it. `doctor --game rust` **fails** when RunicNPC is
missing, and warns when the file was edited by hand. `uninstall` removes `RunicNPC.cs` and keeps
its data.
- **The Pterodactyl egg** places it the same way on every install and reinstall.
Once the server has started, **Admin → Rust servers** shows it as complete. A server without
RunicNPC, or with one older than the bridge needs, reads *Incomplete* with the reason, and every
*Place NPCs* step on it is refused. **Admin → Rust NPC profiles** lists each server's RunicNPC
version and API.
**The first push adopts what the server had.** When the site first pushes profiles to a server,
the profiles that server already had become site profiles for that server alone, so nothing on it
changes. See [NPC profiles](/docs/rust/runicnpc/npc-profiles/).
## Without Runic Gateway
1. Download `runicnpc-<version>.tar.gz` and `SHA256SUMS` from the
[releases page](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust/releases), and check
the tarball: `sha256sum -c SHA256SUMS`.
2. Install Kits from uMod if the server does not have it.
3. Copy `runicnpc/RunicNPC.cs` from the tarball into `oxide/plugins/` or `carbon/plugins/`. The
framework compiles and loads it at once.
4. At the server console, run `rnpc.status`. It should say `navmesh=ready` — a fresh map builds
its navmesh for several minutes after its first boot — and `swap fields: … missing=- added=-`.
5. Grant `runicnpc.place` or `runicnpc.admin` to whoever places NPCs, then `/rnpc place raider`
where you look.
**It comes with examples.** On its first load RunicNPC writes four example kits into Kits' data
file — `rnpc_raider`, `rnpc_campguard`, `rnpc_sniper` and `rnpc_juggernaut`, each where its name is
free and each behind a Kits permission nobody is granted, so no player can claim one. On a server
no site manages it also adds four example profiles: a raider, a camp guard, a sniper and the
Juggernaut, a boss. It then reloads Kits once so the new kits are known. **Nothing is written
again**, even if you delete them.
<Aside type="caution" title="Do not create RunicNPC's data folder yourself">
RunicNPC makes `data/RunicNPC/` on its first load. One made from outside the game — a panel's
file manager, for example — may not be writable by the game.
</Aside>
## Its files
Under `oxide/`, or `carbon/` on Carbon.
| File | What it holds | Who writes it |
|---|---|---|
| `plugins/RunicNPC.cs` | The plugin | The installer, the egg, or you |
| `config/RunicNPC.json` (Carbon: `configs/`) | The caps and the spawn budget — see [Cost and caps](/docs/rust/runicnpc/cost-and-caps/) | You |
| `data/RunicNPC/profiles.json` | The profiles and the faction table, and whether a site manages them | The site, on a Runic Gateway server; otherwise `rnpc.profile` and `rnpc.faction` |
| `data/RunicNPC/placements.json` | The placements | `/rnpc`, the API, and the site's map |
| `data/RunicNPC/routes.json` | The recorded routes | `/rnpc path` |
| `data/RunicNPC/state.json` | Its own bookkeeping: whether the examples were written | RunicNPC |
After editing `profiles.json` or `routes.json` by hand, run `rnpc.reload`.
## After a Rust update
Rust's monthly update can change the scientist RunicNPC is built on. After it:
1. **Wait for the navmesh.** `rnpc.status` says `navmesh=building` while Rust rebuilds it, about
ten minutes on a large map. Placements wait, and spawn when it is ready; a spawn through the
API is refused until then.
2. **Check the swap.** The `swap fields` line should end `missing=- added=-`. Anything else means
Rust's scientist has changed since this RunicNPC was released: update RunicNPC. On a Runic
Gateway server, `update --game rust` or an egg reinstall takes the current bundle.
3. **Check the hooks.** `rnpc.status` names any hook that has never fired as `silent`. One that
stays silent long after players have been on is the first sign Rust renamed it, because
neither framework reports a hook that matches nothing.
In the week before each monthly forced wipe, every new Rust staging build is tried against
RunicNPC, so a release that needs fixing is usually out before the update is.
## Reading `rnpc.status`
<Code
lang="text"
code={[
`RunicNPC ${platform.releases['runicnpc-rust'].replace(/^v/, '')} api=${platform.runicnpc.api} hooks=12 fired=12 silent=0`,
'framework=oxide navmesh=ready swap fields: npc=55/55 brain=32/32 missing=- added=-',
'npcs=14 awake=9 goingHome=0 asleep=5 owners: placement:bandit-1=3 run:42=11',
].join('\n')}
/>
The rest of its answer lists the profiles it refuses and why, the placements waiting and why, the
faction pairs, the caps, and the [cost warning](/docs/rust/runicnpc/cost-and-caps/).

View File

@@ -0,0 +1,68 @@
---
title: NPC placements
description: Placing RunicNPC's NPCs from the site's live map — how a click becomes a placement, and editing, renaming, respawning and removing what is already placed.
---
**Admin → Rust NPC placements** shows one server's RunicNPC placements on its live map, and
places new ones where you click. **Placements live on the server**, not on the site: an admin's
`/rnpc place` in game and this screen edit the same list, and both see each other's at once. So
every read and write here is a live round trip to the game, and a server that is down has nothing
to show.
A server appears in the **Server** list once its RunicNPC can take placements from the site. If
none can yet, the screen says why for each.
## Placing NPCs
**Click the map where they should stand.** The site sends the point — a spot on the map, with no
height — and the server does the rest, exactly as `/rnpc place` would:
- it **puts the point on the ground**, by a ray down onto terrain and rock — never a building or a
tree;
- it **checks the spot against Rust's navmesh**, and refuses a roamer's spot that is off it, with
how far off it is;
- it refuses a point off the map or under water;
- it **names the placement** after its profile and the first free number, `raider-3`.
The form under the map takes what `/rnpc place` takes:
| Field | Means |
|---|---|
| **Profile** | The profiles this server is pushed — see [NPC profiles](/docs/rust/runicnpc/npc-profiles/) |
| **How many** | How many NPCs stand there; all but the first are scattered within 3 m |
| **Respawn (s)** | Seconds after a death before an NPC comes back |
| **Come back** | *each*, after its own death, or *together*, once all are dead |
| **Movement** | The profile's own, `wander`, `monument`, or one of the server's recorded routes. Not shown for a sentry |
| **Radius (m)** | How far a wanderer strays |
| **Keep inside zone** | A ZoneManager zone its NPCs never leave. The server refuses a zone it does not have, or one that does not hold the spot |
**The answer** says the placement's name, where it landed and how high, and the
[cost warning](/docs/rust/runicnpc/cost-and-caps/) for the NPCs the server will then have. If the
spot is on something players built, it says so: if that is destroyed, the NPCs stand on the
nearest navmesh until it is rebuilt.
**A roof or the top of a building is placed in game.** The map only knows the ground; stand on
the roof and use `/rnpc place` or `/rnpc here`.
## What is already placed
Each placement is a pin on the map — yellow, or grey while it waits — and a row in **Placements**:
its name, how many of which profile, how many are alive, the respawn, the movement, its zone and
where it is. Above the list is the cost warning for everything this server runs now.
| Button | Does |
|---|---|
| **Edit** | Change any of the form's fields. Its NPCs are removed and spawn again from the new values |
| **Rename** | Give it a new name. Its live NPCs keep living under it |
| **Respawn** | Remove its NPCs and spawn them again at once |
| **Remove** | Remove the placement and its NPCs, after a second click to confirm |
**A placement can wait.** Its row says why in red — *profile 'guard' is missing*, for example,
because the profile was deleted or is no longer pushed to this server; or its route or zone has
gone; or the map's navmesh is still being built after an update. A waiting placement spawns again
by itself once the thing it waits for is back. A grey note under a row says its NPCs stand
somewhere other than their spot because the ground there went; *Last spawn failed* gives the last
error.
**Recording a route is done in game**, with `/rnpc path` — see
[Commands](/docs/rust/runicnpc/commands/#routes). Once saved, it is offered in **Movement** here.

View File

@@ -0,0 +1,113 @@
---
title: NPC profiles
description: Authoring RunicNPC's profiles and faction table on the site — which servers each profile is for, how the site pushes them, what the first push adopts, and the editor's sections.
---
import { Aside } from '@astrojs/starlight/components';
import Screenshot from '../../../../../components/Screenshot.astro';
**Admin → Rust NPC profiles** is where a Runic Gateway site authors RunicNPC's profiles. There is
no in-game profile editor: on a server a site manages, the profiles and the faction table are the
site's, and the console commands that would change them are refused. Where NPCs stand is a
separate question, answered on [NPC placements](/docs/rust/runicnpc/npc-placements/), in game with
`/rnpc place`, or by an event's *Place NPCs* step.
The screen has four parts: the servers, the profiles, the faction table, and — once there are
any — the profiles a first push replaced.
## Servers
One row per Rust server: its RunicNPC version and API, and when the site last pushed to it, or
why the last push failed. A server without RunicNPC, or with one too old to be managed, shows the
reason instead and is left alone; its events keep Rust's own scientists.
**The site pushes on its own.** Every half-minute it asks each server whether it needs a push —
the first one, a change to its set, a restart, a failure worth retrying, or a quarter-hourly
audit — and pushes only then. A saved profile reaches each server within about half a minute.
**Push now** does it at once, and says what happened: how many profiles went, what was adopted,
and any RunicNPC refused, with the reason.
**A refusal shows under its server.** A push replaces the server's whole set, and RunicNPC keeps
every profile it can accept: one it refuses — a kit that server lacks, say — is listed under the
server in red, and the rest are in use at once.
## The first push adopts what the server had
A server that ran RunicNPC before the site managed it already has profiles, and placements that
use them. So **before the first push, the site reads that server's own profiles and imports them
as profiles for that server alone**, then pushes them back. Nothing on the server changes, and its
placements keep spawning. An adopted profile says *adopted from* its server in the list.
Where a site profile of the same name already covered that server, the site's wins, and the
server's own is kept under **Replaced**, with **Restore** to put it back in use on its server and
**Delete** to drop it.
## Profiles
Each row shows a profile's label and RunicNPC name, the servers it is for, its role, whether it is
a boss or has its own loot, its health, kits and movement, and how its kills count. **New profile**
and **Edit** open the editor below the list.
<Screenshot id="admin-rust-npcs" />
### Which servers
A profile is for **every server** — including servers added later — or for the ones ticked. Each
server is pushed only the profiles that cover it, so two servers can each have a different
`warden`.
### The editor
**Name** is RunicNPC's name for the profile — 1 to 40 of a-z, 0-9, `_` and `-` — and what
`/rnpc place` and an event step use. The rest is in sections, each a group of
[profile fields](/docs/rust/runicnpc/profile-fields/), which says what every field does and its
limits:
| Section | What it sets | Shown |
|---|---|---|
| **Looks** | Names, kits, prefab and role | Always |
| **Moving** | How it moves, its wander radius, and when it sleeps | Not for a sentry, which never moves |
| **Fighting** | Health, damage dealt and taken, aim, vision, ranges, and the health thresholds an event can wait for | Always |
| **Press E** | A line in the player's chat, or a window | A passive profile only |
| **Boss** | The health bar, the lines said in game, and the phases | Any role but passive |
| **Loot** | What the corpse starts with, the rows always rolled, the pool, and the crate | Always; off keeps Rust's scientist loot |
| **Sides** | Faction, its own exceptions, alert radius, turrets, and whether players and it can hurt each other | Always |
| **The kit's extras** | Healing, grenades, melee, rockets and the flamethrower | Always |
**Choosing *Passive* changes two other fields** for you: it stops players hurting the NPC and
makes it stand where it is placed. Choosing another role again sets them back.
**The editor speaks in friendlier units than the file.** Health thresholds, a loot row's chance
and a phase's *At health* are percentages here, and a locked crate's hack time is in minutes; the
file and the API hold fractions and seconds. The site converts both ways.
**Kits are checked when you save.** Every server the profile is for that answers is asked for
its kits, and a kit any of them lacks refuses the save, naming the server and the kit. A server
that does not answer is left to RunicNPC, which refuses the profile there at the next push.
**Kills count** is the site's, not RunicNPC's: how the leaderboard and chat titles count this
profile's kills.
| Choice | Counts |
|---|---|
| **Per server** (the default) | Kills of this name on the server a leaderboard is for |
| **Every server with this name** | Kills of this name on every server |
| **This profile only** | Kills of this profile only, on whichever servers it is pushed to |
**Delete profile** removes it from every server it covered at the next push. Placements that use
it **wait** rather than vanish, and spawn again if a profile of that name comes back.
## The faction table
How factions treat each other, for the whole site, pushed to every server with the profiles. One
row is both ways: *bandits ↔ guards: hostile* makes each hunt the other. A pair that is not listed
is neutral, and a faction is always allied to itself. `scientists` and `animals` are Rust's own; a
profile hostile to scientists fights them, and they only take cover. A profile's own exceptions,
set in its **Sides**, win over the table.
<Aside title="Fighting NPCs is opt-in">
With no faction settings, a profile fights players only. Fighting Rust's scientists, animals or
other profiles costs about what fighting players does — see
[Cost and caps](/docs/rust/runicnpc/cost-and-caps/) — and an NPC only fights what comes within its
chase range of its spot: it never walks into a monument to look for scientists.
</Aside>

View File

@@ -0,0 +1,152 @@
---
title: Profile fields
description: Every field of a RunicNPC profile, by its JSON path — the same path the site's editor, rnpc.profile set, the data file and the API all use — with its limits and what it does.
---
import Ticks from '../../../../../components/Ticks.astro';
import { runicnpcProfileFields } from '../../../../../data/runicnpc.mjs';
export const Fields = ({ group }) => (
<table>
<thead><tr><th>Field</th><th>On the site</th><th>Allowed</th><th>What it does</th></tr></thead>
<tbody>
{Object.entries(runicnpcProfileFields[group]).map(([path, f]) => (
<tr key={path}>
<td><code>{path}</code></td>
<td>{f.site ?? <em>not in the editor</em>}</td>
<td><Ticks text={f.rule} /></td>
<td><Ticks text={f.meaning} /></td>
</tr>
))}
</tbody>
</table>
);
A profile is a named description of an NPC. Its fields are the same wherever a profile is
written, so this one page serves all four places:
- **The site's [profile editor](/docs/rust/runicnpc/npc-profiles/)**, whose sections this page
follows, and whose label for each field is in the second column.
- **The console**, where `rnpc.profile set <name> <field> <value>` takes the path in the first
column: `rnpc.profile set warden ranges.sense 40`.
- **The data file**, `data/RunicNPC/profiles.json`, on a server no site manages.
- **[The API](/docs/rust/runicnpc/api/)**: `RunicNpc_SetProfiles` takes profiles in this shape,
and `RunicNpc_Spawn`'s overrides change any of these fields for one NPC.
The paths are checked against the API's specification on every build. **The site's editor shows
some values in friendlier units**: health thresholds, a loot row's chance and a phase's health as
percentages, and the hack time in minutes. Everywhere else they are fractions and seconds.
**A profile is checked whole when it is saved.** A kit the server does not have refuses the
profile then, not when an NPC spawns; a refused profile is kept, and listed with its reason, but
never spawns.
## Looks
<Fields group="Looks" />
## Moving
<Fields group="Moving" />
## Fighting
<Fields group="Fighting" />
## Press E
<Fields group="Press E" />
A passive profile, as it looks in the file:
```json
{
"names": ["Quartermaster"], "kits": ["outpost_clothes"], "role": "passive",
"movement": { "mode": "stand", "radius": 0 },
"hurtByPlayers": false,
"use": { "mode": "chat", "lines": ["Back again, {player}?", "Supplies are short."], "title": "", "text": "" }
}
```
## Boss
<Fields group="Boss" />
A boss gives no reward of its own. On a Runic Gateway server, an event's reward steps do, and can
name everyone who hurt it.
## Loot
<Fields group="Loot" />
## Sides
<Fields group="Sides" />
**Whom it fights besides players** is decided by its own senses: only factions it is hostile to,
within its sense range of itself and its chase range of its spot, so it never walks into a
monument to look for scientists. Rust's scientists never fight back, by Rust's own rule; they take
cover. Whoever shoots one of RunicNPC's NPCs, it fights back, whatever the table says.
## The kit's extras
<Fields group="The kit’s extras" />
## A whole profile
A roamer that is also a boss, with its own loot, as it looks in the file and through the API:
```json
{
"names": ["Warden", "Old Warden"],
"kits": ["warden_rifle", "warden_smg"],
"prefab": "scientistnpc_roam",
"role": "roamer",
"movement": { "mode": "wander", "radius": 20 },
"health": 250,
"damageDealt": 1.0,
"damageTaken": { "head": 1.0, "body": 1.0, "legs": 1.0 },
"aimCone": 2.0,
"ranges": { "sense": 30, "loseTarget": 40, "chase": 40, "attack": 30 },
"visionCone": -0.8,
"sleepDistance": 160,
"healthThresholds": [0.5],
"faction": "bandits",
"relations": { "scientists": "hostile" },
"alertRadius": 40,
"turrets": "default",
"hurtByPlayers": true,
"hurtsPlayers": true,
"kitUse": { "heal": false, "grenades": false, "melee": false, "rockets": false, "flamethrower": false },
"boss": {
"barDistance": 100,
"announce": "chat",
"spawnLine": "{name} has risen!",
"deathLine": "{name} has fallen to {killer}.",
"phases": [
{ "at": 0.5, "adds": { "profile": "raider", "count": 3 }, "line": "{name} calls for help!" },
{ "at": 0.25, "damageDealt": 1.5, "speed": 1.3, "kit": "warden_heavy", "line": "{name} is enraged!" }
]
},
"use": null,
"loot": {
"start": "rust",
"always": [
{ "item": "scrap", "min": 100, "max": 300, "chance": 1 },
{ "item": "rope", "min": 1, "max": 1, "chance": 0.5 }
],
"pool": {
"pick": 1,
"nothing": 85,
"rows": [
{ "item": "lmg.m249", "min": 1, "max": 1, "weight": 10 },
{ "item": "explosive.timed", "min": 1, "max": 1, "weight": 5 }
]
},
"crate": "locked",
"hackSeconds": 600,
"corpseSeconds": 0,
"dropTable": true
}
}
```

View File

@@ -0,0 +1,83 @@
---
title: sidecar.toml
description: The rust-link sidecar's whole configuration — six keys and the six environment variables that override them — and why the file is written rather than shipped.
---
import { Aside } from '@astrojs/starlight/components';
import { rustSidecarConfig, rustSidecarEnv } from '../../../../data/reference.mjs';
The rust-link sidecar's configuration. Like every sidecar on this platform it is small on
purpose: the sidecar forwards, and policy lives on the site where an administrator can see it.
**One file per Rust server**, because one sidecar serves one server.
## The file is written, not shipped
The sidecar **writes its config on first run** if there is none, with a generated auth token, and
nothing is compiled into the binary. `rust-link-sidecar --print-config --config <file>` resolves
the config exactly as a start would — writing it and generating the token if needed — and prints
the result, **token included**, which is the point.
Which file: `--config <file>`, else `$RUSTLINK_CONFIG`, else `sidecar.toml` in the working
directory. **Relative paths resolve beside the config file**, not the working directory, so a
database configured as `rust-link.db` lives next to its config wherever the service manager
started it. The installer's files are under `/etc/runicgateway/rust/`, or
`%ProgramData%\RunicGateway\rust\` on Windows; the egg's is `rust-link/sidecar.toml` in the server's
directory.
<Aside type="caution" title="Authentication is always on">
A blank token is not "no authentication": it is generated and written back, so the web side is
authenticated from first boot. There is no way to turn it off.
</Aside>
## The keys
<table>
<thead><tr><th>Key</th><th>What it is for</th></tr></thead>
<tbody>
{Object.entries(rustSidecarConfig).map(([name, why]) => (
<tr key={name}><td><code>{name}</code></td><td>{why}</td></tr>
))}
</tbody>
</table>
**`[game].bind` stays on loopback.** There is no token on the game link — the plugin and the
sidecar share a host, and `127.0.0.1` is the authentication. Moving it to a routable address puts
an unauthenticated command channel for your game server on the network. `[web].bind` is the one
that may move, behind TLS and a firewall.
**`[store].retain_days` bounds the sidecar's copy, not the history.** The permanent record — per-wipe
totals that survive a wipe — is in the site's own tables, so shortening it loses recent raw detail
and never a player's history. Keep the sidecar's files out of any wipe script's delete list all
the same: the config holds the token, and the database the recent history.
## Environment variables
Each overrides one key. **An empty variable is ignored**, so a panel can declare one and leave it
blank without blanking the saved value.
<table>
<thead><tr><th>Variable</th><th>Overrides</th></tr></thead>
<tbody>
{Object.entries(rustSidecarEnv).map(([name, key]) => (
<tr key={name}><td><code>{name}</code></td><td><code>{key}</code></td></tr>
))}
</tbody>
</table>
Both lists are checked against the sidecar's own source on every build, so a key or a variable
added upstream turns this page red rather than quietly going undocumented.
## What is *not* in here
- **No audience rules.** Who may see what is the site's, on
[Who sees who is online](/docs/rust/who-sees-who-is-online/).
- **No site URL.** The site reaches the sidecar, never the other way round.
- **No protocol version.** It is compiled in, because a sidecar that could be configured to claim
another protocol would defeat the check.
## Canonical documents
[`sidecar/src/config.rs`](https://gitea.whitlocktech.com/RunicGateway/Rust-Link/src/branch/main/sidecar/src/config.rs)
is the authority;
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§6.2 describes it.

View File

@@ -0,0 +1,68 @@
---
title: The live map
description: The Map tab on each server's page — where the picture comes from, what the layers show and to whom, and why positions are never stored.
---
import { Aside } from '@astrojs/starlight/components';
import Screenshot from '../../../../components/Screenshot.astro';
Each server's public page has a **Map** tab: this wipe's map, with the game's own grid, its
monuments, and layers for everything that moves. It is drawn in the browser from two things the
bridge answers live — the picture, and the positions.
<Screenshot id="rust-map" />
## The picture
**From Rust+, when it is on.** A server with `app.port` set renders its map at boot and keeps the
picture for the Rust+ companion app; the bridge reads that picture and nothing else of Rust+'s, and
the site fetches it once per map and keeps it. **Admin → Rust visibility** says, per server, where
the picture came from, its size and when it was fetched, with **Fetch again**.
**Without Rust+, an admin asks for one**, with **Render now** on the same screen. The game can
render the map on request, but it holds the server's main thread for several seconds while it
does, so it never happens on its own. The
rendered picture is kept on the game host and served again after a restart on the same map; a new
map makes it stale.
The picture says nothing about who plays — it is drawn from the map's seed — so it is always
public. Monument labels follow the in-game map's own; some are hidden by default, and the
visibility screen says how many.
## The layers
Every layer has its own audience, set on
[Who sees who is online](/docs/rust/who-sees-who-is-online/#the-live-map):
| Layer | What moves on it |
|---|---|
| **Monuments & world events** | Cargo, patrol and Chinook helicopters, Bradley, supply drops, locked crates — with how long a hack has left — and RunicNPC bosses placed outside an event |
| **Site events** | The zones, crates and NPCs this site's events placed, while they run |
| **Players** | Connected players, then offline sleepers, by name |
| **Bases** | Tool cupboards and vending machines, **as positions only** — no owner, no authorised list, no shop name |
| **PvP zones** | Dynamic PVP's zones, where they are now |
| **Raid bases** | RaidableBases' live bases, their difficulty, when they despawn, and which an event spawned |
The players layer can never show more than *who is online* does. A linked player always sees
themselves and their online clan mates, unless an operator turns that off.
<Aside type="note" title="Positions are never stored">
The picture passes through the sidecar, and positions are never written to its database or the
site's: the site holds the game's latest answer in memory for a few seconds, so many viewers cost
one ask, and that is all. There is no record of where anybody was to leak later.
</Aside>
## Bounds, and the console
Two keys in [`RunicGateway.json`](/docs/rust/runicgateway-json/), **`MapMaxSleepers`** and
**`MapMaxBases`**, cap how many sleepers and bases one answer carries. Over a bound the layer is cut
short and says so; a read has nobody to refuse, so it is trimmed rather than refused.
`rg.map` at the server console prints the map's key, where the picture came from, its size, whether
a render is running, the game's grid, the size of each layer, and how many map asks there have
been, with the last and the slowest.
## Canonical documents
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§17 is the map on the wire, and §20.7 and §20.12 add its two optional layers.

View File

@@ -0,0 +1,60 @@
---
title: Troubleshooting
description: Rust-side symptoms, what each one means, and where to look — from an install that stops to a site that shows nothing.
---
Start with [Verify the bridge](/docs/rust/verify-the-bridge/): its four checks find which link is
broken. The site-wide symptoms — a `409`, a `401` — are on core's
[Troubleshooting](/docs/administration/troubleshooting/) page. This page is the Rust side.
## Installing
| Symptom | Cause, and the fix |
|---|---|
| The install stops: *already names this server "x"* | The plugin's config names another server. Use that id — or, if the server really is new to the site, remove the config file |
| The install stops: *has both Oxide and Carbon* | A tree mid-migration. Remove the framework you are leaving |
| The install stops: *has neither* | The server has never started with a framework. Install Oxide or Carbon and start it once |
| `doctor`: *not the file that was deployed* | The plugin was edited by hand. `update --game rust` puts the released one back |
| `doctor`: RunicNPC missing | It is required. Reinstall or update; and check Kits is installed, because RunicNPC will not load without it |
| The egg's console prints a new token after every boot | A sidecar older than the first Rust-Link release does this. Reinstall the server |
## Connecting
| Symptom | Cause, and the fix |
|---|---|
| The site says the sidecar is unreachable | The site cannot reach the URL: a loopback bind with the site elsewhere, a firewall — or, on the egg, a sidecar port that is not one of the server's allocations |
| **Test** says `protocol-mismatch` | The site's Rust module and the bridge speak different protocols. Update whichever is behind |
| `doctor`: *plugin connected — no, and the server is running* | The plugin did not compile, or cannot reach its sidecar. The server console names a compile error; the plugin's `Port` must equal the sidecar's game port |
| The sidecar logs *refusing a plugin that names another server* | Two servers dial one sidecar: a plugin's `Port` is another server's game port. Correct that plugin's `Port` and reload it. Nothing it sent was stored |
| `/health` shows `untyped_frames` above zero | The plugin and the sidecar are on different protocols. Move both to one bundle |
| The server is listed but reads stale | It reported once and has not since. Either the site's poll is failing (the site's log) or the sidecar stopped (its own) |
## Features
| Symptom | Cause, and the fix |
|---|---|
| Events refuse every step on a server | `EventsEnabled` is off in its [`RunicGateway.json`](/docs/rust/runicgateway-json/). It ships off |
| A step is refused as over a bound | The server's own bound in `RunicGateway.json` is lower than the step asks for. Steps are refused, never trimmed |
| A permission the site granted does nothing | *not registered here*: no loaded plugin registers that name, so the framework ignores it. Load the plugin. `rg.perms` says what the last sync did |
| A group membership has not landed | The server has never seen that player. It lands on their first connection |
| An event zone's flags do not hold | The ZoneManager helper is missing. Reinstall, or place `RunicGatewayZones.cs` by hand |
| A config save rolled back | The plugin did not come back on the new file. The site shows the log line that says why |
| RaidableBases purchases and raids stop working after a config change | It was reloaded on a running server. Restart the server — see [Optional plugins](/docs/rust/optional-plugins/#raidablebases) |
| *Place a guarded crate* is refused | NpcSpawn is missing — see [Optional plugins](/docs/rust/optional-plugins/#guarded-crate) |
| Chat titles show on the site but not in game | BetterChat is not loaded on that server |
| The map tab has no picture | The server runs without Rust+. Ask for a render from Admin → Rust visibility |
| No names in the feed or on the Online tab | That is the default. [Who sees who is online](/docs/rust/who-sees-who-is-online/) widens it |
## What to send when asking for help
The output of `rg.link` and `rg.hooks` at the server console, `/health` from the game host, and,
where the installer was used, `doctor --game rust`. `rg.hooks` lists which of the plugin's hooks
have fired: both frameworks bind hooks by name with no warning when a name matches nothing, so a
hook Rust renamed on a wipe day shows up there as silence.
## Canonical documents
[`rust-link/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INSTALL.md#troubleshooting)
and
[`rust-link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INTEGRATION.md)
§3 hold the full tables.

View File

@@ -0,0 +1,101 @@
---
title: Verify the bridge
description: The four links between a Rust server and the site, checked in order — the plugin's log, rg.link, the sidecar's /health, and Admin → Rust servers.
---
import { Aside, Code } from '@astrojs/starlight/components';
import platform from '../../../../data/platform.json';
export const P = platform.games.rust.protocol;
A copied file is not a working bridge. Check the four links in the order data travels, the
way [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) describes for
every game; this page has Rust's commands. The first link that fails is the one to fix.
## 1. The bridge plugin loaded
Both frameworks compile and load `RunicGateway.cs` the moment it lands. Oxide logs to
`oxide/logs/`; Carbon to `carbon/logs/Carbon.Core.log`. A good load reads:
<Code code={`RunicGateway was compiled successfully
[Runic Gateway] protocol ${P}, serverId 'main', sidecar 127.0.0.1:7799
[Runic Gateway] connected to 127.0.0.1:7799`} />
The second line is worth reading closely: it is the protocol this plugin speaks, the id the
site will file everything under, and the address it dials. A wrong `ServerId` or `Port` is
visible right here.
If the third line is instead *cannot reach the sidecar: … — retrying quietly until it
answers*, the plugin is fine and the sidecar is not there yet — or `Host` and `Port` in
[`RunicGateway.json`](/docs/rust/runicgateway-json/) point somewhere else. It is printed once
per load and then the plugin keeps trying.
## 2. The server reached the sidecar
At the server console (or over RCON):
<Code code={`rg.link
protocol=${P} serverId=main connected=True depth=0 sent=412 dropped=0 received=38 connects=1 writeErrors=0 bootId=… wipeId=w-20261005T115051Z`} />
`connected=True` is the link. `dropped` above zero means the sidecar was away long enough for
the plugin's queue to fill and shed its oldest lines — the game never waits for it.
`wipeId=none` is a server that has never saved, which is normal for a few minutes after a
fresh wipe.
## 3. The sidecar is healthy
On the game host. `/health` needs no token, so monitoring can use it:
<Code lang="bash" code={`curl -s http://127.0.0.1:8090/health
{"status":"ok","protocol":${P},"plugin_connected":true,"database":"ok","uptime":"2h 5m","last_event":"…","untyped_frames":0}`} />
| Field | Working means |
|---|---|
| `plugin_connected` | `true`. **This is the one value that tells "files copied" from "the bridge works"** |
| `status` | `ok`. `degraded` means the plugin is not connected or the database is unreadable |
| `untyped_frames` | `0`. Anything else means the plugin and the sidecar speak different protocols — see below |
<Aside type="caution" title="untyped_frames above zero">
The link between the plugin and the sidecar has no version handshake, so a mismatched pair is
not refused at connect. The sidecar drops and counts every frame it cannot file instead. The
symptom without this counter is a server plainly up, a sidecar plainly healthy, and a site
showing nothing. Compare `rg.link`'s protocol with `/health`'s, and update whichever is
behind — normally by moving both to one bundle.
</Aside>
## 4. The site is ingesting
On **Admin → Rust servers**, **Test the sidecar** answers *The sidecar answered (protocol
{P})*, and the row reads online with *last seen just now*. The public page at `/rust` lists the
server, and its feed fills as things happen in the world.
Each failure the Test button can report is on
[Connect the site](/docs/rust/connect-the-site/#test-it).
## Three things that look broken and are not
- **Stopping the sidecar does not disturb the game.** The plugin logs *sidecar link lost;
reconnecting* and keeps retrying, into a bounded queue that drops its oldest lines rather
than growing.
- **A plugin started before its sidecar logs one line and goes quiet** until the sidecar
answers.
- **The site renders with every server off.** Lists, counts and last-reported times come from
what the site stored, and the server reads offline.
## On the installer's hosts, one command
```bash
runicgateway doctor --game rust
```
checks the framework, every deployed file, RunicNPC, the required uMod plugins, the service
and `/health` through to *plugin connected*, per server. It exits non-zero when a check
failed, so a monitor can run it. On a Pterodactyl egg there is no shell; the console is the
diagnosis.
## Canonical documents
[`rust-link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INTEGRATION.md)
§3 and
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§5.1 cover diagnosing the link.

View File

@@ -0,0 +1,85 @@
---
title: Who sees who is online
description: Admin → Rust visibility — nothing names a player by default; where an operator widens that, for presence, clan rosters, news in game chat and each live-map layer.
---
import { Aside } from '@astrojs/starlight/components';
**Nothing on the site names who is online unless you choose to show it.** That covers more than
the Online tab: the joins, deaths and chat in each server's feed, and the leaderboard's *last
seen*, all say that a named player was on at a given moment. **How many** players are online is
always shown — a count is never a name.
**Admin → Rust visibility** (`/admin/rust/visibility`) is where an operator widens that, on
purpose. Every setting has a fleet-wide default and a per-server override.
## The audiences
Each setting picks one of three audiences, narrowest last:
| Audience | Who |
|---|---|
| **Everyone** | Anybody, signed in or not |
| **Signed-in members** | Anybody with a site account |
| **Staff only** | Admins and moderators |
## Who is online
The default is **staff only**. It decides who sees a **named** player: the Online tab, and the
feed's [presence kinds](/docs/rust/event-kinds/#presence) — joins and leaves, respawns, deaths,
chat, the per-minute tally, and the death of a RunicNPC boss, which names its killer. Below it,
the public feed carries only what names nobody: a wipe, a start, a shutdown, a world event.
## Clan rosters
Who is in each clan, on every server. The default is **the clan's members and staff**: players
whose linked Rust account is in the clan, plus admins and moderators. Each clan's name, colour,
score and member count are always public.
## News in game chat
Per server: **off**, **in chat**, or **as a popup**. When a news post is published, its title is
said on every server switched on here. A server that is down at that moment is skipped rather
than told late. A popup needs PopupNotifications on that server; one without it refuses the post
and says why.
## The live map
The map's **picture** is always public: it is drawn from the map's seed and says nothing about
who plays. Everything that moves on it is a **layer**, and each layer has its own audience:
| Layer | What it shows | Default |
|---|---|---|
| **Monuments & world events** | Cargo, helicopters, Bradley, supply drops, locked crates, and RunicNPC bosses placed outside an event | Everyone |
| **Site events** | The zones, crates and NPCs this site's events placed, while they run | Everyone |
| **Players** | Where everybody is, with names, and the sleepers | Staff only |
| **Bases** | Tool cupboards and vending machines, as positions only | Staff only |
| **PvP zones** | Dynamic PVP's own zones. Needs Dynamic PVP on the server | Everyone |
| **Raid bases** | RaidableBases' live bases and when they despawn. Needs RaidableBases | Everyone |
**The players layer can never show more than *who is online* does**, whatever it is set to here.
**You and your clan**, on by default, lets a linked player see themselves and their online clan
mates whatever the players layer says.
Per server, this section also says how many monument labels the map has and how many are hidden,
and where the map's picture came from, with **Fetch again**. See
[The live map](/docs/rust/the-live-map/).
<Aside type="note" title="Why the default is the narrowest one">
A feed that says a named player was on at 3 a.m. is a record of somebody's evenings. So nobody's
presence is published until an operator decides it should be, and a new server follows the
fleet's default rather than starting open.
</Aside>
## What this does not cover
Some kinds never reach a public page at any setting: IP addresses, player reports, bans, who
destroyed whose base, and permission changes are [staff-only kinds](/docs/rust/event-kinds/#staff).
They are not on this screen because there is nothing to choose.
## Canonical documents
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
§8.5 sets out why the boundary is the module's, and
[`modules/rust/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/PLAN.md)
§23 records the presence rule.

View File

@@ -60,7 +60,7 @@ for longer sidecar outages at the cost of memory; it never buys correctness.
**`GuildRosterMembersPerLine`** exists because a roster is the only fat frame this bridge
emits — a real 155-member guild measured about 10.8 KB. Rosters are **split** across lines
rather than sent oversized. See [The bridge](/docs/architecture/the-bridge/).
rather than sent oversized. See [Rosters are sets, not signatures](/docs/ultima-online/event-catalog/#rosters-are-sets-not-signatures).
## Canonical documents

View File

@@ -61,6 +61,14 @@ lazily instead. The two buttons there — *Fetch waiting pictures* and *Refresh
have* — exist for the two moments waiting is the wrong answer: you have just linked a shard,
or you have just patched a client.
## After a client update
When you patch the UO client on the shard host, press one more button. Creature portraits,
item pictures and the name table are read from that client, and the site deliberately never
re-reads them on its own — a restart does not, and neither does the installer's `update`.
They keep serving the old artwork until somebody presses *Update* here. It is one round trip
when nothing has changed.
## When the page says something is wrong
Every one of these is a reported state with a reason, not an error. The site keeps serving
@@ -69,8 +77,8 @@ whatever is already imported in all of them.
| What you see | What it means |
|---|---|
| **The shard is busy with another client-file request** | Not a fault. The shard serves one of these at a time, and an import — or the item-picture pass refilling itself — is holding it. It frees itself. |
| **The shard is not answering for client files** | The ordinary bridge problem: see [The shard connection](/docs/administration/the-shard-connection/). |
| **…set `AssetsEnabled` on the shard** | The asset plane is switched off in [`Bridge.cfg`](/docs/reference/bridge-cfg/). It is a separate switch on purpose — turning it on is consenting to the website reading this host's client files. |
| **The shard is not answering for client files** | The ordinary bridge problem: see [The shard connection](/docs/ultima-online/the-shard-connection/). |
| **…set `AssetsEnabled` on the shard** | The asset plane is switched off in [`Bridge.cfg`](/docs/ultima-online/bridge-cfg/). It is a separate switch on purpose — turning it on is consenting to the website reading this host's client files. |
| **The shard host cannot render images** | A Linux host with no `libgdiplus`. Names are unaffected, because they have no pixels in them. |
| **Waiting for you: *n* pictures … no longer offered** | The shard stopped offering artwork this site holds. A deletion is never silent here; it waits for you to approve or dismiss it. |
@@ -81,7 +89,7 @@ cannot read a single sprite.
`sudo apt-get install libgdiplus`, or `dnf install libgdiplus`. `runicgateway doctor` checks
for it, and Windows shard hosts need nothing. See
[Requirements](/docs/getting-started/requirements/).
[what the shard host needs](/docs/ultima-online/connect-a-servuo-shard/#what-the-shard-host-needs).
</Aside>
## What it will not do

Some files were not shown because too many files have changed in this diff Show More