Compare commits
38 Commits
6046214d71
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| f38dec2ac4 | |||
| 080f9827b8 | |||
| 7ac19a791c | |||
| b8306dcdaf | |||
| 08a4973bde | |||
| 8b8896f54b | |||
| e5ec81b172 | |||
| e0b2885cd7 | |||
| c1b38081f5 | |||
| dff4232491 | |||
| caab3476eb | |||
| 70b31302b7 | |||
| 094c606238 | |||
| 338cc6f3de | |||
| d6d5a70ed4 | |||
| 04e8c14d1f | |||
| bda4662a89 | |||
| fcc1a06361 | |||
| 769d213c80 | |||
| 8701126d64 | |||
| e7bbc250a5 | |||
| d59c993430 | |||
| 9b11c5cb99 | |||
| 06a8892895 | |||
| a918e9248e | |||
| abf7dceb06 | |||
| c47e9c1aa4 | |||
| 4f38e29ad7 | |||
| 56473d4d51 | |||
| ec65b2d5aa | |||
| 297cc83db5 | |||
| ecc556d7ac | |||
| fe86fc369d | |||
| 9b28c95305 | |||
| aad3a37c09 | |||
| 75c8ffc07a | |||
| a100195e7b | |||
| 4426d3e339 |
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
10
DEPLOY.md
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
12
README.md
@@ -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.
|
||||
|
||||
@@ -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: [
|
||||
|
||||
@@ -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.",
|
||||
|
||||
@@ -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": {
|
||||
|
||||
BIN
public/screens/admin-rust-npcs.webp
Normal file
|
After Width: | Height: | Size: 61 KiB |
BIN
public/screens/admin-rust-permissions.webp
Normal file
|
After Width: | Height: | Size: 86 KiB |
BIN
public/screens/app-rust-account.webp
Normal file
|
After Width: | Height: | Size: 89 KiB |
BIN
public/screens/app-rust-map.webp
Normal file
|
After Width: | Height: | Size: 284 KiB |
BIN
public/screens/app-rust-server.webp
Normal file
|
After Width: | Height: | Size: 173 KiB |
BIN
public/screens/rust-feed.webp
Normal file
|
After Width: | Height: | Size: 75 KiB |
BIN
public/screens/rust-leaderboard.webp
Normal file
|
After Width: | Height: | Size: 57 KiB |
BIN
public/screens/rust-map.webp
Normal file
|
After Width: | Height: | Size: 111 KiB |
BIN
public/screens/rust-servers.webp
Normal file
|
After Width: | Height: | Size: 44 KiB |
@@ -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(
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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.`);
|
||||
|
||||
@@ -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
@@ -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
@@ -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'));
|
||||
@@ -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');
|
||||
|
||||
@@ -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',
|
||||
);
|
||||
|
||||
@@ -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">
|
||||
|
||||
37
src/components/GameExample.astro
Normal 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>
|
||||
112
src/components/GameFeatures.astro
Normal 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>
|
||||
@@ -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' },
|
||||
];
|
||||
|
||||
@@ -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>
|
||||
|
||||
21
src/components/Signature.astro
Normal 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})`} />
|
||||
63
src/components/SupportedGames.astro
Normal 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>
|
||||
35
src/components/Ticks.astro
Normal 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
|
||||
)}
|
||||
@@ -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);
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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
@@ -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/',
|
||||
};
|
||||
@@ -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}`)]);
|
||||
});
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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/).
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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/).
|
||||
|
||||
@@ -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.
|
||||
|
||||
108
src/content/docs/docs/rust/connect-the-site.mdx
Normal 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.
|
||||
106
src/content/docs/docs/rust/event-kinds.mdx
Normal 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.
|
||||
104
src/content/docs/docs/rust/events-zones-and-rewards.mdx
Normal 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.
|
||||
102
src/content/docs/docs/rust/index.mdx
Normal 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 |
|
||||
161
src/content/docs/docs/rust/install-the-bridge.mdx
Normal 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.
|
||||
79
src/content/docs/docs/rust/linking-steam-accounts.mdx
Normal 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.
|
||||
76
src/content/docs/docs/rust/mod-config.mdx
Normal 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.
|
||||
93
src/content/docs/docs/rust/optional-plugins.mdx
Normal 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.
|
||||
93
src/content/docs/docs/rust/permissions-and-groups.mdx
Normal 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.
|
||||
74
src/content/docs/docs/rust/runicgateway-json.mdx
Normal 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.
|
||||
362
src/content/docs/docs/rust/runicnpc/api.mdx
Normal 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>
|
||||
104
src/content/docs/docs/rust/runicnpc/commands.mdx
Normal 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.
|
||||
79
src/content/docs/docs/rust/runicnpc/cost-and-caps.mdx
Normal 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.
|
||||
75
src/content/docs/docs/rust/runicnpc/index.mdx
Normal 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 |
|
||||
115
src/content/docs/docs/rust/runicnpc/install.mdx
Normal 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/).
|
||||
68
src/content/docs/docs/rust/runicnpc/npc-placements.mdx
Normal 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.
|
||||
113
src/content/docs/docs/rust/runicnpc/npc-profiles.mdx
Normal 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>
|
||||
152
src/content/docs/docs/rust/runicnpc/profile-fields.mdx
Normal 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
|
||||
}
|
||||
}
|
||||
```
|
||||
83
src/content/docs/docs/rust/sidecar-toml.mdx
Normal 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.
|
||||
68
src/content/docs/docs/rust/the-live-map.mdx
Normal 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.
|
||||
60
src/content/docs/docs/rust/troubleshooting.mdx
Normal 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.
|
||||
101
src/content/docs/docs/rust/verify-the-bridge.mdx
Normal 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.
|
||||
85
src/content/docs/docs/rust/who-sees-who-is-online.mdx
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||