RunicGateway/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(link): the catalogue is real, and UOFiddler's last job is gone (Phase 3) #238

Merged
whitlocktech merged 2 commits from docs/asset-bridge-p3 into main 2026-09-10 23:57:20 +00:00
Conversation 0 Commits 2 Files Changed 7 +31 -11
1 changed files with 31 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit d07772a3d8 - Show all commits

42
modules/uo/SCHEMA.md
View File

@@ -245,29 +245,49 @@ marketplace listing — but with no table to resolve it against, the character s
| Table | Shape | | Table | Shape |
|---|---| |---|---|
| `shard_clilocs` | `number` INT PK, `flag`, `text` TEXT | | `shard_clilocs` | `number` INT PK, `flag`, `text` TEXT |
| `shard_cliloc_meta` | Singleton (`id = 1`), `payload` JSON (source file, sha256, count, `parserVersion`), `imported_at` | | `shard_cliloc_meta` | Singleton (`id = 1`), `payload` JSON (`source` — `bridge` or `file` — the base's fingerprint under `base`, the overlay `hashes`, per-source counts, `parserVersion`), `imported_at` |
Import-owned and all-or-nothing in one transaction, same contract as the atlas — including **`DELETE`, Import-owned and all-or-nothing in one transaction, same contract as the atlas — including **`DELETE`,
not `TRUNCATE`**, for the same reason. not `TRUNCATE`**, for the same reason.
**Sourced from files the operator supplies**, at a path from the `cliloc_client_path` setting falling **The base table comes from the SHARD** on any install with uo-link configured (Protocol 8, phase 2):
back to `UO_CLIENT_PATH`. Nothing client-derived is committed: UO's strings are EA's, exactly as the it reads its own client's compressed `Cliloc.enu` and serves the table paged over the bridge, so
creature sprites are. A shard with nothing configured is fully supported — names render as ids. Full nothing is converted and nothing is copied to the web host. Without a shard link it falls back to a
design and operator guide: [`CLILOCS.md`](../../website/CLILOCS.md). converted file on disk at a path from the `cliloc_client_path` setting, then `UO_CLIENT_PATH` — the
pre-protocol-8 pipeline, deprecated rather than removed so an existing install keeps working.
**Overlays are always the filesystem's**, either way: ServUO has no server-side notion of a custom
cliloc, so `custom/` is the only place shard-added ids exist and there is nothing on the shard to ask
for. That gap is in the *game*, not in this pipeline.
Nothing client-derived is committed: UO's strings are EA's, exactly as the creature sprites are. A
shard with nothing configured is fully supported — names render as ids. Full design and operator
guide: [`CLILOCS.md`](../../website/CLILOCS.md).
**It reads a SET of sources, not one file**, because shards edit items and add new ones and those **It reads a SET of sources, not one file**, because shards edit items and add new ones and those
carry cliloc ids no stock client table has. A base (the converted client table) plus every overlay carry cliloc ids no stock client table has. A base (from the shard, or a converted file) plus every
under `custom/` are re-read on every boot and hash-gated **together**, exactly as the atlas re-reads overlay under `custom/` are hash-gated **together**, exactly as the atlas re-reads
`Regions.xml` + `Locations/*.xml` + `Spawns/*.xml` + `ChampionSpawns.xml`. Later sources win, so an `Regions.xml` + `Locations/*.xml` + `Spawns/*.xml` + `ChampionSpawns.xml`. Later sources win, so an
overlay both adds ids and overrides stock ones, and adding one custom item never means re-exporting a overlay both adds ids and overrides stock ones, and adding one custom item never means re-exporting a
5 MB client file. Scale, measured on the live shard: its script tree references 16,434 cliloc ids and 5 MB client file. Scale, measured on the live shard: its script tree references 16,434 cliloc ids and
only 37 are absent from stock — tens of entries against a 67k base, which is why this is an overlay only 37 are absent from stock — tens of entries against a 67k base, which is why this is an overlay
and not a second table. and not a second table.
The conversion step is not avoidable: **every current client ships its cliloc files compressed** **The conversion step used to be unavoidable, and is not any more.** Every current client ships its
(first DWORD's high byte `0x8E`), and ServUO's own bundled `Ultima.StringList` cannot read that cliloc files compressed (first DWORD's high byte `0x8E`) and ServUO's own bundled
either — so the shard cannot supply names on our behalf. The plain layout and a delimited text export `Ultima.StringList` cannot read that either — which is why, for two protocol versions, the operator
are both accepted, sniffed by header rather than extension. had to install UOFiddler, build a converter against its `Ultima.dll` and copy a 5 MB file to the web
host. Protocol 8 phase 2 ported the Mythic decompressor into the overlay, so **the shard reads its
own client and supplies the names**. The file half survives only as the fallback above, where the
plain layout and a delimited text export are both accepted, sniffed by header rather than extension.
Two consequences for what this table holds. `shard_cliloc_meta.payload` carries the base's
fingerprint under `meta.base` (the shard's file size, mtime, hash and `EXTRACTOR_VERSION`) separately
from the overlay hashes, because on the bridge the old `clilocs.plain` label is *supposed* to
disappear and a single hash map would read that upgrade as a vanished source. And **boot does not
import on the bridge path**: a file could be re-hashed locally on every restart, but asking the shard
would put a sidecar round trip in the boot sequence for a table that changes only when an operator
patches their client. Importing is an admin action.
Three decisions worth stating: Three decisions worth stating: