# Asset Bridge (Protocol 8) — client assets without UOFiddler **Call it the Asset Bridge.** That is the name for this work everywhere — commits, PR titles, branches (`feat/asset-bridge-p`), and conversation. The protocol number is **8** and this file is `docs/link/v8.md`. **Status:** Design of record, **phases 0-4 complete** (§16). Approved in principle 2026-09-09 (architecture, asset scope, built-in cliloc decoder, atlas cleanup); refined 2026-09-10 (one direction not five, ServUO's own decoders, the UOP reader, the libgdiplus requirement). The phase 0 spike ran on 2026-09-10 and its findings are §4.5-§4.7 -- §4's decision stands, and the response to a malformed record is now measured rather than proposed. Phase 4 built the one decoder §4.3 reserved, and §4.9 is what it measured: **two** of the eight player bodies it was scoped to exist at all, and the same fallback found **233** other bodies, taking the catalogue to **1,022**. **Nothing in §17 is open.** **Supersedes the manual half of:** `../website/UOFIDDLER.md` (deleted in phase 3, once creature art stopped needing it), [`../website/CLILOCS.md`](../website/CLILOCS.md) §Converting, [`../website/SPAWN_ATLAS.md`](../website/SPAWN_ATLAS.md) §Artwork and §Configuring the tree. Two features on this platform read data that only exists inside a UO client, and today both reach the site by hand: the operator installs UOFiddler, converts `Cliloc.enu` on their own desktop, exports sprites one at a time from a GUI, hand-writes a slug→filename JSON map, and copies the result to the server. A third — the spawn atlas — avoids UOFiddler but pays a different price: the **website** must be able to read the shard's ServUO tree directly, over a bind mount or a shared volume. This protocol deletes all three arrangements. The shard already has everything, and the bridge already goes to the website. --- ## 1. The premise, which turns out to be free **A ServUO shard cannot boot without a UO client installation.** It reads maps, statics, tiledata and multis out of `.mul`/`.uop` files, and `Config/DataPath.cfg` is where an operator declares where those live — *required* on Linux, auto-detected from the registry on Windows. At runtime the resolved directories sit in `Server.Core.DataDirectories`, a public static the plugin can read on any shard, with no new configuration and nothing for an operator to set up. So the files the operator has been converting on their desktop are already on the shard host, in a directory the shard already knows the path of, in a process the bridge already runs inside. Everything below follows from that. ### 1.1 What was measured, not assumed Against this machine's ServUO 57.4 tree (`C:\Users\colby\Desktop\ServUO`) and client (`D:\Games\Electronic Arts\Ultima Online Classic`, 3.5 GB), loading **ServUO's own `Ultima.dll`** — the assembly `overlay/Scripts/Scripts.csproj:39` already carries a `` to: | Call | Result | |---|---| | `Art.GetStatic(0…16383)` | 16,384 decoded, 0 errors | | `Art.GetStatic(16384…65535)` | 32,766 decoded, 1 empty, 16,385 clean out-of-range errors | | `Art.GetLand(0…16383)` | 16,384 decoded, 0 errors | | `Animations.GetAnimation(0…2047, 0, 1)` | **1,144** bodies with a decodable first frame, 904 empty, 0 errors — of which **357 are wrong pictures**; see §4.8 | | `Hues.GetHue(33)` | loads | | `Bitmap.Save(…, Png)` | 852-byte PNG from one creature frame | | `Gumps.GetGump(2)` | **hard crash** — `AccessViolationException`, process exit `0xC0000005` | | `new StringList("enu", "Cliloc.enu")` | throws — `Non-negative number required` | Two of those rows are load-bearing and are dealt with in §4 and §9. The rest say the same thing: **most of the extraction this protocol needs is already implemented, already compiled, and already referenced by the plugin's own build.** **Every "decoded" count in that table is an upper bound, not a measurement**, and phases 0 and 1 spent themselves establishing by how much. `Ultima` reports success for records that do not exist (§4.5, §4.8), so the honest reading of the animation row is 787 bodies with art, 357 that return the previously-decoded body's bitmap, and 904 that return nothing. The static and land rows are overstated the same way. This is not a table to size anything from any more — §11 is. Depth, for §11's sizing: body 400 (human male) has **35 actions × 5 directions = 1,050 frames**. One body. §5.1 cuts that by exactly 5×. --- ## 2. Architecture: the shard extracts, the sidecar forwards, the website decides ``` UO client files (operator's own, on the shard host) │ read by the plugin, off the Core thread ▼ ServUO shard (servuo-plugins/) ← decodes; resolves body ids; hashes │ loopback JSON, request/reply, one batch outstanding at a time ▼ uo-link sidecar (link/) ← forwards bytes; decides nothing │ REST, bearer-token auth, X-UOLink-Version: 8 ▼ website (module-uo/) ← stores, names, gates, serves ``` This is deliberately the *only* arrangement that keeps [the bridge's standing rules](PLAN.md) intact: - **The sidecar stays a dumb forwarder.** It moves opaque assets and decides nothing about them — no audience, no projection, no capability advertisement. Putting the decoders in Rust would have meant the sidecar deciding what an asset *is*, on top of re-deriving in Rust what is already compiled next door in C#. - **Access control stays on the website**, which has the auth machinery and the admin forms. - **The shard is still never network-reachable.** Nothing here opens a port; the plugin answers requests on the connection it already dialled out on. ### 2.1 Why not the sidecar, and why not the operator's desktop A Rust extractor in the sidecar would need ports of: the Mythic cliloc decompressor, `FileIndex` (including UOP), the ARGB1555 run-length frame decoder, `Body.def`/`Bodyconv.def` translation, `Hues.mul`, and a PNG encoder — weeks of work to re-derive what §1.1 shows already runs. It also cannot do §8: resolving a creature slug to a body id requires being inside ServUO. Automating on the operator's desktop (shipping the converter with the installer) removes UOFiddler but keeps a manual step and still cannot do §8. It was considered and rejected. --- ## 3. The transport, and the three traps in it ### 3.1 Assets go over the request/reply path, never the event path `link/sidecar/src/app.rs:122` persists **every** non-`pong` event into the SQLite store *and* broadcasts it to every WebSocket subscriber. An asset stream on that path would grow the sidecar's store without bound and fan megabytes out to every connected client, forever. `rpc.rs`'s `try_route` consumes a correlated reply and `continue`s **before** either of those happens. So an asset batch is a reply, not an event. This is not a new mechanism — it is the one `char.request`, `account.roster` and `vendor.snapshot` already use. ### 3.2 One batch outstanding, always `BridgeLink.Emit()` enqueues onto a **bounded drop-oldest** queue (`Bridge.QueueCap`, default 10,000). It counts **lines, not bytes** — a design that is correct for live events and dangerous for bulk transfer, because 10,000 queued 200 KB replies is 2 GB of shard memory. The rule that makes this safe is flow control, not a bigger queue: **the website requests batch *n+1* only after batch *n* has arrived.** Queue depth stays at approximately one. A dropped or lost reply simply times out and the batch is re-requested, which is safe because reading a client file is idempotent and has no world side effects. **Phase 1 made that a rule the shard enforces rather than one the website is trusted to follow.** The asset plane has a **single slot**: a request arriving while one is in flight is answered `bridge.busy` — which the sidecar already maps to 425 — and runs nothing. The bound belongs on the side where the memory actually is; a documented convention would have held right up until the first website bug, and its failure mode is the 2 GB above. The alternative considered was serialising in the sidecar, so a second caller waits instead of being refused. It was rejected because a waiter spends the website's own 12 s timeout doing nothing, and because it leaves the shard itself unguarded against anything that is not that one sidecar. What this costs, and it is deliberate: **a status poll shares the slot with a batch**, so polling during a long import is answered 425 until the batch lands. That is honest — this plane really does do one thing at a time — and it is why the one genuinely long operation on it, hashing 343 MB of client files, is explicitly *not* a job on this worker (§6). ### 3.3 The size ceilings are already fixed, and one of them is missing | Limit | Value | Where | |---|---|---| | Sidecar waits for a shard reply | **10 s** | `rpc.rs` `REPLY_TIMEOUT` | | Website waits for the sidecar | **12 s** | `module-uo/server/utils/uoLinkClient.js` `TIMEOUT_MS` | | Sidecar → shard line | 1 MiB | `BridgeLink.cs:283` | | **Shard → sidecar line** | **1 MiB** | `shard.rs` `MAX_INBOUND_LINE_BYTES` — **added in phase 1**; it was unbounded | | **Batch budget** | **512 KiB encoded** | `Bridge.AssetBatchBytes` — **added in phase 1** | The first two bound a batch: it must decode, encode, serialise and cross the wire inside ten seconds. The last is a gap this protocol must close — an unbounded `read_line` facing a component that is now deliberately sending large lines is a memory-exhaustion shape we would be inventing ourselves. **Protocol 8 adds an explicit inbound line cap to the sidecar**, set above the largest legal batch and rejecting rather than buffering past it. Batches are therefore sized by bytes, not by count, with the emitter cutting a batch short when it would exceed the cap. Base64 costs 33%; the budget must be stated in encoded bytes. **The two numbers, settled in phase 1: a 512 KiB batch budget under a 1 MiB line cap.** The cap is symmetric with the one the shard has always applied to its own inbound lines, so both directions of this link read the same. The factor of two between them is load-bearing rather than cautious: a page always admits its **first** item even when that item alone exceeds the budget, because the alternative is an oversized item being skipped for the budget on every page forever and its family never making progress. The headroom is what makes that overshoot land on the wire instead of being rejected by the cap. An over-long line is **discarded and the connection kept**, which is what `BridgeLink.cs` has always done in the other direction. Tearing the link down would take the live event feed with it over a single malformed frame, and the reply that was lost simply times out and is re-requested — safe, because reading a client file is idempotent. ### 3.4 One paging envelope, defined once Five of the families in §14 page: clilocs (phase 2), the body catalogue (3), statics and land (5), deep animation keys (6) and the ServUO tree files (7). Left to themselves that is five chances to invent five slightly different shapes, and the website would have to learn each one — so phase 1 defines the envelope before the first family needs it, and `assets.sources` is its first user even though it has nothing to page. ``` "files": [ … ], // the array, named by the family "more": true, // ask again, with this cursor "cursor": "s:4104", // opaque to everyone but the shard; absent when more is false "cut": "budget" // budget | end | limit — WHY the page stopped ``` `cut` is the field that is easy to leave out and expensive not to have. "This page is short" has three different meanings — the source ran out (`end`), the byte budget was spent (`budget`), or the family stopped at a limit of its own (`limit`) — and **only the first means the import is finished.** A website that had to infer completion from an item count would resume from the wrong place the first time a page happened to land exactly on a boundary. The cursor is deliberately **opaque and shard-defined**. The shard is the only side that knows how its own walk is ordered, and a cursor the website could parse is a cursor the website would eventually construct. The budget is counted in **UTF-8 bytes**, not characters and not items. Characters would undercount every non-ASCII byte in a cliloc row, and the ceiling this has to live inside — §3.3's line cap — is measured in bytes. --- ## 4. The decoders are ServUO's own — decided, and the crash is narrower than it looked **We call ServUO's vendored `Ultima` (decided 2026-09-10).** No decoders are reimplemented. `overlay/Scripts/Scripts.csproj:39` already references the project, so the art half of this protocol costs plumbing rather than pixel code, and only §9's cliloc decompressor is written from scratch. The reason that is safe, rather than merely cheap, is a distinction §1.1 did not draw at first. ### 4.1 The crash lives on one code path, and nothing we call uses it `Gumps.GetGump(2)` does not fail — it **corrupts the process**: `AccessViolationException`, exit `0xC0000005`. That is a corrupted-state exception, uncatchable by an ordinary `try/catch` on .NET Framework 4.8, so in-process on a live shard it is a crash with players on it. That much is alarming, and on its own it looked like an argument against using this library at all. It is not, because of how the three decoders construct their `FileIndex`: | Decoder | UOP file | `hasExtra` | Probed | |---|---|---|---| | `Art` | `artLegacyMUL.uop` | **false** | 49,150 statics + 16,384 land tiles, **0 faults** | | `Animations` | *none — legacy `anim*.mul` only* | — | 1,144 bodies, **0 faults** | | `Gumps` | `gumpartLegacyMUL.uop` | **true** | **faults on the second id** | `FileIndex.cs`'s own comment says the extra-field handling exists *for* `gumpartlegacy.uop` — it is the one UOP layout carrying an extra field, and `hasExtra: true` is the branch written to cope with it. **Gumps is the only caller that sets it.** So the fault is not a general fragility in this library's `unsafe` code; it is a bug on a branch that exactly one decoder reaches, and that decoder is already out of scope (§11). The rule this turns into is a safety rule, not a preference: **nothing in this protocol calls `Ultima.Gumps`.** Adding gump art later means fixing or replacing that path first, deliberately, not discovering it in production. ### 4.2 What the decision accepts Three costs come with it, all known and none of them blocking: 1. **Six of the twelve stock player-character bodies have no art on this path** — both human ghosts and every gargoyle body (§5.2). `Animations` never reads `AnimationFrame*.uop`. **This one is not merely accepted: §4.3 adds a decoder for it**, because it is the player character and the scope says player models. 2. **`System.Drawing` is a hard dependency, in the decode and not just the encode.** `Frame` writes ARGB1555 straight through a `LockBits` pointer, so a Linux shard needs **libgdiplus** to read a sprite at all. That is a stated prerequisite — §4.4. 3. **We inherit whatever `Ultima` a given ServUO vendors**, which can change under a shard upgrade. `EXTRACTOR_VERSION` (§7) is the mitigation: it already counts as drift, so a shard whose library changed re-derives on the next import. The residual risk that remains is a patched or custom client tripping an out-of-bounds read on a path we *do* call. §16's phase 0 is where that gets exercised rather than assumed. ### 4.3 One decoder we do write: UOP animation **Built in phase 4. What it reaches is not what this section predicted, and §4.9 is the measurement.** The section stands as the argument; the numbers below are the corrected ones. The bodies the legacy path cannot resolve get a decoder rather than a caveat. It is deliberately the **narrowest possible** addition: a reader for `AnimationFrame*.uop`, used *only* where the vendored code has nothing. Everything it can already decode keeps going through it — which after phase 4 is still 787 of the catalogue's 1,022 bodies. This client ships `AnimationFrame1/2/3/4/6.uop` (107, 118, 253, 115 and 24 MB) plus `AnimationSequence.uop`. ServUO's `FileIndex` already contains a UOP reader — but `Animations` never constructs one, and the UOP animation *payload* is its own format rather than a repackaged mul record, so wiring the existing `FileIndex` in is not sufficient. Two license-compatible references exist to work from: ClassicUO's animation loader (GPL-3, and we are GPL-3-or-later) and UOFiddler 4.22 (Beerware, already established in §9). **What it was for, and what it actually delivers.** The phase was scoped to the eight player bodies §4.8 left undecodable. **Two of the eight are in the client at all** — gargoyles 666 and 667, in `AnimationFrame3.uop`. The six ghost bodies are in no package, and §4.9 shows how that was established rather than assumed. What the same fallback *does* deliver is **233 further bodies** the catalogue had nothing for, so the phase's real effect is 787 → **1,022**. **The trap this must not fall into, and it is why the phase exists at all.** `Bodyconv.def` maps gargoyle 666 to `anim5`, and `BodyConverter.Convert` faithfully returns fileType 5 — where this client's index runs out before the entry. Asking the *other* anim files for index 666 does not fail. It returns 175 decodable action/direction combinations of **a giant spider**, because something unrelated occupies that index in `anim2.mul`; fileTypes 3 and 4 return misaligned colour fragments. Rendered and confirmed. So the extractor takes `BodyConverter.Convert`'s answer and, if that yields nothing, reports nothing. **It must never sweep file types looking for a hit** — that does not find missing art, it silently puts a spider on the gargoyle page, and no error is raised anywhere. A "0 rows" outcome is correct behaviour; a plausible wrong picture is the failure this protocol most needs to avoid, because nothing downstream can detect it. **Searching all five UOP packages for one body is not that, and the difference is structural.** A legacy index is addressed **by position**: nothing in the file says which body a record belongs to, so a wrong lookup returns a confident picture of something else. A UOP entry is addressed by the **hash of a name that contains the body id** — `build/animationlegacyframe/000666/00.bin` — and the payload then declares that id again in its own header, which the reader checks against the id it asked for. A hit is proof of identity rather than a coincidence of position. Measured: no hash appears in two packages. ### 4.4 Requirement: a Linux shard host needs libgdiplus **Stated prerequisite, not a soft recommendation.** ServUO targets `net48`, so on Linux it runs under Mono, and Mono's `System.Drawing` is a thin layer over **libgdiplus**. §4.2 put `System.Drawing` in the decode path, so without that library a Linux shard cannot extract art at all — the cliloc table (§9) and the atlas files (§10) are unaffected, since neither touches pixels. **Windows shard hosts need nothing.** `System.Drawing` ships with .NET Framework. This is a Linux-only prerequisite and most shards will never read this section. | Host | Get it with | |---|---| | Debian / Ubuntu | `sudo apt-get install libgdiplus` — in Debian since bullseye (6.0.4) and bookworm/trixie (6.1), and in Ubuntu universe | | Fedora / RHEL | `sudo dnf install libgdiplus` (EPEL or the Mono repository) | | Docker | `RUN apt-get update && apt-get install -y libgdiplus` in the shard image | | Alpine, or a distro with no package | Build from source — see the repository below. This is the awkward case and is worth avoiding by choosing a Debian-based image | Upstream is , with the Mono project's own page at . **One thing to know before depending on it: that repository was archived in March 2025 and is read-only.** Distributions still package and patch it, so `apt-get install libgdiplus` is a normal, supported thing to do today — but upstream is not maintained. It is the strongest long-term argument for eventually moving extraction off `System.Drawing`, and phase 4's UOP reader (§4.3) is written without it precisely so that door stays open — decode and encode both (§4.9). It does not change the decision now, and §17.9 is the decision not to walk through that door yet: a host with no libgdiplus still gets the flat refusal below rather than the ~238 bodies that no longer need it. **How its absence must present.** Never a stack trace and never a 500. Missing libgdiplus is a named, actionable outcome in the same family as the cliloc reader's `COMPRESSED`: ``` status: unavailable code: NO_IMAGING reason: This shard host cannot render images — Mono's System.Drawing needs libgdiplus. Install it (apt-get install libgdiplus) and re-run the import. Cliloc and atlas import are unaffected. ``` The installer's `doctor` checks for it and reports it alongside its other host checks, so an operator learns about this while setting the shard up rather than from an empty bestiary weeks later. --- ### 4.5 What phase 0 measured, and the rule it produced Phase 0 ran §4's decoders from inside a live ServUO 57.4 against a client broken in 21 catalogued ways ([`servuo-plugins/tools/scaffolding/README.md`](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/src/branch/main/tools/scaffolding/README.md) carries the full results). §4's decision **stands** — nothing faulted on a path this protocol calls, and §9's cliloc reader reproduced UOFiddler's 123,490-entry table byte for byte in 218 ms. But the spike was looking for the wrong kind of failure, and found a worse one. **A malformed record does not usually throw. It renders the previous asset.** `LoadStatic` and `LoadLand` decode out of `m_StreamBuffer`, which is reused across calls, only ever grown, and filled by a `stream.Read` whose return value is discarded. So a record that is short, absent or out of bounds produces a real bitmap of whatever was decoded last — reported as success by every count in the library and undetectable by anything downstream. On the **stock, unmodified** client on this machine that is **22,102 ids**: 9,962 statics and 12,140 land tiles whose index entry reads `lookup 0, length 0`. `FileIndex.Seek` rejects `lookup < 0` and `length < 0`, and zero is neither, so it treats an empty slot as a hit. A bulk import that trusted the library would have written 22,102 duplicate images into the site under ids that have no art. §1.1's "32,766 decoded" was counting these. **This is specific to the UOP path** (see §4.6), because `artidx.mul` stores `-1` for an absent record where an unmapped UOP slot is a zeroed struct. So the rule, and it is the deliverable phase 1 inherits: > **Validate before calling.** The extractor judges an index entry — and, for statics, the record > header and row table behind it — *before* handing the id to `Ultima`. A record that fails is > reported as absent, never decoded. The checks, all of which phase 0 implemented and measured as `BridgeAssetValidator`: | Check | The shape it stops | |---|---| | `lookup >= 0`, `length > 0` | the 22,102 empty slots above | | `lookup + length <= .Length` | **`Seek` checks that a record *starts* inside the file and never that it *ends* inside it**; a short read then decodes the previous asset | | the same bound against `verdata.mul` for a patched entry | `Verdata.Seek` is bounds-checked **nowhere at all** | | land records are at least 2,024 bytes | `LoadLand` reads exactly that many whatever the length says | | declared width and height within a ceiling | `LoadStatic` allocates `new Bitmap(width, height)` from two bytes in the file — phase 0 got a ~128 MB allocation out of an edit, and the same field can ask for 8 GB | | walk the row table and every run, bounded | `LoadStatic`'s two guards bound the **write** into the bitmap and nothing bounds the **read** out of the record | Measured against the patched client, this refused all eight record-level defects, seven of which the library rendered without raising anything. Measured against the stock client it refused **nothing** across 49,151 statics and 16,384 land tiles. That second number is the one that makes the boundary defensible: a checker that refuses real art would be worse than no checker. Two more ways an id with no art yields a picture, both of which the extractor must handle itself: `Art.GetStatic(id, false)` **throws** `IndexOutOfRangeException` above the index's own ceiling (16,385 ids in a full sweep), and `Art.GetStatic(id)` with the default `checkmaxid: true` is worse — `GetLegalItemID` maps an out-of-range id to **0** and returns **item 0's picture**. Take the ceiling from the index that was opened, and pass `checkmaxid: false` so an overrun is loud. **The animation path has none of this yet**, and phase 0 proved it needs it: the patched client's verdata entry for body 34 points past `verdata.mul`'s end and the wolf still "decoded", counted among the 1,144 successes while rendering something else. `GetAnimation` additionally allocates `new int[frameCount]` straight from a file-supplied int. Extending the validator to animations is phase 1 work, not a phase 9 tidy-up. ### 4.6 The UOP wins outright, and `art.mul` is never opened `FileIndex`'s UOP constructor ends with a bare `MulPath = uopPath`. **When `artLegacyMUL.uop` is present it wins, and `art.mul` / `artidx.mul` are not opened at all.** Every current client ships the UOP, so this is the normal case and not an edge one. It matters twice. **For us:** an index entry's `lookup` is an offset into whichever file `FileIndex` resolved, so any bound taken against `art.mul` while the index holds UOP offsets is not approximate — it is meaningless. Phase 0's first run refused **34,299 perfectly good statics** for "declaring 10533x2085" on exactly that mistake, and every one of those refusals read like a real finding. The extractor must resolve the data file with `FileIndex`'s own precedence, not by name. **For operators:** a shard that adds custom art to `art.mul` while the UOP is still in place gets nothing, silently. Worth a line in the admin surface's diagnostics (§14) rather than leaving an operator to discover it as "my art did not import". ### 4.7 The gump crash, reproduced where it counts §4.1 argued from source that the access violation lives on the `hasExtra: true` branch only `Gumps` reaches. Phase 0 called `Ultima.Gumps.GetGump(2)` **once, from inside a running shard**: the ServUO process disappeared. No exception line, no `catch` reached, no shutdown, nothing in the console — the probe's checkpoint file, written before the call, was the entire record of what happened. `AccessViolationException` is a corrupted-state exception that .NET Framework 4.8 does not deliver to ordinary handlers, so on a live shard this is a crash with players on it and **there is no in-process defence**. §4.1's "nothing in this protocol calls `Ultima.Gumps`" is therefore an earned safety rule rather than a scoping preference, and adding gump art later means fixing that path first, deliberately. --- ### 4.8 What phase 1 measured: the animation path has the same defect, and it is worse §4.5 ended by saying the animation path had no validator and that extending it was phase 1's work rather than a phase 9 tidy-up. Phase 1 built it, ran it, and the reason that sentence was right is larger than the verdata entry that prompted it. **357 of the 1,144 "decodable" bodies are wrong pictures, on the stock client.** Their index entry reads `length 0` — no record at all — and `GetAnimation` returns a real bitmap anyway, for the same reason `LoadStatic` does: `m_StreamBuffer` is reused, only ever grown, and filled by a `stream.Read` whose return value is discarded. Measured directly, because a count could not tell: | Decode body 320 (`lookup 22638982, length 0`) straight after… | What comes back | |---|---| | body 12, the dragon | the dragon's bitmap, 176×167, identical hash | | body 34, the wolf | the wolf's dimensions, 35×34 | | body 400, the human male | the human's bitmap, 27×63, identical hash | That is not a near miss or a misaligned fragment. Body 320 has no art, and it renders **whichever creature was decoded before it** — which means the picture a bestiary page got would depend on the order the importer happened to walk the catalogue in. So the working set is **787 bodies, not 1,144**: | | Bodies 0–2047, direction 1, first frame | |---|---| | Real art | **787** | | Wrong pictures (empty record, library returned a bitmap) | **357** | | Absent, and the library agreed | 903 | | `bodyconv` resolves nowhere, nothing swept (§4.3) | 1 | | Refused by the record walk | **0** | | Threw | 0 | **That last-but-one row is the number that matters as much as the first.** The record-level animation checks — palette, frame count, frame table, and every run header walked against both the record's own length and the bitmap it locks — refused **nothing** across every real body on a stock client. §4.5's rule holds: a checker that refuses real art is worse than no checker, and this one does not. #### The player bodies: four of twelve, not six §5.2's table was built from the library's answer alone, and two of the six bodies it listed as decoding do not have art: | Body | Index entry | Library | Actually | |---|---|---|---| | Human male/female (400, 401) | real | 24×64, 24×63 | **art** | | Elf male/female (605, 606) | real | 24×64, 24×63 | **art** | | **Elf ghosts (607, 608)** | `lookup 27221378, length 0` | 24×63 | **the previous body's picture** | | Human ghosts (402, 403) | `lookup -1` | nothing | honestly absent | | Gargoyle (666, 667, 694, 695) | `lookup -1` / past the index | nothing | honestly absent | Confirmed the same way: body 607 decoded after the dragon is the dragon, after the wolf is the wolf, after the human male is the human male. Its 24×63 was the elf *female*'s dimensions, because 606 is what the catalogue walk decoded immediately before it. Two consequences, both of which change work elsewhere in this document: - **§4.3's UOP decoder covers eight player bodies, not six.** The elf ghosts join the human ghosts and the four gargoyle bodies. Phase 4's scope grows by two ids and its argument does not change. — *Phase 4 then found that six of those eight are in no client file at all, and recovered the other two (§4.9). The reasoning above is why they were in scope; the answer is there.* - **The `lookup -1` / `length 0` distinction is the whole difference between an honest absence and a wrong picture**, and it is not visible from outside the index. `artidx.mul` and the legacy `anim*.idx` write `-1` for a record that is not there; an empty UOP slot, and evidently a deliberately blanked legacy entry, is a zeroed struct. `FileIndex.Seek` rejects the first and accepts the second, and the second is 357 creatures and two playable ghosts. #### Why this could not have been found any other way Phase 0 ran this exact sweep and reported "1,144 decoded, 904 empty, 0 faults", and every one of those numbers is true. The library raised nothing, returned bitmaps of plausible sizes, and agreed with itself. Nothing downstream of the decode — not a count, not an exception, not a hash of the output, not a look at one picture in isolation — distinguishes body 320's dragon from body 12's. The only things that did were **validating the index entry before the call** and **decoding the same id twice after different neighbours**. That is the same method note §4.3 ended on, and this is its second confirmed catch. Any time a UO file lookup is addressed by index, a success count is evidence of nothing. --- ### 4.9 What phase 4 measured: two of eight, and 233 nobody was looking for §4.3 was scoped to eight player-character bodies. Before writing the reader, phase 4 opened the five packages and asked which of the eight were in them. **Two.** Gargoyles 666 and 667, in `AnimationFrame3.uop`. The other six are in no package at all. | Body | Legacy index | In a UOP package? | |---|---|---| | Gargoyle 666, 667 | index position runs **past the end of `anim5.idx`** | **yes — `AnimationFrame3.uop`** | | Human ghosts 402, 403 | `lookup -1` — honest absence | no | | Elf ghosts 607, 608 | `length 0` — the §4.8 shape | no | | Gargoyle ghosts 694, 695 | `lookup -1` | no | **That absence is established, not merely unfound**, which matters because "I looked and did not see it" is exactly how a name scheme that is subtly wrong presents. The five packages hold **10,724 entries** between them, and hashing `build/animationlegacyframe/%06d/%02d.bin` over bodies 0–4095 and actions 0–99 claims **all 10,724** — every entry accounted for, none left over for another naming to hide in. No client ships ghost art. §5.2 is where that lands, and §17.9 is the decision it produced. #### The 233 the phase was not asked for The rule "legacy first, UOP when it has nothing" is the same code whether it is applied to six bodies or to all of them, and applied to all of them it finds **244 bodies with a group 0** in the packages, of which only **8** also have legacy art. So the catalogue's working set goes from 787 to **1,022**, measured on the live rig: | | Rows | Of which | |---|---|---| | `legacy` — vendored `Animations` over `anim*.mul` | **787** | 366 Equipment, 240 Monster, 95 Animal, 65 unlisted, 17 Human, 4 Sea | | `uop` — §4.3's reader | **235** | 97 Equipment, 57 Monster, 50 unlisted, 26 Animal, 3 Human, 2 Sea | The mix is worth a sentence because "add every body" sounds like it changes what a catalogue *is*: it does not. The legacy 787 was **already** 366 equipment bodies — weapons and tools drawn alone for the client to composite — so the UOP's 97 more change the proportion by a point. What a bestiary sees is 83 creatures it could not show before, plus the gargoyles. #### The format, as read rather than as assumed A group file is one action of one body, every direction concatenated, zlib-compressed inside the package (`flag == 1`, `78 9c`). The payload is not a repackaged mul record: ``` 'AMOU' version decompressedSize bodyId … frameCount frameTableOffset frame table: frameCount × 16 bytes (group, frameId, two unknowns, pixel offset) each frame: its OWN 512-byte ARGB1555 palette, then centreX/centreY/width/height, then the same run-length rows the legacy Frame decoder walks ``` Two consequences the reader is built on. The per-frame palette means **no `Ultima.Frame` and no `Bitmap`**: the runs are written into a `ushort[]` of our own, which is what §4.4's promise about this reader and `System.Drawing` was always about — and it leaves the encode as the only GDI+ step, which phase 4 replaced with a ~200-line PNG writer (zlib around net48's raw-deflate-only `DeflateStream`, CRC32, one IDAT, filter 0). And **direction is a slice of the frame table**, not an index into five records: direction *d* starts at `d * (frameCount / 5)`. On **nine** of the 244 bodies the frame count is not a multiple of five (41, 42, 46…), where integer division lands slightly early in the run. That is what the reference implementations do and it is the right trade here, because the failure §4.5 and §4.8 are written against is a picture of the **wrong creature**, and this cannot produce one — the worst case is the right creature at a marginally different angle, on nine bodies, against losing nine bodies outright. #### Validate-as-we-go, and the measurement that says it is in the right place §4.5's rule is "validate before calling", because `Ultima`'s decoders take their bounds from the file they read. Here there is no library to validate ahead of: this code **is** the decode. So the same discipline appears as a bound on every read — the block chain against the file length, a record against the file, the inflated length against the declared one, the frame table against the payload, and every run header against **both** the record's remaining bytes and the bitmap it writes into, which is the bound `Frame` itself does not have. Measured exactly the way §4.5 was measured, because the second number is what makes a checker defensible: across every UOP body on a stock client it refused **nothing** that carries art. The one body it refuses, 286, declares a 0×0 frame — which the vendored decoder also treats as no art rather than as damage, so it reports absent silently rather than logging a defect on every scan. #### The live rig Real sidecar, real ServUO, this machine's client: | | | |---|---| | Catalogue | **1,022 rows in ONE page, 1,409 ms cold** | | Player bodies | **six, and all six have art** — 400/401/605/606 `legacy`, 666/667 `uop` — every one at direction 0 | | Direction split | 6 at direction 0, 1,016 at direction 1 | | The six ghost bodies | `absent` | | Duplicate-sha256 scan | 45 groups, of which **one** is new | That last row is phase 3's cheap detector for the §4.8 bug, and it earned its keep again. The new group is bodies 1531 and 1532 — two **distinct** records, 48,281 bytes each, whose first frames are identical pixels. What separates that from a reused-buffer defect is not the hash: it is that each payload declares its own body id, and the reader checked. A duplicate you can explain at the source is data; one you cannot is the bug. Manifest and fetch rows now carry `source` (`legacy` / `uop`) for exactly this reason — an operator looking at a wrong picture can say which half of the extractor to doubt, and an acceptance walk can prove the fallback fired rather than infer it from a count. **`EXTRACTOR_VERSION` is 2.** Every client file is byte-identical and the answer is different, which is the whole of what §7's number exists to say. The UOP packages join `assets.sources` and the catalogue id with it, so patching one is drift rather than a silent no-op — and resolving them needed its own lookup, because `Ultima.Files`' table of known client files predates UOP animations and answers null for every `AnimationFrame*.uop` however present they are. The replacement matches **case-insensitively by enumeration**, which is a Linux-host concern rather than a tidiness one. ### 4.10 What phase 6 measured: the ceiling, and 452 validated pictures of the wrong body §4.8 found the library returning the previously-decoded body's bitmap for an index entry that reads `length 0`. Phase 6 went looking one axis over — along **actions** rather than bodies — and found the same class of failure with none of the tells. An index entry for an animation is `bodyBase + action * 5 + direction`, and `bodyBase` comes from a **band**: 110 slots for a high-detail body (22 actions), 65 for a low-detail one (13), 175 for a people body (35). The bands are contiguous, so the slots immediately after a body's band are the **next body's**. Ask for one action past the ceiling and the arithmetic lands on a real entry, at a real offset, holding a real animation record — of a different creature. Measured on this machine's stock client, over the 795 bodies the legacy path serves: | Asking one action past the band | Bodies | |---|---| | Refused by §4.5's validator (the entry is absent or unreadable) | 152 | | **Passes `CheckEntry` and `AnimationSane` and decodes** | **643** | | ...and the picture is **byte-identical to body+1's action 0** | **452** | Body 1 action 22 is an ettin. Body 3 action 22 is an imp. Both confirmed by rendering them beside the body they belong to, because a count would have said the walk was fine — phase 0's validator cannot catch this and is not wrong to miss it: there is nothing defective about the record. The only defence is to **refuse the address**, so the ceiling lives inside `BridgeAssetValidator.ResolveAnimation`, where every caller already goes and no caller can skip it. **The ceiling is the banding, not the library's own `GetAnimLength`.** That function exists, looks authoritative and disagrees with the index arithmetic on exactly one body of this client: a body reaching file type 5 as id 34 is excluded from the first band by `Animations.GetFileIndex`'s own "looks strange, though it works" special case, so it owns **13** actions while `GetAnimLength` answers **22**. Taking the larger number is nine actions of somebody else's art, reached on this client by translation from body 276. So the count is derived from the same switch that produces the offset, in the same file, where the two cannot drift apart. This is the §4.3 never-sweep rule again in a third disguise. Sweeping file types puts a spider on the gargoyle page; trusting a `length 0` entry puts the last creature decoded on this one; walking past a band puts the *next* creature on it. All three decode cleanly, all three report success, and all three are caught by refusing to ask rather than by checking the answer. --- ## 5. Addressing: one key for every asset Every asset the bridge can serve is named by a single string key, and the key is the cache key, the hash key, the filename stem and the manifest row id: ``` static/3922 one item graphic static/3922/h33 the same graphic, hue 33 applied land/3 one land tile body/34/a0 creature body 34, action 0, first frame body/820/a23 body 820, whose action 0 is empty — a horse (§11.2) body/400/a0/f0..f9 human male, action 0, all ten frames — NOT SERVED (§11.2) cliloc/enu the whole converted string table (not an image) tree/Spawns/Trammel.xml a ServUO tree file (§10) ``` **The catalogue's key names whichever action its picture came from.** One row per body either way, and for all but 73 of this client's bodies that action is 0 — but a body with no art there is catalogued at the first action that has any, and the key says which (§11.2). Calling it `a0` regardless would have been fewer changes downstream and a key that lies about its content, which is the failure §4.5, §4.8 and §4.10 each describe from a different direction. **The frame depth is defined and not served.** `body/400/a0/f0..f9` is well-formed under this scheme and every request for it is refused `unsupported` — see §11.2 for the decision and what it would cost to change. Three properties this shape buys: - **Hue is part of the key, not a transform.** `itemId` and `hue` are already on the wire together (`BridgeMarket.cs:582`, `BridgeProfile.cs:314`), so a marketplace listing already knows the exact key for its own picture. Applying hues website-side would mean shipping `Hues.mul` semantics into Node for no gain. - **Depth is expressible without being mandatory.** `body/400/a0` and `body/400/a0/f0..f9` are the same addressing scheme at two depths, which is what lets §11 bulk-import thumbnails and, if anything ever wants them, fetch full animations on demand without a second protocol. Phase 6 measured what that second depth costs and deferred it (§11.2); the point of the scheme is that deferring it is a decision about *what to serve*, not about what can be named. - **Nothing in the key is client-version-specific**, so a client patch changes an asset's *bytes*, not its name — which is what makes §7's delta work. ### 5.1 There is no direction segment, because only one direction is wanted Bodies are stored in **five** directions and the client mirrors three of them to reach eight. Only one is needed here, so **direction is fixed by the extractor and is not part of the key**. Leaving it in would advertise a choice nobody is going to vary and would five-fold every count in §11 for nothing. **Which one depends on whether the body is a player character:** | Body | Direction | Why | |---|---|---| | A player character body | **0** — head-on, facing the viewer | A character is a portrait; it should look at you | | Everything else | **1** — front three-quarter | The view that actually reads as a creature (see the caveat below) | Which index is which was determined by **rendering all five** for a human, a wolf and a dragon rather than from a table, because the answer is not obvious and the small-thumbnail version of the same test suggested the exact opposite: | Index | View | |---|---| | **0** | **Head-on, facing the viewer** — face, chest and front legs visible | | 1 | Front three-quarter | | 2 | Full side profile | | 3 | Rear three-quarter | | 4 | Directly away — back of the head, and a quadruped's tail toward the camera | The caveat the render made obvious is what produced the split: **index 0 is the least legible view for four-legged and long-bodied creatures.** A wolf seen head-on is a dark blob; the same wolf at index 1 is unmistakably a wolf, which is also why UOFiddler's own thumbnail list picks that view. A humanoid has no such problem — it reads fine head-on, and head-on is what a character portrait wants. Both indices stay **configuration values** (defaulting to 0 and 1), so changing the catalogue's mind later is a setting and a re-import, not a protocol change. ### 5.2 "Player character body" is asked of the shard, never hardcoded `Server.Race.AllRaces` gives every registered race, and each carries `MaleBody`, `FemaleBody`, `MaleGhostBody` and `FemaleGhostBody`. The plugin enumerates the **living pair** per race, and that set — nothing else — takes index 0. On stock ServUO 57.4 that is six ids: | Race | Male | Female | Male ghost | Female ghost | |---|---|---|---|---| | Human | **400** | **401** | 402 | 403 | | Elf | **605** | **606** | 607 | 608 | | Gargoyle | **666** | **667** | 695 | 694 | This is the §8 argument again in miniature: only code inside ServUO can answer it, and asking is the only thing that works on a shard with a custom race. Two details make the case that a hardcoded list would have been wrong — `RaceDefinitions.cs` passes the gargoyle's ghost bodies in the **opposite order** to the other two races (695 male, 694 female), and a shard that calls `RegisterRace` adds ids no table of ours would contain. **The ghost columns are greyed above because no client has art for any of them, anywhere.** That is phase 4's measurement and it is what removed them from the set (§17.9). The evidence is in §4.9: 402/403 and 694/695 read `lookup -1` in the legacy index, 607/608 read `length 0` — the §4.8 shape, where the library hands back the previously-decoded body's picture — and **none of the six appears in any `AnimationFrame*.uop`**, established by claiming all 10,724 entries of the five packages with a single name scheme rather than by failing to find them. So the set is asked of the shard exactly as before; only the question changed, from four ids per race to two. A shard whose client *does* ship ghost art loses nothing: the body is catalogued like any other, at direction 1 rather than 0. **And with phase 4 in, all six have art.** The gargoyles were the last gap, and they were never a missing-art problem: `Bodyconv.def` sends 666 and 667 to `anim5`, at an index past the end of `anim5.idx`, while `AnimationFrame3.uop` has held both all along. | Has art | Via | |---|---| | Human male/female (400, 401) | vendored `Animations`, `anim.mul` | | Elf male/female (605, 606) | vendored `Animations`, `anim5.mul` | | **Gargoyle male/female (666, 667)** | **§4.3's UOP reader, `AnimationFrame3.uop`** | The catalogue must still **not** treat a missing player body as an error. It is now an unlikely answer rather than the expected one, but a client that ships fewer bodies than this one is an ordinary thing to meet, and a status screen that flags failures on every import teaches an operator to ignore it. `shard_spawn_creatures.art` staying NULL remains a first-class state everywhere it is consumed, which it already is. --- ## 6. The manifest, and what the two buttons actually do Two stages, which is where **Import** and **Update** come from. **Stage 1 — the source gate.** The shard reports a manifest of the client files themselves: size, mtime and content hash of `Cliloc.enu`, `anim*.idx`/`anim*.mul`, `art.mul`/`artidx.mul`, `Body.def`, `Bodyconv.def`, `Hues.mul`. Unchanged since the last import, and nothing else happens. This is the same hash gate the spawn atlas and the cliloc table already use, and for the same reason: the normal case is a restart that changed nothing, and it must cost nothing. `anim.mul` is 195 MB and `art.mul` is 148 MB, so the gate is **(size, mtime) first, content hash only when those differ** — a full hash of 343 MB on every status poll would make the admin panel feel broken. **Phase 1 found that the rule is not sufficient on its own, because of §3.3's other ceiling.** The first time those hashes are needed there is nothing cached to compare against, so "hash only when (size, mtime) differ" still means hashing 343 MB — inside a 10 s reply timeout it will not fit, and the call would 504 rather than answer. So the shard's hashes are computed **off the request path entirely**: - `assets.sources` always answers immediately, with `size` and `mtime` for every file and `sha256: null` for any file whose hash is not cached against exactly that (size, mtime). - A file with a missing hash starts a background pass on its **own** thread — deliberately not a job on §3.2's single-slot worker, which would answer every status poll `bridge.busy` for the minutes the pass takes, at exactly the moment an operator is watching the panel. - The reply carries `hashing` and `complete`, so the website knows to poll again rather than to treat a null hash as a changed file. The gate is unchanged; what changed is that "the normal case must cost nothing" now also means "and the abnormal case must not time out". **Stage 2 — the asset manifest.** For the working set (§11), the shard streams `[{ key, sha256, bytes }]` — no pixels. The website diffs that against what it holds and requests **only the keys whose hash changed**. - **Update** = stage 1, then stage 2, then fetch the diff. - **Import** = the same path with the diff skipped and every key fetched. - **A key that has vanished** from the manifest is staged for review, never applied silently — the same rule, and the same reasoning, as a vanished cliloc source or a disappearing atlas facet. An unmounted volume and a deliberate client downgrade look identical from here. Clilocs are the exception and stay a **whole-table replace** whenever the file hash changes: the measured cost is 663 ms for 67,496 rows, so per-entry deltas would be complexity bought for nothing. --- ## 7. The parser version applies here too `spawnAtlasSource.js` carries `PARSER_VERSION` (currently 6) and the cliloc source carries its own, both counted as drift so that a corrected parse reaches an install whose files never change. The asset pipeline inherits the rule and needs it more, not less: a fixed hue application or a corrected frame offset changes the bytes we derive from files that are byte-identical. **`EXTRACTOR_VERSION` lives in the plugin**, because the plugin is what derives the bytes, and it is folded into stage 1's gate. Bumping it makes every asset drift, which is correct. --- ## 8. Body ids: the part only the shard can do The atlas knows creatures by **slug**, derived from type names in `Spawns/*.xml`. The client knows them by **body id**. Nothing in the ServUO tree declares the mapping as data — today an operator bridges it by grepping `Scripts/Mobiles/Normal/.cs` for `Body =`, which appears variously as a decimal, as hex (`0xD1`), as `Utility.RandomList(35, 36)`, and as an `m_IDs[]` table. Inside ServUO the problem does not exist. `BridgeWorld.cs:350` already does exactly the required thing for a different feature: ```csharp var type = ScriptCompiler.FindTypeByName(name, true); var creature = Activator.CreateInstance(type) as BaseCreature; ``` Construct, read `creature.Body.BodyID`, `Delete()`. Authoritative, no source parsing, and correct for custom creatures a grep would never find. **This pass must run on the Core thread** — it constructs and deletes mobiles, which is world mutation — while the decode in §4 must run **off** it. That split is the one genuinely new threading shape in this protocol, and it is why slug→body resolution is its own request kind with its own (small) batch size rather than a step inside asset extraction. Constructing arbitrary creature types has side effects: constructors pack items, set skills, start timers. The mitigations are per-type `try`/`catch`, immediate `Delete()`, small batches, and the fact that the whole pass is admin-triggered rather than something that runs at boot. ### 8.1 What phase 3 measured **Built and walked 2026-09-10** against a live ServUO with a real world (43,000 mobiles, 210,000 items) and the real sidecar. **The catalogue is 787, exactly as §4.8 predicted**, and it arrives in one page: the whole scan of bodies 1–2047 — index validation, 787 decodes, 787 PNG encodes and 787 SHA-256s — took **734 ms** cold. That is well inside the 3 s scan budget, so the wall-clock paging §11 was designed for never fired on this client. It stays, because the budget is what keeps a slower host or a larger family inside the 10 s reply timeout rather than producing replies that are always thrown away. Every prediction in §4.8 and §5.2 held when the bytes were actually rendered and looked at: | Asked for | Answer | Why it matters | |---|---|---| | `body/320/a0` (`length 0`) | **absent** | The 357-class bug. The library would have returned the previously-decoded creature | | `body/607/a0`, `body/608/a0` (elf ghosts) | **absent** | §4.8's two rows that moved; the library returns the elf female here | | `body/666/a0` (gargoyle → `anim5`) | **absent** | The spider trap. Nothing swept, nothing found | | `body/400/a0/…` deeper key | **unsupported** | Well-formed under §5, not served until phase 6 | | direction distribution across 787 | **783 at index 1, 4 at index 0** | Four player bodies, not six — §4.8 again, from `Race.AllRaces` rather than a table. *Phase 4 made it six of six and 1,016/6 across 1,022 rows: §4.9* | **44 of the 787 hashes are shared by two or three bodies, and that is correct.** It is the exact signature the wrong-picture bug produces, so it was chased rather than assumed: the client's own `Body.def` says `83 {1}`, `84 {1}`, `138 {7}`, `139 {7}`, `106 {12, 59}`, and the sharing groups match those lines rather than being runs of consecutive ids (which is what a reused stream buffer produces). The distinguishing check is at the source: `Animations.Translate(ref body, ref hue)` rewrites `body` **only when bit 31 of the table entry is set**, unlike the one-argument overload which always does — and `BridgeAssetValidator.ResolveAnimation` calls that same two-argument overload, matching `GetAnimation(…, preserveHue: false, …)`. Validator and decoder therefore resolve the identical record, which is the property the whole §4.5 design rests on. **The Core-thread pass costs about 190 ms per 100 types.** All 455 stock `Scripts/Mobiles/Normal` classes were constructed and deleted in five chunks, producing every status the protocol defines (`ok` 436, `unknown` 11, `notCreature` 4, `failed` 4). The world's mobile count went from 43,000 at boot to 42,924 afterwards and its item count fell too — so `Delete()` is reclaiming the packed inventory as well as the mobile, and nothing leaked. The three refusals answer as designed end to end: an unknown `family` is **400**, a stale `catalog` on a fetch is **422**, and 101 types in one `assets.bodies` is **400** naming the cap. --- ## 9. The cliloc decompressor is ours now Every modern client ships `Cliloc.*` in the Mythic compressed container — this machine's `Cliloc.enu` is 4,989,921 bytes beginning `E8 79 67 8E`, high byte `0x8E`. ServUO's bundled `Ultima.StringList` implements only the plain layout and throws on it (§1.1), which is also why the shard's own `VendorSearch.GetItemName` is already inert. **UOFiddler is released under the Beerware licence**, so porting its decompressor into our GPL-3.0-or-later tree is clean. It lands in the overlay as ordinary C# — the **only** decoder Protocol 8 writes rather than calls (§4) — and from that point: - No operator installs UOFiddler. - No operator runs `dotnet build` on a converter. - No operator copies a 5 MB file to a server. - `website/server/tools/cliloc-export/` is retired, and `UOFIDDLER.md` is deleted rather than rewritten. (Phase 2 deleted its Part 1; **phase 3 deleted the page**, a phase earlier than that section predicted, because creature art was the only thing left on it.) ### 9.1 What phase 2 built, and what the port cost **Built 2026-09-10.** `BridgeCliloc.cs` in the overlay, `GET /cliloc` in the sidecar, and a paging walk in module-uo that merges the shard's table under the `custom/` overlays. The port is `MythicDecompress` + `MoveToFront` rewritten against plain arrays: the upstream is `Span` / `ArrayPool` / `BinaryPrimitives` code and ServUO targets `net48`, which has none of them without a package this tree does not vendor. The algorithm is unchanged, **including the parts that read oddly** — the three-region count/cursor/end table and the symbol-table shifts are upstream's, deliberately, because a tidier rewrite of somebody else's format decoder is a chance to be subtly wrong in a way that produces plausible text. Two bounds checks were added, and they are the only behavioural change: the upstream indexes its payload without checking, which is safe for a file the client wrote and is not safe for a file this shard was handed. A truncated container now reports `UNREADABLE` with the byte it wanted, instead of throwing an `IndexOutOfRangeException` from inside a decoder. **Measured on this machine's stock client:** 4,989,921 bytes read, decompressed and parsed in **290 ms**, yielding **67,496** non-blank rows in id order, ~5.4 MB on the wire, ~11 pages. That 67,496 is the acceptance test, and it is worth saying why it is a strong one: it is the number [`../website/CLILOCS.md`](../website/CLILOCS.md) already recorded for this same client, measured through **UOFiddler's own `Ultima.dll`** by the converter this phase deletes. An independent implementation agreeing to the row is not something a subtly-wrong decoder produces. Checked alongside it: zero U+FFFD, so the UTF-8 survived; 696 rows with non-ASCII text, spot-checked as correct curly quotes; the longest row is a 12,149-character EULA, which is also why the record length is read **unsigned** (a signed read turns anything over 32 KB negative). **The shard drops blanks before they reach the wire.** ~56,000 of the 123,490 entries are empty strings the client reserves, the website discards them at import anyway, and sending them would double the transfer for data thrown away on arrival. **Language is a parameter (`enu` by default) but not a free one.** `Ultima.Files` resolves only the names in its own table, which for clilocs is `enu`, `deu`, `custom1` and `custom2`; anything else is refused `NOT_FOUND` rather than answered with an empty table. `custom1`/`custom2` are the client-side custom cliloc files a shard ships to its players — readable here, and deliberately not wired into the website's import, because `custom/` on the site is the supported answer for shard-added ids. **`assets.error` gained a `code`.** Phase 1 chose between 403 and 400 by looking for the word "disabled" in the operator-facing sentence, which makes prose load-bearing; the codes are `DISABLED` (403), `NOT_FOUND` (404), `UNREADABLE` (422), `UNAVAILABLE` (503) and `BAD_REQUEST` (400). The substring check survives as a fallback, because an overlay and a sidecar are deployed separately and a phase-1 shard must keep its 403. ### 9.2 Where the base comes from now, and when it is read **The shard wins whenever uo-link is configured and enabled.** No mode setting: there is no version of that question an operator benefits from answering. A file on disk remains the source only where there is no shard link, plus a one-off explicit path — the deprecated pipeline, kept for installs with no bridge and for development. **Boot no longer imports on the bridge.** The file path could hash 5 MB locally and skip in 14 ms; a shard round trip in the boot sequence would be spent answering "no" on every restart but the one after a client patch — and patching a client is an operator action, so importing became one: Admin → Shard → Import. Whatever table is loaded keeps serving until then. Three things about the walk are worth recording because each is a way a shard can hand back a table that *looks* complete: - **Only `cut: "end"` finishes it** (§3.4). A short page can equally be a spent budget. - **The cursor must advance**, or the walk stops rather than spinning. - **Every page echoes the source's size and mtime.** A client patched mid-import is refused outright (`SOURCE_CHANGED`) rather than stitched together — half of what arrived came from a file that no longer exists and nothing later can tell which half. **The base is exempt from the vanished-source rule**, and that is an upgrade detail rather than a design preference: an install that used the file pipeline carries its base file's label in the stored fingerprint, and on the bridge that label is *supposed* to disappear. Counting it as vanished would make the first import after the upgrade demand approval for a change the upgrade itself made. Overlays keep the rule in full. **module-uo's protocol pin moved 7 → 8 in this phase**, which is the third declaration site §15 names and the one nothing enforces. Phase 1 moved the sidecar and the overlay together because the installer refuses to pair a mismatched bundle; this one had to be moved by hand, in the phase that first calls a protocol-8 route — the same trap that left the pin at 5 for two phases of the Event System while every REST call was answered `409`. **What survives untouched is the `custom/` overlay mechanism.** Shard-added items carry cliloc ids no client table has, and ServUO has no server-side notion of a custom cliloc — that is a real gap in the *game*, not an artefact of the manual pipeline, and `CLILOCS.md`'s reasoning for it stands. The base table now arrives over the bridge; overlays still come from a directory the site reads. Measured on the live shard: 16,434 cliloc ids referenced by the script tree, 37 absent from stock. --- ## 10. The atlas stops needing a shared filesystem Today `SPAWN_ATLAS.md` requires the **website** to read the ServUO tree — "same host, a bind mount, or a shared volume". That is the one place the platform's own rule (only the sidecar bridges the shard) is broken, and it is broken by the component that faces the internet. The same transport closes it. `spawnAtlasSource.js` already labels every file it reads with a portable key: | Label | Count (stock 57.4) | |---|---| | `Data/Regions.xml` | 1 | | `Data/Locations/*.xml` | 6 | | `Spawns/*.xml` | 13, ~10.5 MB | | `Config/ChampionSpawns.xml` | 1 | | `Data/Decoration/**` | tree | So the shard serves these files over the same batched request/reply path, and `spawnAtlasSource.js` gains a second backend behind its existing interface: **filesystem** (today, kept for same-host installs and for development) or **sidecar** (new, and the default once configured). **The parsers do not move.** `spawnAtlasParse.js` is pure, fs-free and CI-covered without a ServUO tree, and every quirk it handles — the two respawn delay units, `:OBJ=` splitting, facet-name reconciliation, the XmlSpawner directive stripping — stays exactly where it is. The shard sends bytes; the website still decides what they mean. That is the same division as §2, and it keeps the sidecar a forwarder here too. `SERVUO_PATH` and the `spawn_atlas_servuo_path` setting remain, and select the filesystem backend. ### 10.1 What phase 7 measured: `tree/