wtclaude
c89e818dbf
Asset Bridge phase 1 (docs/link/v8.md §16). Sidecar half: RunicGateway/link#41. Docs half: RunicGateway/docs#236. The transport for protocol 8, plus phase 0's validator promoted into the overlay and extended to animations — which is where the interesting part is. ## 357 of the 1,144 "decodable" bodies are wrong pictures, on a STOCK client Phase 0 measured the art path and left the animation half unbuilt. It has the same defect, and it is worse: `GetAnimation` decodes through `new MemoryStream(m_StreamBuffer, false)` — the whole shared buffer, not the `length` bytes just read into it — so a truncated or absent record does not even hit end-of-stream. It sails on into the previous animation's bytes. Measured directly, because no count could tell: | Decode body 320 (`lookup 22638982, length 0`) straight after… | Comes back | |---|---| | body 12, the dragon | the dragon, 176x167, identical hash | | body 34, the wolf | the wolf's dimensions, 35x34 | | body 400, the human male | the human, 27x63, identical hash | The catalogue is **787 bodies, not 1,144**. Importing the other 357 would have written duplicate creature portraits into the site showing whichever body the walk decoded before them. The record walk refused **0** real bodies on the stock client — the false-refusal measurement §4.5 says the boundary depends on. ## And four of the twelve player bodies, not six §5.2 listed the elf ghosts (607, 608) as decoding. Their index entry is `length 0`; what came back was the elf female at her exact dimensions, because 606 is what the walk decoded immediately before. Confirmed the same way — 607 after the dragon is the dragon. Phase 4's UOP decoder now covers eight ids rather than six. ## What is here - **`overlay/Scripts/Custom/Bridge/BridgeAssets.cs`** — the plane. Accepts on the Core thread, hands off to a dedicated asset worker, returns immediately. Three rules, all answering a specific failure: - **one slot**, second request answered `bridge.busy` (425). `Emit`'s queue is bounded in *lines*, so 10,000 queued 200 KB replies is 2 GB of shard memory; the bound that holds is flow control, on the side where the memory is. - **byte budgets** (`AssetBatchBytes`, 512 KiB) under the sidecar's new 1 MiB cap. The factor of two is load-bearing: a page always admits its first item, so it may overshoot by one, and the headroom is what makes that land on the wire. - **replies, never events** — no `reqId`, no answer. An uncorrelated frame is an event by definition, and §3.1 is why none of this may be one. - **`PageBuilder`** — one paging envelope (`more`/`cursor`/`cut`) for all five families that will page, defined before the first one needs it. `cut` matters: "short page" has three meanings and only `end` means finished. - **`assets.sources`** — stage 1 of the import gate, its first user. - **`BridgeAssetValidator.cs`** — promoted from `tools/`, plus `ResolveAnimation` (the never-sweep-file-types rule as code, with no loop and no fallback), `AnimationRecordSane` and the frame walk. - **`EXTRACTOR_VERSION`**, **`overlay.toml` protocol 7 → 8**, `AssetsEnabled`. ## Hashing had to come off the request path §6's gate is (size, mtime) first, hash only when those differ. The first call has nothing cached, so that still means hashing 1.06 GB — inside the sidecar's 10 s reply timeout it does not fit. So hashes are computed on their own thread (deliberately not the single-slot worker, which would answer every status poll `bridge.busy` for the whole pass) and the reply carries `hashing`/`complete`. Measured on the real rig: first call instant with `sha256: null`, second call **44 ms** with every hash present. ## Verified on the wire, not just compiled Real ServUO 57.4 + the real sidecar + the real client. `GET /assets/sources` → 200, `X-UOLink-Version: 8`, `imaging: {ok: true}`, and §4.6's diagnostic firing on a live client: `artDataFile: artlegacymul.uop`, with `art.mul` and `artidx.mul` both carrying `shadowedBy`. Live events kept flowing through the new capped reader with no warnings. Not exercised live: the disabled-plane 403 and the busy 425 (both unit-tested on the sidecar side; the shard halves are a config read and a lock). - [x] AI-assisted — Claude Code (Opus 5) Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
Runic Gateway — ServUO Plugin
The C# ServUO side of the Runic Gateway bridge. The shard emits newline-delimited JSON over a loopback TCP socket to the Rust sidecar (RunicGateway/link), which owns the WebSocket the website consumes.
ServUO plugin (C#, net48) ──loopback TCP, newline-JSON──► Rust sidecar ──WebSocket/JSON──► website
(Core-thread reads) ◄──inbound commands─────────────┘ (owns WS, auth, buffering, fan-out)
>>> THIS REPO <<< (RunicGateway/link)
The shard never speaks WebSocket. Every world read happens on the Core thread; the socket is touched only by a dedicated writer thread draining a bounded queue.
Documentation
All project documentation lives in the central RunicGateway/docs repo,
under link/ (design docs,
integration guide, protocol spec, research — with full history preserved).
Layout
| Path | What |
|---|---|
overlay/ |
Mirrors the ServUO server root. Everything here — and only this — copies over an install. |
patches/ |
Unified diffs against stock ServUO for files we must modify rather than add. |
tools/ |
Never deployed. Test scaffolding (C# probes + PowerShell stub sidecars) and anything else that must not reach a server. |
deploy.ps1 |
Developer tool — copies overlay/ from this working tree into a server root. -Verify diffs instead of writing. Operators use the installer; see Deploy. |
overlay.toml |
Release metadata: the wire-protocol version this overlay speaks, and its ServUO compatibility. Read by CI into the release manifest — see Releases. |
.gitea/workflows/release.yml |
Publishes runicgateway-overlay-<ver>.tar.gz on every merge to main. |
| INTEGRATION.md | Website integration guide — the WebSocket feed, REST endpoints, auth, event catalog, and examples. |
| PLAN.md | Implementation plan, measured performance budget, and the full data catalog. |
| RESEARCH.md | Original source-level research. Partly superseded — see the corrections table in PLAN.md §8. |
| SHARD_PREREQS.md | Repairs the target shard needed before any of this could load. |
Anything under overlay/ is authoritative. Do not edit files in the server tree directly — edit here and deploy.
Sidecar & deployment
The Rust sidecar is the other half of the bridge and lives in RunicGateway/link. The two are deployed together — by the installer, in one run — but built independently:
- This plugin is deployed as source:
overlay/is copied into the ServUO server root and ServUO compiles it at boot (Scripts.csproj; see Phase 0). There is no CI build — it cannot be compiled standalone without the ServUO reference assemblies. CI publishes a source tarball, which is what the installer fetches and syncs; see Releases. - The sidecar is a standalone Rust binary, released from its own repo and installed from that release.
The only coupling is the loopback JSON protocol (the shard dials out to the sidecar on
127.0.0.1). Compatibility is a protocol concern, not a build-order one: keep the event/command
catalog in sync across the two repos (canonical spec: PLAN.md
§5/§7 and INTEGRATION.md).
A wedged or absent sidecar cannot stall the shard, so the plugin can be deployed before, after, or
without the sidecar running.
Deploy
On a shard, use the Runic Gateway installer.
One binary syncs this overlay from the release tarball below, offers the patch tier, installs the
uo-link sidecar as a service, and prints the values your website needs — cross-platform, with a
doctor afterwards to tell a copied file from a working bridge:
sudo ./runicgateway-installer-linux-x86_64 install
Guide: installer/INSTALL.md. To place the overlay yourself instead — a host that cannot run the binary, or you want to see every file land — Appendix A2 is the same copy done by hand, and stays supported.
deploy.ps1 — the developer path
deploy.ps1 deploys from a working tree, which is what you want while writing plugin code and
is the one thing the installer cannot do (it deploys from a release):
.\deploy.ps1 -ServerPath <servuo> -Verify # show what would change
.\deploy.ps1 -ServerPath <servuo> # write
It is Windows-only and stays developer-facing; it never installs the sidecar, registers a service, or checks the protocol pairing. Nothing shipped to an operator depends on it.
Releases
Every merge to main that carries a releasable conventional commit (feat:, fix:, perf:, or a
breaking change — a docs:/chore:-only merge deliberately cuts nothing) publishes a Gitea release:
runicgateway-overlay-<ver>.tar.gz
└── runicgateway-overlay/
├── manifest.json
├── overlay/ # exactly what deploy.ps1 would copy
└── patches/ # the opt-in stock-file diffs + their companion sources
SHA256SUMS
This is a source tarball, not a build — nothing here is compiled. It exists so the installer can deploy the plugin onto a shard host that has no git and no Gitea credentials.
manifest.json is what makes the tarball self-describing:
{
"component": "servuo-plugins-overlay",
"version": "0.1.0",
"commit": "968b526…",
"protocol": 3,
"servuo": { "min_version": "57.4", "patches_verified_against": "57.4" },
"files": { "overlay/Config/Bridge.cfg": "32718424…", … }
}
protocolcomes fromoverlay.tomland is the plugin half of the compatibility contract. The plugin announces no version on the wire and none is queryable before ServUO boots, so this declaration is the only way the installer can check it against the sidecar'sPROTOCOL_VERSIONbefore an operator installs the pair. When the protocol changes, bump it in the same PR that changes the emitters.filescarries a SHA256 per shipped file, so a deployment can later tell "an operator edited this" from "the overlay moved on".
The version is derived from git tags — there is no version to maintain by hand and no bump commit,
so this workflow never pushes to main.
The tarball is byte-reproducible for a given tree (tar --sort=name, pinned mtime and ownership), so
its checksum changes only when its contents do.
Status
| Phase | State |
|---|---|
0 — build fix (Scripts.csproj) |
done, verified end-to-end |
1 — transport (BridgeLink) |
done, acceptance in PLAN.md §11 |
2 — event streams (BridgeEvents) |
done, acceptance in PLAN.md §12 |
3 — sweeps (BridgeSweeps) |
done, acceptance in PLAN.md §13 |
4 — request/response (BridgeRequests) |
done, acceptance in PLAN.md §14 |
5 — [link account linking (BridgeAccountLink) |
done, acceptance in PLAN.md §15 |
6 — town-crier inbound (BridgeTownCrier) |
done, acceptance in PLAN.md §16 |
7 — PlayerVendorSale core event (patches/ + BridgeVendorSale) |
done, acceptance in PLAN.md §17 |
Every phase on the ServUO side is complete. Phases 0–6 are drop-in (overlay/); Phase 7 is the one
core change, shipped as patches/.
Cheat-detection signals are not a separate phase — they are folded into the streams above:
cheat.fastwalk, audit.set, audit.command, and vendor.sale (buyer + owner for laundering detection).
Phase 0 — what it fixes
ScriptCompiler.Compile() runs dotnet build Scripts/Scripts.csproj -c Release, prints the output, and never checks the exit code, then Assembly.LoadFrom("Scripts.dll") and returns true. Because that build passed no Platform, MSBuild defaulted to AnyCPU, and Scripts.csproj gated both OutputPath and DefineConstants on Configuration|Platform == Release|x64. So:
- the DLL landed in
Scripts/bin/Release/while the core loadsScripts.dllfrom the base directory, and TRACE;NEWTIMERS;ServUOwent undefined, so XmlSpawner compiled its non-ServUO branches.
Runtime script compilation therefore had no effect, silently. overlay/Scripts/Scripts.csproj conditions both property groups on Configuration alone.
Server.csproj is deliberately left alone: nothing under Server/ uses those symbols, and giving it OutputPath=..\ would make the boot-time build try to overwrite the running ServUO.exe.
The plugin (Phase 1)
overlay/Scripts/Custom/Bridge/:
| File | Responsibility |
|---|---|
BridgeConfig.cs |
Reads Config/Bridge.cfg in Configure(), before World.Load. |
BridgeJson.cs |
Outbound JSON by hand (Core thread, so no reflection serializer). Inbound via JavaScriptSerializer. |
BridgeLink.cs |
The socket. Link thread owns it; a bounded drop-oldest queue fronts it; a reader thread marshals inbound lines to the Core thread. |
BridgeBoot.cs |
Lifecycle, inbound dispatch, [bridge status|reload|ping]. |
BridgeEvents.cs |
EventSink subscriptions (Phase 2). Read-only, player-filtered, never emits secrets. |
BridgeSweeps.cs |
Polled streams (Phase 3): vitals, house decay on transition, economy supply. Core-thread timers. |
BridgeProfile.cs |
Read-model builders (Phase 4): full character profile, account roster. Core-thread reads. |
BridgeRequests.cs |
Inbound request handlers (Phase 4): char.request, account.roster, vendor.snapshot, with bridge.error replies. |
BridgeAccountLink.cs |
[link account linking (Phase 5): one-time code, link.confirm, WebsiteUserId account tag. |
BridgeTownCrier.cs |
Town-crier news (Phase 6): inbound towncrier.add / remove into the global crier list, with abuse caps. |
Emit() is called from the Core thread. It enqueues and returns — it never touches the socket, never blocks, never allocates a syscall. A wedged or absent sidecar cannot stall the shard, and that is the property everything else depends on.
Testing
tools/stub_sidecar.ps1 is a loopback listener that logs every line the shard sends. Run it, boot the shard, watch server.hello arrive. It survives a just-killed instance (SO_REUSEADDR) and won't die on a transient error.
.\tools\stub_sidecar.ps1 -Port 7788 -Log .\sidecar.log
tools/stub_sidecar_request.ps1 additionally sends inbound requests (char.request, account.roster, vendor.snapshot, plus an error case) right after the shard connects, and logs the replies — the harness used to validate Phase 4.
Note: the throwaway PowerShell sidecars are fragile — they get reaped and contend on their log file. The real Rust sidecar (RunicGateway/link) replaces them; don't read their flakiness as a shard problem. The shard buffers non-perishable events through any outage and reconnects on its own (observed reconnecting 5× unattended in one session).
tools/scaffolding/ holds the world seeder and the performance probe. Neither is deployed — deploy.ps1 only copies overlay/. They produced the budget in PLAN.md §1. See tools/scaffolding/README.md.
License
Runic Gateway is free software, licensed under the GNU General Public License v3.0 or later — see LICENSE.md.
Copyright (C) 2026 Runic Gateway
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version. It is distributed WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
Contributions are welcome — please read CONTRIBUTING.md (note the AI-usage disclosure requirement) and our Code of Conduct. Report vulnerabilities privately per SECURITY.md.