Compare commits
20 Commits
edge
...
4c6b0c566a
| Author | SHA1 | Date | |
|---|---|---|---|
| 4c6b0c566a | |||
| bbd69a8e2e | |||
| df9b3fd990 | |||
| 1a048ae1be | |||
| f6ea5c0484 | |||
| 018f1af5ff | |||
| f2e074c3f7 | |||
| 041e1f4069 | |||
| d39e4163d1 | |||
| 44039e83d5 | |||
| b62d0b6307 | |||
| 0c3f0d65cc | |||
| 556141341f | |||
| 132620e8b3 | |||
| 81b55ac29b | |||
| 2db5737f22 | |||
| eae8a6f93d | |||
|
537c79e5de | ||
| abfdcd4658 | |||
|
|
90f95520a3 |
@@ -37,7 +37,7 @@ sidecar as a service, and hands you the values the website needs.
|
||||
| [MODERATION_APPEALS.md](website/MODERATION_APPEALS.md) | Moderation actions, content reports and the appeals flow |
|
||||
| [SPAWN_ATLAS.md](website/SPAWN_ATLAS.md) | The bestiary / spawn atlas: what the shard contains, parsed from its own ServUO tree |
|
||||
| [CLILOCS.md](website/CLILOCS.md) | UO's id → name table: converting one from your client so items have names |
|
||||
| [UOFIDDLER.md](website/UOFIDDLER.md) | **Operator runbook** — step-by-step extraction from your own UO client (cliloc table, creature art) |
|
||||
| [UOFIDDLER.md](website/UOFIDDLER.md) | **Operator runbook** — extracting creature art from your own UO client. Shrinking: the cliloc half moved to the [Asset Bridge](link/v8.md) in protocol 8 |
|
||||
| [MARKETPLACE.md](website/MARKETPLACE.md) | The player-vendor index: how it is gathered, what it costs, how to tune it |
|
||||
| [website-README.md](website/website-README.md) | Snapshot of the website repo's README (setup/run reference) |
|
||||
| [test-plan.md](website/test-plan.md) | The website's test strategy and harness |
|
||||
|
||||
@@ -79,6 +79,8 @@ android-app/
|
||||
│ │ │ │ │ │ └── PushTickle.kt
|
||||
│ │ │ │ │ ├── result/
|
||||
│ │ │ │ │ │ └── ApiResult.kt
|
||||
│ │ │ │ │ ├── time/
|
||||
│ │ │ │ │ │ └── Instants.kt
|
||||
│ │ │ │ │ ├── web/
|
||||
│ │ │ │ │ │ ├── WebHandoff.kt
|
||||
│ │ │ │ │ │ └── WebsiteUrls.kt
|
||||
@@ -90,6 +92,7 @@ android-app/
|
||||
│ │ │ │ │ │ │ ├── AdminDto.kt
|
||||
│ │ │ │ │ │ │ ├── AuthDto.kt
|
||||
│ │ │ │ │ │ │ ├── ContactDto.kt
|
||||
│ │ │ │ │ │ │ ├── EventsDto.kt
|
||||
│ │ │ │ │ │ │ ├── NotificationsDto.kt
|
||||
│ │ │ │ │ │ │ ├── PageDto.kt
|
||||
│ │ │ │ │ │ │ ├── PlayerShardDto.kt
|
||||
@@ -102,6 +105,7 @@ android-app/
|
||||
│ │ │ │ │ │ ├── AdminApi.kt
|
||||
│ │ │ │ │ │ ├── AuthApi.kt
|
||||
│ │ │ │ │ │ ├── AuthRefreshApi.kt
|
||||
│ │ │ │ │ │ ├── EventsApi.kt
|
||||
│ │ │ │ │ │ ├── MeApi.kt
|
||||
│ │ │ │ │ │ ├── NotificationsApi.kt
|
||||
│ │ │ │ │ │ ├── PlayerShardApi.kt
|
||||
@@ -117,11 +121,13 @@ android-app/
|
||||
│ │ │ │ │ ├── ConnectionRepository.kt
|
||||
│ │ │ │ │ ├── ContactRepository.kt
|
||||
│ │ │ │ │ ├── ContentRepository.kt
|
||||
│ │ │ │ │ ├── EventsRepository.kt
|
||||
│ │ │ │ │ ├── NotificationsRepository.kt
|
||||
│ │ │ │ │ ├── PlayerShardRepository.kt
|
||||
│ │ │ │ │ ├── SettingsRepository.kt
|
||||
│ │ │ │ │ ├── ShardFeaturesRepository.kt
|
||||
│ │ │ │ │ ├── ShardRepository.kt
|
||||
│ │ │ │ │ ├── SiteCapabilitiesRepository.kt
|
||||
│ │ │ │ │ └── WikiRepository.kt
|
||||
│ │ │ │ ├── di/
|
||||
│ │ │ │ │ ├── AppModule.kt
|
||||
@@ -157,6 +163,16 @@ android-app/
|
||||
│ │ │ │ │ ├── contact/
|
||||
│ │ │ │ │ │ ├── ContactScreen.kt
|
||||
│ │ │ │ │ │ └── ContactViewModel.kt
|
||||
│ │ │ │ │ ├── events/
|
||||
│ │ │ │ │ │ ├── EventScreen.kt
|
||||
│ │ │ │ │ │ ├── EventSeriesScreen.kt
|
||||
│ │ │ │ │ │ ├── EventSeriesViewModel.kt
|
||||
│ │ │ │ │ │ ├── EventsScreen.kt
|
||||
│ │ │ │ │ │ ├── EventsViewModel.kt
|
||||
│ │ │ │ │ │ ├── EventTimes.kt
|
||||
│ │ │ │ │ │ ├── EventViewModel.kt
|
||||
│ │ │ │ │ │ ├── MyEventsScreen.kt
|
||||
│ │ │ │ │ │ └── MyEventsViewModel.kt
|
||||
│ │ │ │ │ ├── home/
|
||||
│ │ │ │ │ │ ├── HomeScreen.kt
|
||||
│ │ │ │ │ │ └── HomeViewModel.kt
|
||||
@@ -335,6 +351,7 @@ android-app/
|
||||
│ │ │ │ │ └── WikiDtoTest.kt
|
||||
│ │ │ │ └── fake/
|
||||
│ │ │ │ ├── FakeAdminApi.kt
|
||||
│ │ │ │ ├── FakeEventsApi.kt
|
||||
│ │ │ │ ├── FakeNotificationsApi.kt
|
||||
│ │ │ │ ├── FakePlayerShardApi.kt
|
||||
│ │ │ │ ├── FakePublicApi.kt
|
||||
@@ -345,7 +362,8 @@ android-app/
|
||||
│ │ │ └── repository/
|
||||
│ │ │ ├── AccountTrustedDevicesTest.kt
|
||||
│ │ │ ├── ConnectionVersionGuardTest.kt
|
||||
│ │ │ └── ShardFeaturesRepositoryTest.kt
|
||||
│ │ │ ├── ShardFeaturesRepositoryTest.kt
|
||||
│ │ │ └── SiteCapabilitiesRepositoryTest.kt
|
||||
│ │ ├── ui/
|
||||
│ │ │ ├── admin/
|
||||
│ │ │ │ ├── AdminContentViewModelTest.kt
|
||||
@@ -356,8 +374,12 @@ android-app/
|
||||
│ │ │ │ └── BrandAssetsTest.kt
|
||||
│ │ │ ├── contact/
|
||||
│ │ │ │ └── ContactViewModelTest.kt
|
||||
│ │ │ ├── events/
|
||||
│ │ │ │ ├── EventsViewModelsTest.kt
|
||||
│ │ │ │ └── EventTimesTest.kt
|
||||
│ │ │ ├── navigation/
|
||||
│ │ │ │ ├── MenuAccessTest.kt
|
||||
│ │ │ │ ├── MenuCapabilityGatingTest.kt
|
||||
│ │ │ │ ├── MenuFeatureGatingTest.kt
|
||||
│ │ │ │ ├── NavOverridesTest.kt
|
||||
│ │ │ │ ├── NavPathsTest.kt
|
||||
|
||||
@@ -57,9 +57,9 @@ The wire protocol is versioned so a mismatch is caught immediately instead of fa
|
||||
|
||||
The current version is **6**. It is not released yet — it lives on `edge` and ships with the event system's cutover; the last released pairing is protocol **5**, sidecar **v2.1.0** + overlay **v1.1.0**, resolved as bundle **2026.09.01**, never as "latest of each".
|
||||
|
||||
- Every response carries an **`X-UOLink-Version: 6`** header.
|
||||
- Every response carries an **`X-UOLink-Version: 8`** header.
|
||||
- `GET /health` and the WebSocket `ws.hello` frame include `"protocol": 6`.
|
||||
- **Optionally**, send `X-UOLink-Version: 6` on your requests. If it disagrees with the sidecar, the request is rejected **409 Conflict**:
|
||||
- **Optionally**, send `X-UOLink-Version: 8` on your requests. If it disagrees with the sidecar, the request is rejected **409 Conflict**:
|
||||
|
||||
```json
|
||||
{ "error": "protocol version mismatch", "sidecar_protocol": 6, "client_protocol": "5" }
|
||||
@@ -1277,7 +1277,7 @@ so a retry loop cannot quietly swallow a mismatched deployment.
|
||||
A typical character page:
|
||||
|
||||
```js
|
||||
const H = { "Authorization": `Bearer ${TOKEN}`, "X-UOLink-Version": "6" };
|
||||
const H = { "Authorization": `Bearer ${TOKEN}`, "X-UOLink-Version": "8" };
|
||||
|
||||
// 1. render the roster
|
||||
const roster = await fetch(`${BASE}/roster/${account}`, { headers: H }).then(r => r.json());
|
||||
|
||||
@@ -69,3 +69,44 @@ World: Loading...
|
||||
## Unrelated, still open
|
||||
|
||||
`DllNotFoundException: zlibwapi64` crashed this shard once (`Crash 6-5-2026-22-38-3.log`) while sending a packed gump. `zlibwapi64.dll` is present in the repo root, so this is a working-directory / native-load-path problem. It will bite the bridge if the bridge ever triggers a gump send. Resolve before load testing.
|
||||
|
||||
---
|
||||
|
||||
## Host prerequisite: `libgdiplus` on Linux (Protocol 8)
|
||||
|
||||
Everything above is a repair to one shard's *scripts*. This one is different in kind: it is a
|
||||
requirement on the **host**, it applies to every shard, and only to Linux ones.
|
||||
|
||||
The Asset Bridge ([`v8.md`](v8.md) §4.4) has the shard read art out of the operator's own UO client
|
||||
files. ServUO targets `net48`, so on Linux it runs under Mono, and Mono's `System.Drawing` is a thin
|
||||
layer over **libgdiplus** — which sits in the **decode** path and not merely the encode:
|
||||
`Ultima.Frame` writes ARGB1555 through a `LockBits` pointer. Without that library a Linux shard
|
||||
cannot read a sprite at all.
|
||||
|
||||
**Windows shard hosts need nothing.** `System.Drawing` ships with .NET Framework.
|
||||
|
||||
| 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. This is the awkward case, and it is worth avoiding by choosing a Debian-based image |
|
||||
|
||||
Upstream is <https://github.com/mono/libgdiplus>. **That repository was archived in March 2025** and
|
||||
is read-only; distributions still package and patch it, so installing it is a normal supported thing
|
||||
to do today, but nobody is maintaining it upstream. It is the strongest long-term argument for
|
||||
eventually moving extraction off `System.Drawing`.
|
||||
|
||||
**Its absence is not an error and never a crash.** The shard reports a named status on the source
|
||||
gate — the first call any import makes — so an operator meets this while setting the shard up rather
|
||||
than as an empty bestiary weeks later:
|
||||
|
||||
```
|
||||
imaging: { ok: false, 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." }
|
||||
```
|
||||
|
||||
Clilocs and the ServUO tree files are genuinely unaffected: neither touches a pixel. The installer's
|
||||
`doctor` checks for this alongside its other host checks.
|
||||
|
||||
@@ -823,6 +823,11 @@ shapes are the plain binary layout and a `number<TAB|,|;>text` export; the site
|
||||
and writes the plain form. A shard that never converts is fully supported — names render as ids,
|
||||
exactly as before.
|
||||
|
||||
> **Superseded by [`v8.md`](v8.md) §9 (protocol 8, phase 2).** The decompressor is in the overlay
|
||||
> now, the shard reads its own client, and `server/tools/cliloc-export/` has been deleted. The
|
||||
> paragraph above is kept as the record of why the manual step existed; everything else in this
|
||||
> section — the overlay set, the hash gate, the refusals — still describes what runs.
|
||||
|
||||
**Shards edit items and add new ones**, and those carry ids no stock client table has — so this reads
|
||||
a **set** of sources, not one file, hash-gated together and re-read on every boot exactly as §6 reads
|
||||
the ServUO tree: a base (the converted client table) plus every overlay under `custom/`, later
|
||||
|
||||
1057
link/v8.md
Normal file
1057
link/v8.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -21,7 +21,7 @@ these routes *mean* are the ones that already existed and did not move:
|
||||
| [`SPAWN_ATLAS.md`](../../website/SPAWN_ATLAS.md) | The bestiary / spawn atlas, parsed from the shard's own ServUO tree |
|
||||
| [`MARKETPLACE.md`](../../website/MARKETPLACE.md) | The player-vendor index |
|
||||
| [`CLILOCS.md`](../../website/CLILOCS.md) | UO's id → name table |
|
||||
| [`UOFIDDLER.md`](../../website/UOFIDDLER.md) | Operator runbook for extracting the cliloc table and creature art |
|
||||
| [`UOFIDDLER.md`](../../website/UOFIDDLER.md) | Operator runbook for extracting creature art. The cliloc table now arrives over the bridge ([`link/v8.md`](../../link/v8.md) §9) |
|
||||
| [`../../link/PLAN.md`](../../link/PLAN.md), [`../../link/INTEGRATION.md`](../../link/INTEGRATION.md) | The wire protocol this module speaks to the sidecar |
|
||||
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
# Cliloc table (item and title names)
|
||||
|
||||
**Status:** Complete on `edge` — website [#115](https://gitea.whitlocktech.com/RunicGateway/website/pulls/115), docs [#70](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/70).
|
||||
**Design:** [`docs/link/v3.md` §8.6](../link/v3.md) — Protocol 3.0, the dependency Part B/3 was sequenced behind.
|
||||
**Status:** Complete. The base table now arrives **over the bridge** — protocol 8, phase 2.
|
||||
**Design:** [`docs/link/v3.md` §8.6](../link/v3.md) (the table itself, Protocol 3.0) and
|
||||
[`docs/link/v8.md` §9](../link/v8.md) (the Asset Bridge, which retired the manual conversion).
|
||||
|
||||
A "cliloc" is UO's localization table: an integer id mapped to a display string.
|
||||
**Items on the wire carry a `LabelNumber`, not a name.** The bridge has always
|
||||
@@ -12,86 +13,70 @@ render `id 1023721` where the game renders **"quarter staff"**.
|
||||
|
||||
The number was never the missing piece. The table was.
|
||||
|
||||
## Why the operator has to convert the file
|
||||
## Where the table comes from
|
||||
|
||||
This is the awkward part, and it is not avoidable:
|
||||
**The shard reads its own client.** A ServUO server cannot boot without a UO
|
||||
client — `Config/DataPath.cfg` resolves into `Core.DataDirectories` at run time —
|
||||
so the file this table is made of is already sitting on the shard host. Since
|
||||
protocol 8 the plugin decompresses it and serves it over the bridge, and the site
|
||||
imports it like any other shard read:
|
||||
|
||||
**Every current UO client ships its cliloc files compressed.** All eight
|
||||
`Cliloc.*` files in a modern client (`chs`, `cht`, `deu`, `enu`, `esp`, `fra`,
|
||||
`jpn`, `kor`) begin with a DWORD whose high byte is `0x8E` — the "Mythic"
|
||||
compressed container. The plain layout this site parses is what those files
|
||||
looked like *before* that change.
|
||||
|
||||
Decompressing it means an inverse-BWT coder with a frequency header — a few
|
||||
hundred lines of bit-level work whose failure mode is plausible-looking garbage
|
||||
rather than an error. The site has no business carrying that at runtime.
|
||||
|
||||
Two facts make the alternatives worse, not better:
|
||||
|
||||
- **ServUO cannot read it either.** Its bundled `Ultima.StringList` implements
|
||||
only the plain layout, so on a modern client `VendorSearch.StringList` is null
|
||||
and `VendorSearch.GetItemName` returns `item.Name` — usually nothing. The
|
||||
shard cannot supply names on our behalf; the in-game Vendor Search gump has the
|
||||
same gap.
|
||||
- **Nothing client-derived may be committed.** UO's strings are EA's. The repo
|
||||
ships no string table for the same reason it ships no artwork and no map
|
||||
snapshot — see [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md).
|
||||
|
||||
So the conversion happens **once, on the operator's machine, against their own
|
||||
client**, and the site reads the result from a path it is given. A shard that
|
||||
never does this is in a fully supported state: names render as ids, exactly as
|
||||
they did before the table existed.
|
||||
|
||||
## Converting
|
||||
|
||||
> **Step-by-step operator instructions — where to get UOFiddler, where your
|
||||
> client files are, and how to verify the import — are in
|
||||
> [`UOFIDDLER.md`](UOFIDDLER.md).** This section covers the formats and the
|
||||
> reasoning behind them.
|
||||
|
||||
Either format below is accepted; the site sniffs which one it was handed.
|
||||
|
||||
| Format | Fidelity | Notes |
|
||||
|---|---|---|
|
||||
| **Plain binary** (recommended) | Exact | 6-byte header, then `{int32 number, byte flag, uint16 length, UTF-8}` records |
|
||||
| Delimited text | Loses leading/trailing whitespace | `number<TAB\|,\|;>text` per line; a header row, blank lines and `#` comments are ignored |
|
||||
|
||||
The whitespace caveat is real but cosmetic: ~1,300 of the 123,490 entries in a
|
||||
stock `Cliloc.enu` are label prefixes like `"max = "` whose trailing space is
|
||||
meaningful when the client concatenates a value onto them. Nothing on this site
|
||||
concatenates, and every consumer passes through `displayText()`, which trims.
|
||||
|
||||
### Using the bundled tool
|
||||
|
||||
`server/tools/cliloc-export/` is a small .NET console app that drives
|
||||
[UOFiddler](https://github.com/polserver/UOFiddler)'s `Ultima.dll` — the
|
||||
decompressor that already exists and is already maintained — and writes the plain
|
||||
format. It loads that DLL **reflectively** so it compiles against any SDK, and it
|
||||
writes the records by hand because UOFiddler's own `SaveStringList` *re-compresses*
|
||||
on save (its purpose is round-tripping a file back into the client, so its output
|
||||
is byte-identical to its input — a trap worth knowing about).
|
||||
|
||||
```bash
|
||||
cd website/server/tools/cliloc-export
|
||||
dotnet build -c Release
|
||||
|
||||
# binary (recommended)
|
||||
dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/clilocs.plain
|
||||
|
||||
# or tab-delimited
|
||||
dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/clilocs.tsv --tsv
|
||||
```
|
||||
ServUO shard ──`cliloc.table`──▶ uo-link sidecar ──`GET /cliloc`──▶ website
|
||||
reads Cliloc.enu, forwards, keeps merges overlays,
|
||||
decompresses, pages nothing replaces the table
|
||||
```
|
||||
|
||||
A UOFiddler GUI export works too, but **not unmodified**: its Cliloc tab writes
|
||||
`Number;Text;Flag` — three columns, the flag *last* — and the parser reads
|
||||
`number<separator>text`, so the trailing field is absorbed into the name and
|
||||
every item renders as `quarter staff;0`. Stripping it is one `sed`, given in
|
||||
[`UOFIDDLER.md`](UOFIDDLER.md) §Route B.
|
||||
**Why that was worth building.** Every current UO client ships its cliloc files
|
||||
compressed: all eight `Cliloc.*` files in a modern client (`chs`, `cht`, `deu`,
|
||||
`enu`, `esp`, `fra`, `jpn`, `kor`) begin with a DWORD whose high byte is `0x8E` —
|
||||
the "Mythic" container. The plain layout is what those files looked like *before*
|
||||
that change, and **ServUO's own bundled `Ultima.StringList` cannot read the new
|
||||
one either**, which is why `VendorSearch.GetItemName` is inert on a modern shard
|
||||
and the in-game Vendor Search gump has the same gap.
|
||||
|
||||
The parser already tolerates `number,flag,text`, with the flag in the *middle*.
|
||||
It is not extended to cover the trailing form because a final `;0` is
|
||||
indistinguishable from a name that genuinely ends that way — a heuristic there
|
||||
would corrupt real names to save the operator one command.
|
||||
So until protocol 8 an operator had to install UOFiddler, build a converter
|
||||
against its `Ultima.dll`, run it over their client and copy a 5 MB file to the web
|
||||
host — every time they patched. The decompressor now lives in the overlay
|
||||
(`overlay/Scripts/Custom/Bridge/BridgeCliloc.cs`, ported from UOFiddler, which is
|
||||
Beerware and therefore clean to bring into a GPL tree), so **none of that is a
|
||||
step any more**.
|
||||
|
||||
Two things are unchanged and remain the point:
|
||||
|
||||
- **Nothing client-derived is committed.** UO's strings are EA's. The repo ships
|
||||
no string table for the same reason it ships no artwork and no map snapshot —
|
||||
see [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md). The extraction happens on the
|
||||
operator's own host, from their own files, for their own shard.
|
||||
- **A shard with no table is fully supported.** Names render as ids, exactly as
|
||||
they did before the table existed.
|
||||
|
||||
### What arrives, and in how many pieces
|
||||
|
||||
The sidecar's reply timeout is 10 s and its inbound line cap is 1 MiB, so the
|
||||
table is **paged**: the shard cuts at a 512 KiB byte budget and hands back a
|
||||
cursor, and the site walks it until a page says `more: false`. Measured on a stock
|
||||
English client: **67,496 rows in about eleven pages**, decoded on the shard in
|
||||
**290 ms**.
|
||||
|
||||
The rows are `{ n, f, t }` — number, flag, text. **Blanks never leave the shard**:
|
||||
roughly 56,000 of a stock table's 123,490 entries are empty strings the client
|
||||
reserves and never uses, the site drops them at import anyway, and sending them
|
||||
would double the transfer for data that is discarded on arrival.
|
||||
|
||||
Only `cut: "end"` means the table finished. A short page can equally mean the byte
|
||||
budget was spent, and importing a table that stopped early is the one failure that
|
||||
is invisible downstream — some items named, some not, which is exactly what *no
|
||||
table* looks like.
|
||||
|
||||
### The file pipeline is deprecated, not removed
|
||||
|
||||
An install with **no uo-link configured** can still be pointed at a converted file
|
||||
and works exactly as it did. That path exists for shards with no bridge and for
|
||||
development without a running ServUO, it accepts the same two formats it always
|
||||
did (plain binary, or `number<TAB|,|;>text` delimited text), and passing an
|
||||
explicit path to a refresh still selects it as a one-off. Nothing new should be
|
||||
built on it.
|
||||
|
||||
## Shard-added and shard-edited items
|
||||
|
||||
@@ -103,12 +88,16 @@ atlas, which reads `Regions.xml` + `Locations/*.xml` + `Spawns/*.xml` +
|
||||
|
||||
```
|
||||
<cliloc path>/
|
||||
clilocs.plain ← base: the converted client table
|
||||
custom/
|
||||
01-uomysticmoon.tsv ← overlays: shard additions and overrides
|
||||
02-events.tsv
|
||||
```
|
||||
|
||||
The base is no longer a file in that directory — it comes from the shard — so on
|
||||
a bridged install the configured path selects **only** where `custom/` is read
|
||||
from. (Without a shard link, a converted base file sitting beside `custom/` is
|
||||
still found, which is the deprecated pipeline above.)
|
||||
|
||||
Overlays use the same delimited-text format, are read in **sorted order**, and
|
||||
**later sources win** — so an overlay both *adds* ids the client never had and
|
||||
*overrides* stock ones the shard has re-purposed. Any `.tsv`, `.csv`, `.txt`,
|
||||
@@ -116,8 +105,9 @@ Overlays use the same delimited-text format, are read in **sorted order**, and
|
||||
say) is ignored.
|
||||
|
||||
Adding, editing or removing any overlay counts as drift, so a new custom item
|
||||
needs only a file edit and a restart — or the admin panel's Import button.
|
||||
**Adding one item never means re-exporting a 5 MB client file.**
|
||||
needs only a file edit and the admin panel's Import button. **Adding one item
|
||||
never means re-reading the client table** — though on the bridge that is now
|
||||
cheap enough not to matter much.
|
||||
|
||||
The import result reports what each source contributed, which is how you confirm
|
||||
an overlay took effect — `overrode: 0` on a file meant to re-label stock items
|
||||
@@ -125,11 +115,14 @@ says it did not:
|
||||
|
||||
```json
|
||||
"sources": [
|
||||
{ "label": "clilocs.plain", "kind": "base", "entries": 123490, "added": 123490, "overrode": 0 },
|
||||
{ "label": "custom/uomysticmoon.tsv", "kind": "custom", "entries": 2, "added": 1, "overrode": 1 }
|
||||
{ "label": "cliloc.enu", "kind": "shard", "entries": 67496, "added": 67496, "overrode": 0 },
|
||||
{ "label": "custom/uomysticmoon.tsv", "kind": "custom", "entries": 2, "added": 1, "overrode": 1 }
|
||||
]
|
||||
```
|
||||
|
||||
`kind` says where a source came from: `shard` over the bridge, `base` a converted
|
||||
file on disk, `custom` an overlay.
|
||||
|
||||
**Why a convention rather than discovery.** Everywhere else this pipeline follows
|
||||
the shard's own files, but **ServUO has no server-side notion of a custom
|
||||
cliloc** — they live in the patched client a shard distributes to its players,
|
||||
@@ -143,28 +136,29 @@ ids and only **37** are absent from the stock client table — tens of entries
|
||||
against a 67k base, which is what makes an overlay the right shape rather than a
|
||||
second full table.
|
||||
|
||||
## Configuring the path
|
||||
## Choosing the source
|
||||
|
||||
Two ways to point at the sources, the setting winning over the environment:
|
||||
Nothing to configure: **the shard wins whenever uo-link is configured and
|
||||
enabled.** There is no mode setting, because there is no version of this question
|
||||
an operator benefits from answering — a shard that can serve its own client table
|
||||
is strictly better than a file somebody converted by hand months ago.
|
||||
|
||||
| Source | Notes |
|
||||
The two escape hatches, both deliberate:
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| `cliloc_client_path` setting | Admin-editable (Admin → Shard); takes effect on the next refresh without a redeploy |
|
||||
| `UO_CLIENT_PATH` env var | The deploy-time default, since the path usually describes a mount the deployment sets up |
|
||||
| No uo-link configured | The file pipeline, exactly as before |
|
||||
| An explicit `path` passed to a refresh | A one-off "import from this file", which the shard never overrules |
|
||||
|
||||
The value may be **the base file itself or a directory to search**, because both
|
||||
are natural answers to "where is it". Overlays are read from a `custom/`
|
||||
directory beside the base **either way** — pointing at a file does not forfeit
|
||||
them.
|
||||
|
||||
A directory is searched case-insensitively (the client writes `Cliloc.enu` on
|
||||
Windows; the site usually runs on Linux) for, in order: `clilocs.tsv`,
|
||||
`clilocs.csv`, `clilocs.plain`, `cliloc.plain`, `cliloc.plain.enu`,
|
||||
`cliloc.enu.plain`, `clilocs.txt`, `cliloc.enu`.
|
||||
|
||||
That ordering puts explicitly-converted names first on purpose. Pointing the
|
||||
setting straight at an unconverted client directory finds `cliloc.enu`, which is
|
||||
compressed — and the site says so by name rather than failing obscurely:
|
||||
`cliloc_client_path` (setting, admin-editable) and `UO_CLIENT_PATH` (env
|
||||
deploy-time default) still name a path, and the setting still wins over the
|
||||
environment. What that path *means* narrowed: on a bridged install it is where
|
||||
`custom/` overlays live. Without a link it is also searched for a base file,
|
||||
case-insensitively (the client writes `Cliloc.enu` on Windows; the site usually
|
||||
runs on Linux), in order: `clilocs.tsv`, `clilocs.csv`, `clilocs.plain`,
|
||||
`cliloc.plain`, `cliloc.plain.enu`, `cliloc.enu.plain`, `clilocs.txt`,
|
||||
`cliloc.enu` — and pointing it straight at an unconverted client directory still
|
||||
answers by name rather than failing obscurely:
|
||||
|
||||
```
|
||||
status: unavailable
|
||||
@@ -175,16 +169,25 @@ reason: This is a compressed (Mythic-format) cliloc file, which the site cannot
|
||||
|
||||
## Refresh contract
|
||||
|
||||
Identical in shape to the spawn atlas, and for the same reasons:
|
||||
|
||||
- **It never blocks startup.** No path, an unreadable file, a wrong-format file,
|
||||
a database error — all caught and logged. The site comes up either way.
|
||||
- **Hash-gated.** The boot path hashes the file and skips the parse entirely when
|
||||
it matches what is loaded, which is every restart that did not follow a client
|
||||
patch. Measured on a stock table: **14 ms** for the no-op, **663 ms** for a full
|
||||
parse and replace.
|
||||
- **A `PARSER_VERSION` bump also counts as drift**, so a corrected parse reaches
|
||||
an install whose client never patches.
|
||||
- **It never blocks startup**, and on the bridge it never *touches* startup: boot
|
||||
imports nothing when the shard is the source. A sidecar 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 is an
|
||||
operator action. **Admin → Shard → Import** is the button. Whatever table is
|
||||
loaded keeps serving until then.
|
||||
- **Still hash-gated**, so pressing Import when nothing changed costs one small
|
||||
call. The gate is the shard's own `assets.sources`: size, mtime and content
|
||||
hash of `Cliloc.enu` plus the shard's `EXTRACTOR_VERSION`. A `sha256` of `null`
|
||||
with `hashing: true` means the shard has not computed it yet (it hashes off the
|
||||
request path, because the art and animation files it also reports are 343 MB)
|
||||
— that means *ask again*, never *changed*, and the comparison falls back to
|
||||
(size, mtime) meanwhile.
|
||||
- **Without a link** the file path is unchanged: boot hashes the local file and
|
||||
skips the parse when it matches. Measured on a stock table: **14 ms** for the
|
||||
no-op, **663 ms** for a full parse and replace.
|
||||
- **A `PARSER_VERSION` bump counts as drift**, and so does an `EXTRACTOR_VERSION`
|
||||
bump on the shard — same argument at the other end of the wire: a corrected
|
||||
reader must reach an install whose client never patches.
|
||||
|
||||
### Two ways a refresh is refused
|
||||
|
||||
@@ -201,7 +204,7 @@ and the rows already loaded are untouched. A malformed overlay names the file it
|
||||
came from (`custom/broken.tsv: No cliloc entries found…`), because "which of my
|
||||
six overlay files is broken" is otherwise a guessing game.
|
||||
|
||||
**A source that has VANISHED** is the hazard a single file did not have. It
|
||||
**An OVERLAY that has VANISHED** is the hazard a single file did not have. It
|
||||
parses perfectly and imports a table quietly missing everything that file
|
||||
contributed — and an unmounted volume looks exactly like a deliberate deletion
|
||||
from here. This is the same ambiguity the atlas stages a facet removal for, so it
|
||||
@@ -209,11 +212,28 @@ is escalated rather than applied:
|
||||
|
||||
```
|
||||
status: needsReview
|
||||
reason: 1 previously-loaded cliloc source(s) are missing;
|
||||
reason: 1 previously-loaded cliloc overlay(s) are missing;
|
||||
the existing table is unchanged
|
||||
missingSources: ["custom/uomysticmoon.tsv"]
|
||||
```
|
||||
|
||||
**The base is deliberately exempt from that question**, and that is an upgrade
|
||||
detail worth stating: an install that used the converted-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 a vanished source would make the first
|
||||
import after the upgrade demand an approval for a change the upgrade itself made.
|
||||
|
||||
**A client patched mid-import** is refused outright rather than staged, because
|
||||
there is nothing to decide: every page echoes the source file's size and mtime, and
|
||||
if they move between pages then half of what arrived came from a file that no
|
||||
longer exists and nothing later can tell which half.
|
||||
|
||||
```
|
||||
status: unavailable
|
||||
code: SOURCE_CHANGED
|
||||
reason: The shard's cliloc file changed while it was being read; nothing was imported
|
||||
```
|
||||
|
||||
`status()` reports `missingSources` too, so the panel can show it before anyone
|
||||
clicks Import. An admin accepts it by re-running the import with
|
||||
`{ "approve": true }`.
|
||||
@@ -229,15 +249,20 @@ admin was already going to run.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Parsed from a stock `Cliloc.enu` | **123,490** entries |
|
||||
| Entries in a stock `Cliloc.enu` | **123,490** |
|
||||
| Of those, empty strings | **55,994** (ids the client reserves and never uses) |
|
||||
| Stored in `shard_clilocs` | **67,496** |
|
||||
|
||||
Blank entries are dropped at import. A row resolving to no name is
|
||||
indistinguishable from no row at all to every caller, and dropping them makes the
|
||||
binary and text imports converge on **identical** content — the binary format
|
||||
carries the blanks explicitly and a text export may or may not, depending on the
|
||||
tool. Verified: both formats import to the same 67,496 rows with the same keys.
|
||||
Blank entries are dropped, and since protocol 8 they are dropped **on the shard**,
|
||||
before they reach the wire. A row resolving to no name is indistinguishable from
|
||||
no row at all to every caller, so sending 56,000 of them would double the
|
||||
transfer for data discarded on arrival. The site still filters at import, because
|
||||
an overlay file can carry one and because the file pipeline still exists.
|
||||
|
||||
That the shard's own decoder lands on **exactly 67,496** is also the strongest
|
||||
check there is that the ported decompressor is correct: the number was measured
|
||||
first through UOFiddler's `Ultima.dll` against this same client, by an entirely
|
||||
different implementation.
|
||||
|
||||
`text` is `TEXT`, not `VARCHAR`: the long property descriptions reach 12 KB, and
|
||||
silently truncating them would be worse than storing them. The index that matters
|
||||
@@ -297,13 +322,24 @@ All admin-only, alongside the atlas under Admin → Shard:
|
||||
|
||||
| Route | Purpose |
|
||||
|---|---|
|
||||
| `GET /api/v1/admin/shard/clilocs` | Sources found, what each contributed at the last import, readability, drift, entry count, `missingSources` |
|
||||
| `POST /api/v1/admin/shard/clilocs/import` | Reload after a client patch or an overlay edit; `{ "force": true }` reimports an unchanged set, `{ "approve": true }` accepts a vanished source |
|
||||
| `PUT /api/v1/admin/shard/clilocs/path` | Set the path; blank disables resolution |
|
||||
| `GET /api/v1/admin/shard/clilocs` | Which source is in use (`bridge` / `file`), the shard's client-file fingerprint, what each source contributed at the last import, drift, entry count, `missingSources` |
|
||||
| `POST /api/v1/admin/shard/clilocs/import` | Reload after a client patch or an overlay edit; `{ "force": true }` reimports an unchanged set, `{ "approve": true }` accepts a vanished overlay |
|
||||
| `PUT /api/v1/admin/shard/clilocs/path` | Set the overlay path (and, with no shard link, the base file's); blank clears it |
|
||||
|
||||
A refresh **result is not an exception**: a missing file, or the likely mistake of
|
||||
pointing at the client's own compressed `Cliloc.enu`, answers `200` with
|
||||
`status: "unavailable"` and a reason. A `500` would say only "something broke";
|
||||
the operator needs to be told which file to convert. Setting the path
|
||||
deliberately does **not** import as a side effect — the response carries the
|
||||
refreshed status so the panel can offer that as the next step.
|
||||
**Import is now the only thing that refreshes the table on a bridged install**,
|
||||
since boot no longer asks the shard. It is the button an operator presses after
|
||||
patching their client.
|
||||
|
||||
A refresh **result is not an exception**, and protocol 8 widened the set of things
|
||||
that covers: a shard that is down, an asset plane the operator has switched off
|
||||
(`Bridge.AssetsEnabled`), a client with no cliloc file, a client patched halfway
|
||||
through the import, plus everything the file pipeline could already report. Each
|
||||
answers `200` with `status: "unavailable"` and a reason naming what to fix. A
|
||||
`500` would say only "something broke". Setting the path deliberately does **not**
|
||||
import as a side effect — the response carries the refreshed status so the panel
|
||||
can offer that as the next step.
|
||||
|
||||
The sidecar's own statuses are worth knowing when reading a log: **425** is the
|
||||
shard saying it is busy with another asset request (flow control, and the ordinary
|
||||
answer mid-import — the site retries), **403** the asset plane switched off, **404**
|
||||
a client with no such file, **422** a file it has and cannot decode.
|
||||
|
||||
@@ -15,6 +15,14 @@ UO actions, the integrations, the authoring UI, the public surface — needed no
|
||||
Those fourteen phases reach the game only to *announce*, over verbs the write plane already carries; nothing in them creates or
|
||||
changes a thing in the world.
|
||||
|
||||
**COMPLETE as of 2026-09-10.** All seventeen phases are built and on `main` in every repository they
|
||||
touch. P16 ran as three legs — **16a** the acceptance walk from `edge`, **16b** the six-step cutover
|
||||
and the re-verify against released artefacts, **16c** `runicgateway.com` and `.profile` — and 16c
|
||||
opened by closing the seventh cutover step 16b had left standing (`docs#232`). The platform the
|
||||
workstream leaves behind is sidecar **v2.2.0**, overlay **v1.2.0**, bundle **2026.09.10** on
|
||||
**protocol 7**, `Module-uo` **v1.2.2**, and `MODULE_API_VERSION` **1.10.0**. Each phase's record is
|
||||
in its own section below; `edge` stays standing, unused, in every repository.
|
||||
|
||||
---
|
||||
|
||||
## Before anything: three facts about the ground
|
||||
@@ -2025,6 +2033,75 @@ core, docs, then the kit's re-pin and `runicgateway.com`.
|
||||
- **`.profile`** — the org landing page is updated when the *shape* of the project changes, which a new
|
||||
subsystem is.
|
||||
|
||||
> **16c BUILT (2026-09-09/10) — and it began by closing the cutover's missing seventh step.**
|
||||
> `runicgateway.com#30` and `.profile#6`, both onto `main`; the leg's first act was `docs#232`.
|
||||
>
|
||||
> #### The step 16b left on `edge`
|
||||
>
|
||||
> Six repositories were cut over and every one of them showed **0 commits on `edge` that are not on
|
||||
> `main`**. This one showed **46**. Step 6 (`#231`) landed the record *on* `edge` rather than cutting
|
||||
> `edge` over — an easy thing to miss, because the step's own PR merged green and closed. The
|
||||
> consequence was quiet and total: `docs` `main` opened `EVENTS.md` with *"revision 5. **No code
|
||||
> written.** Read against … `MODULE_API_VERSION` 1.9.0 · sidecar protocol 5"* while six repositories
|
||||
> shipped the engine on protocol 7, and `link/v6.md` and `v7.md` — the specs of record for two
|
||||
> protocol versions — existed on no default branch anywhere.
|
||||
>
|
||||
> **Nothing in this workstream could have caught it.** Every check that guards a contract lives in
|
||||
> the repository that *depends* on the contract, and a documentation repository has no dependants.
|
||||
> What found it was the one check that reads `docs` from outside: `runicgateway.com`'s
|
||||
> `checkReference.mjs` asserts every canonical document it names still exists on `main`, and adding
|
||||
> the current protocol spec failed with `✗ canonical doc link/v7.md`. **The site is the docs
|
||||
> repository's only dependant, and 16c is the only phase that would ever have run that check.**
|
||||
>
|
||||
> The merge was clean, and both `PROJECT_TREE.md` files stayed on `main`'s newer automated syncs —
|
||||
> `edge` never edited them, so git kept `main`'s side. `edge` stays standing, per 16b's decision,
|
||||
> now four generated commits behind.
|
||||
>
|
||||
> #### The site
|
||||
>
|
||||
> The checks were red before the phase started and named their own answers, which is the whole
|
||||
> bargain §12 of that repository's plan struck: nine `checkFacts` values (protocol 5 → **7** in all
|
||||
> three declaration sites, `moduleApi` → **1.10.0**, the bundle triple, `link` **v2.2.0**, `Module-uo`
|
||||
> **v1.2.2** — a third module release, one past the v1.2.1 the cutover cut), and **twenty-seven
|
||||
> `Bridge.cfg` keys** the site listed nowhere. Those became five groups rather than an appendix,
|
||||
> because `EventsEnabled` is a *second consent switch* and belongs beside the ceilings it governs
|
||||
> rather than filed under `AdminWriteEnabled`.
|
||||
>
|
||||
> Two pages, the treatment Teams has: **Scheduled events** under Administration and **Events
|
||||
> architecture**. Two capability entries, so the homepage, `/features/` and `/modules/` stop omitting
|
||||
> the subsystem — and the calendar one is deliberately **not** `needsModule`, because a bare core can
|
||||
> author and run an event and that marker means "present, correct and permanently empty".
|
||||
>
|
||||
> **`/privacy` owed a row and had none.** `event_run_participants` is personal data — scores and
|
||||
> ranks against a module-opaque member key, linked to an account where one is linked, feeding a
|
||||
> participant's own history. The new `deploy-events` row states the retention exactly, including the
|
||||
> asymmetry that matters: the diagnostic log is swept after 90 days **and only on terminal runs**,
|
||||
> while the run, its steps and its participants are never swept, because they are the record of what
|
||||
> was done to a shared world.
|
||||
>
|
||||
> **A naming collision worth fixing while it was cheap.** `reference/event-catalog` is about what a
|
||||
> shard *emits*; with a scheduled-event system shipped, two things in the documentation were called
|
||||
> an event catalog. Retitled **"Shard event catalog"**, with the route left alone so nothing outside
|
||||
> that repository breaks — and the page now opens by saying which of the two it is, since the kinds
|
||||
> it lists are exactly what a phase can wait for.
|
||||
>
|
||||
> **No screenshots**, and stated as a choice: capturing the events surfaces means standing the whole
|
||||
> rig back up for images no check requires, and the engagement workstream's site leg added none
|
||||
> either.
|
||||
>
|
||||
> #### `.profile`
|
||||
>
|
||||
> One bullet, and two stale numbers. The bullet says the posture rather than the feature list — off
|
||||
> by default, caps in the database, cleanup generated from a ledger, and *an event does not edit the
|
||||
> world, it holds a lease the game restores on its own deadline*. The numbers are protocol **5 → 7**
|
||||
> in the four values the installer prints (the block a reader copies into Admin → Shard, where a
|
||||
> wrong number is a pairing failure with no obvious cause) and **module-uo v1.1.0 → v1.2.2**.
|
||||
>
|
||||
> #### What 16c did not need
|
||||
>
|
||||
> No `EVENTS.md` change, no `MODULE_API_VERSION` change, no protocol change, no release. The phase
|
||||
> moves no contract — it makes the ones already moved legible from outside the organisation.
|
||||
|
||||
---
|
||||
|
||||
## What this plan does not do
|
||||
|
||||
@@ -169,6 +169,8 @@ website/
|
||||
│ │ ├── lib/
|
||||
│ │ │ ├── adminNav.js
|
||||
│ │ │ ├── engagementRules.js
|
||||
│ │ │ ├── eventAuthoring.js
|
||||
│ │ │ ├── eventCalendar.js
|
||||
│ │ │ ├── format.js
|
||||
│ │ │ ├── heroLayout.js
|
||||
│ │ │ ├── moduleAdmin.js
|
||||
@@ -216,6 +218,11 @@ website/
|
||||
│ │ │ │ │ ├── EngagementSuppressions.jsx
|
||||
│ │ │ │ │ ├── EngagementTemplates.jsx
|
||||
│ │ │ │ │ ├── EngagementTriggers.jsx
|
||||
│ │ │ │ │ ├── EventActions.jsx
|
||||
│ │ │ │ │ ├── EventEditor.jsx
|
||||
│ │ │ │ │ ├── EventRun.jsx
|
||||
│ │ │ │ │ ├── EventsAdmin.jsx
|
||||
│ │ │ │ │ ├── EventsCalendar.jsx
|
||||
│ │ │ │ │ ├── HeroEditor.jsx
|
||||
│ │ │ │ │ ├── InvitesAdmin.jsx
|
||||
│ │ │ │ │ ├── Moderation.jsx
|
||||
@@ -246,6 +253,7 @@ website/
|
||||
│ │ │ │ ├── ForgotPassword.jsx
|
||||
│ │ │ │ ├── PlayerAccount.jsx
|
||||
│ │ │ │ ├── PlayerAppeals.jsx
|
||||
│ │ │ │ ├── PlayerEvents.jsx
|
||||
│ │ │ │ ├── PlayerInbox.jsx
|
||||
│ │ │ │ ├── PlayerLogin.jsx
|
||||
│ │ │ │ ├── PlayerNotifications.jsx
|
||||
@@ -258,6 +266,9 @@ website/
|
||||
│ │ │ ├── public/
|
||||
│ │ │ │ ├── About.jsx
|
||||
│ │ │ │ ├── CmsPage.jsx
|
||||
│ │ │ │ ├── EventPage.jsx
|
||||
│ │ │ │ ├── Events.jsx
|
||||
│ │ │ │ ├── EventSeries.jsx
|
||||
│ │ │ │ ├── FiveOnFriday.jsx
|
||||
│ │ │ │ ├── Maintenance.jsx
|
||||
│ │ │ │ ├── News.jsx
|
||||
@@ -279,6 +290,8 @@ website/
|
||||
│ │ ├── apiClient.test.js
|
||||
│ │ ├── emailTemplates.test.js
|
||||
│ │ ├── engagementRules.test.js
|
||||
│ │ ├── eventAuthoring.test.js
|
||||
│ │ ├── eventCalendar.test.js
|
||||
│ │ ├── featureGate.test.js
|
||||
│ │ ├── format.test.js
|
||||
│ │ ├── heroLayout.test.js
|
||||
@@ -352,6 +365,7 @@ website/
|
||||
│ │ │ └── validateBlocks.js
|
||||
│ │ ├── config/
|
||||
│ │ │ ├── brand.js
|
||||
│ │ │ ├── coreEventActions.js
|
||||
│ │ │ ├── coreStreams.js
|
||||
│ │ │ ├── coreTriggers.js
|
||||
│ │ │ ├── csp.js
|
||||
@@ -393,6 +407,18 @@ website/
|
||||
│ │ │ ├── suppressions.js
|
||||
│ │ │ ├── templates.js
|
||||
│ │ │ └── templateSeeds.js
|
||||
│ │ ├── events/
|
||||
│ │ │ ├── announce.js
|
||||
│ │ │ ├── authorize.js
|
||||
│ │ │ ├── cleanup.js
|
||||
│ │ │ ├── dispatch.js
|
||||
│ │ │ ├── gates.js
|
||||
│ │ │ ├── ledger.js
|
||||
│ │ │ ├── participants.js
|
||||
│ │ │ ├── price.js
|
||||
│ │ │ ├── recurrence.js
|
||||
│ │ │ ├── spec.js
|
||||
│ │ │ └── verify.js
|
||||
│ │ ├── middleware/
|
||||
│ │ │ ├── botScore.js
|
||||
│ │ │ ├── loginProtection.js
|
||||
@@ -442,6 +468,25 @@ website/
|
||||
│ │ │ │ ├── engagementSuppressions.db.js
|
||||
│ │ │ │ ├── engagementTemplates.db.js
|
||||
│ │ │ │ └── engagementTemplates.model.js
|
||||
│ │ │ ├── events/
|
||||
│ │ │ │ ├── eventActionSettings.db.js
|
||||
│ │ │ │ ├── eventCalendar.model.js
|
||||
│ │ │ │ ├── eventDefinitions.db.js
|
||||
│ │ │ │ ├── eventDefinitions.model.js
|
||||
│ │ │ │ ├── eventJson.js
|
||||
│ │ │ │ ├── eventPhaseGates.db.js
|
||||
│ │ │ │ ├── eventPublic.model.js
|
||||
│ │ │ │ ├── eventRunBudget.db.js
|
||||
│ │ │ │ ├── eventRunControls.model.js
|
||||
│ │ │ │ ├── eventRunLog.db.js
|
||||
│ │ │ │ ├── eventRunParticipants.db.js
|
||||
│ │ │ │ ├── eventRunResources.db.js
|
||||
│ │ │ │ ├── eventRuns.db.js
|
||||
│ │ │ │ ├── eventRuns.model.js
|
||||
│ │ │ │ ├── eventRunSteps.db.js
|
||||
│ │ │ │ ├── eventSeries.db.js
|
||||
│ │ │ │ ├── eventSeries.model.js
|
||||
│ │ │ │ └── eventVersions.db.js
|
||||
│ │ │ ├── invites/
|
||||
│ │ │ │ ├── invites.db.js
|
||||
│ │ │ │ └── invites.model.js
|
||||
@@ -559,6 +604,8 @@ website/
|
||||
│ │ │ │ │ ├── emailConfig.controller.js
|
||||
│ │ │ │ │ ├── engagement.controller.js
|
||||
│ │ │ │ │ ├── engagement.router.js
|
||||
│ │ │ │ │ ├── events.controller.js
|
||||
│ │ │ │ │ ├── events.router.js
|
||||
│ │ │ │ │ ├── imageUpload.js
|
||||
│ │ │ │ │ ├── index.js
|
||||
│ │ │ │ │ ├── invites.controller.js
|
||||
@@ -607,6 +654,8 @@ website/
|
||||
│ │ │ │ ├── player/
|
||||
│ │ │ │ │ ├── appeals.controller.js
|
||||
│ │ │ │ │ ├── appeals.router.js
|
||||
│ │ │ │ │ ├── events.controller.js
|
||||
│ │ │ │ │ ├── events.router.js
|
||||
│ │ │ │ │ ├── index.js
|
||||
│ │ │ │ │ ├── teamForum.controller.js
|
||||
│ │ │ │ │ ├── teamForum.router.js
|
||||
@@ -615,6 +664,8 @@ website/
|
||||
│ │ │ │ ├── public/
|
||||
│ │ │ │ │ ├── engagement.controller.js
|
||||
│ │ │ │ │ ├── engagement.router.js
|
||||
│ │ │ │ │ ├── events.controller.js
|
||||
│ │ │ │ │ ├── events.router.js
|
||||
│ │ │ │ │ ├── index.js
|
||||
│ │ │ │ │ ├── modules.controller.js
|
||||
│ │ │ │ │ ├── modules.router.js
|
||||
@@ -646,6 +697,7 @@ website/
|
||||
│ │ │ ├── engagementEmit.js
|
||||
│ │ │ ├── engagementRetentionPrune.js
|
||||
│ │ │ ├── engagementWorker.js
|
||||
│ │ │ ├── eventRunner.js
|
||||
│ │ │ ├── forumHtml.js
|
||||
│ │ │ ├── htmlShell.js
|
||||
│ │ │ ├── logger.js
|
||||
@@ -718,6 +770,27 @@ website/
|
||||
│ │ ├── engagementRetentionSql.test.js
|
||||
│ │ ├── engagementTemplatesAdmin.test.js
|
||||
│ │ ├── engagementTriggers.test.js
|
||||
│ │ ├── eventActionRegistry.test.js
|
||||
│ │ ├── eventAnnounce.test.js
|
||||
│ │ ├── eventAuthorize.test.js
|
||||
│ │ ├── eventCleanup.test.js
|
||||
│ │ ├── eventGates.test.js
|
||||
│ │ ├── eventIntegrations.test.js
|
||||
│ │ ├── eventLedger.test.js
|
||||
│ │ ├── eventModuleContract.test.js
|
||||
│ │ ├── eventParticipants.test.js
|
||||
│ │ ├── eventPrice.test.js
|
||||
│ │ ├── eventPublic.test.js
|
||||
│ │ ├── eventRecurrence.test.js
|
||||
│ │ ├── eventRunControls.test.js
|
||||
│ │ ├── eventRunner.test.js
|
||||
│ │ ├── eventRunnerSql.test.js
|
||||
│ │ ├── eventsAdmin.test.js
|
||||
│ │ ├── eventSchedule.test.js
|
||||
│ │ ├── eventSeries.test.js
|
||||
│ │ ├── eventSpec.test.js
|
||||
│ │ ├── eventsRoles.test.js
|
||||
│ │ ├── eventVerify.test.js
|
||||
│ │ ├── honeypot.test.js
|
||||
│ │ ├── htmlShell.test.js
|
||||
│ │ ├── inviteController.test.js
|
||||
|
||||
@@ -1,34 +1,45 @@
|
||||
# Extracting from your own UO client (UOFiddler)
|
||||
|
||||
**Audience:** the shard operator, once, at setup time.
|
||||
**Related:** [`CLILOCS.md`](CLILOCS.md) (why the cliloc conversion is unavoidable),
|
||||
[`SPAWN_ATLAS.md`](SPAWN_ATLAS.md) (where creature art fits).
|
||||
**Related:** [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md) (where creature art fits),
|
||||
[`../link/v8.md`](../link/v8.md) (the Asset Bridge, which is replacing this page).
|
||||
|
||||
Two features read data that **only exists inside a UO client**, and a UO client's
|
||||
files are EA's, not ours to redistribute. So neither this repo nor any image we
|
||||
publish can ship them — the operator extracts from **their own** client, once,
|
||||
> ### The cliloc conversion is gone — you no longer do this by hand
|
||||
>
|
||||
> **Protocol 8, phase 2.** The shard reads its own client's `Cliloc.enu` and
|
||||
> serves the table over the bridge, so there is nothing to install, convert or
|
||||
> copy. Press **Admin → Shard → Import** after you patch your client and that is
|
||||
> the whole procedure; see [`CLILOCS.md`](CLILOCS.md).
|
||||
>
|
||||
> Part 1 of this guide has been deleted rather than rewritten. If you already
|
||||
> have a converted file it keeps working on an install with no uo-link
|
||||
> configured, but nobody should make a new one.
|
||||
>
|
||||
> **Creature art is next** (phase 5), after which this page goes away entirely.
|
||||
|
||||
What remains here reads data that **only exists inside a UO client**, and a UO
|
||||
client's files are EA's, not ours to redistribute. So neither this repo nor any
|
||||
image we publish can ship them — the operator extracts from **their own** client
|
||||
and points the site at the result.
|
||||
|
||||
| Feature | What it needs | Required? | Without it |
|
||||
|---|---|---|---|
|
||||
| **Item / title names** ([`CLILOCS.md`](CLILOCS.md)) | `Cliloc.enu`, converted | No | Names render as raw ids — `id 1023721` instead of *quarter staff* |
|
||||
| **Creature art** ([`SPAWN_ATLAS.md`](SPAWN_ATLAS.md)) | Sprites from `.mul`/`.uop` | No | Atlas pages render as text, which is the normal state |
|
||||
|
||||
**Both are optional and neither is load-bearing.** A shard that never does any of
|
||||
this is fully supported. Do part one and skip part two if art is not worth your
|
||||
time — they share only the tool.
|
||||
**It is optional and it is not load-bearing.** A shard that never does any of this
|
||||
is fully supported.
|
||||
|
||||
Everything you extract stays **outside the repository**: the converted cliloc
|
||||
file lives at a path you choose, and `spawnAtlas.art.json` plus `server/uploads/`
|
||||
are gitignored, so none of it can be committed by accident.
|
||||
Everything you extract stays **outside the repository**: `spawnAtlas.art.json` and
|
||||
`server/uploads/` are gitignored, so none of it can be committed by accident.
|
||||
|
||||
---
|
||||
|
||||
## Part 0 — Get UOFiddler
|
||||
|
||||
[UOFiddler](https://github.com/polserver/UOFiddler) is the community client-file
|
||||
editor. We use it because its `Ultima.dll` already contains the cliloc
|
||||
decompressor, maintained by people who do this for a living.
|
||||
editor. What is left here uses its GUI to export sprites; the `Ultima.dll` this
|
||||
guide used to reach for was the cliloc decompressor, and the shard has its own
|
||||
now.
|
||||
|
||||
1. Download the latest release zip from
|
||||
<https://github.com/polserver/UOFiddler/releases/latest> — one asset, named
|
||||
@@ -38,204 +49,30 @@ decompressor, maintained by people who do this for a living.
|
||||
|
||||
```
|
||||
UOFiddler-4.22.2/
|
||||
Ultima.dll ← the decompressor (Part 1 needs this path)
|
||||
UoFiddler.exe ← the GUI (Part 2 needs this)
|
||||
Ultima.dll
|
||||
plugins/
|
||||
…
|
||||
```
|
||||
|
||||
3. **Runtime:** UOFiddler 4.22.2 is built for **.NET 10**. Running `UoFiddler.exe`
|
||||
needs the .NET 10 **Desktop** Runtime (Windows only); loading `Ultima.dll` from
|
||||
the converter in Part 1 needs the .NET 10 runtime. Install from
|
||||
<https://dotnet.microsoft.com/download/dotnet/10.0>.
|
||||
3. **Runtime:** UOFiddler 4.22.2 is built for **.NET 10**, so running
|
||||
`UoFiddler.exe` needs the .NET 10 **Desktop** Runtime (Windows only). Install
|
||||
from <https://dotnet.microsoft.com/download/dotnet/10.0>.
|
||||
|
||||
### Finding your client files
|
||||
|
||||
The cliloc file is in your **UO client installation directory**, not in your
|
||||
ServUO tree — the shard server has no copy of it. Look for `Cliloc.enu` (English;
|
||||
the other seven are `chs`, `cht`, `deu`, `esp`, `fra`, `jpn`, `kor`) beside
|
||||
`art.mul` / `artLegacyMUL.uop`. The EA Classic Client's default location is:
|
||||
The art files are in your **UO client installation directory**. Look for
|
||||
`art.mul` / `artLegacyMUL.uop` and the `anim*.mul` set. The EA Classic Client's
|
||||
default location is:
|
||||
|
||||
```
|
||||
C:\Program Files (x86)\Electronic Arts\Ultima Online Classic\
|
||||
```
|
||||
|
||||
**If your shard distributes its own patched client to players, use that copy.**
|
||||
Any cliloc edits you shipped to players are then already in the base table and
|
||||
you need no overlay for them (see [`CLILOCS.md`](CLILOCS.md) §Shard-added and
|
||||
shard-edited items).
|
||||
|
||||
---
|
||||
|
||||
## Part 1 — Convert the cliloc table
|
||||
|
||||
**Goal:** turn the client's compressed `Cliloc.enu` into a file the site can
|
||||
read, and point the site at it.
|
||||
|
||||
The site cannot read `Cliloc.enu` directly. Every modern client compresses it
|
||||
(the "Mythic" container), and so does ServUO's own bundled `Ultima.StringList` —
|
||||
which is why the shard cannot supply names on our behalf either. The full
|
||||
reasoning is in [`CLILOCS.md`](CLILOCS.md) §Why the operator has to convert the
|
||||
file; this section is just the procedure.
|
||||
|
||||
Two routes. **The bundled tool is the recommended one** — the GUI export needs a
|
||||
fixup step, described below.
|
||||
|
||||
### Route A — the bundled converter (recommended)
|
||||
|
||||
Needs a .NET SDK (any version 8 or newer — the project targets `net8.0` and rolls
|
||||
forward, so whatever you have works) **plus** the .NET 10 runtime from Part 0,
|
||||
which is what actually loads `Ultima.dll`.
|
||||
|
||||
```bash
|
||||
cd website/server/tools/cliloc-export
|
||||
dotnet build -c Release
|
||||
|
||||
# plain binary — recommended, exact
|
||||
dotnet run -c Release -- \
|
||||
"/path/to/UOFiddler-4.22.2/Ultima.dll" \
|
||||
"/path/to/UO client/Cliloc.enu" \
|
||||
/srv/uo-data/clilocs.plain
|
||||
|
||||
# or tab-delimited text, if you want to eyeball or hand-edit it
|
||||
dotnet run -c Release -- \
|
||||
"/path/to/UOFiddler-4.22.2/Ultima.dll" \
|
||||
"/path/to/UO client/Cliloc.enu" \
|
||||
/srv/uo-data/clilocs.tsv --tsv
|
||||
```
|
||||
|
||||
Expected output for a stock English client:
|
||||
|
||||
```
|
||||
wrote 123490 entries to /srv/uo-data/clilocs.plain (maxTextBytes=12150, skippedOversize=0)
|
||||
```
|
||||
|
||||
**Sanity-check that number.** A stock `Cliloc.enu` is ~123,000 entries. A few
|
||||
hundred means it read something else and you should not ship the result. The
|
||||
tool exits non-zero and says `no entries were written — is that a cliloc file?`
|
||||
when it gets nothing at all.
|
||||
|
||||
The conversion runs on whatever machine has the client (usually Windows), and the
|
||||
site reads the output wherever it runs — so **copy the output file to the server**
|
||||
if those are different machines. It is a single self-contained file (~5 MB); the
|
||||
`--tsv` form is larger but diff-able.
|
||||
|
||||
<details>
|
||||
<summary>Errors you may hit</summary>
|
||||
|
||||
| Message | Cause |
|
||||
|---|---|
|
||||
| `Ultima.StringList not found — is that really UOFiddler's Ultima.dll?` | First argument points at some other `Ultima.dll` (ServUO ships one too — it is **not** the same assembly and cannot do this) |
|
||||
| `You must install .NET to run this application` | Missing the .NET 10 runtime from Part 0 step 3 |
|
||||
| `Unexpected Ultima.StringList API` | UOFiddler older than 4.21 |
|
||||
| `usage: clilocexport …` | Fewer than three arguments |
|
||||
|
||||
</details>
|
||||
|
||||
### Route B — the UOFiddler GUI
|
||||
|
||||
Use this if you would rather not install a .NET SDK. **It needs one extra step**,
|
||||
so do not skip the fixup.
|
||||
|
||||
1. Launch `UoFiddler.exe` and point it at your client directory when it asks
|
||||
(or **Options → Path Settings**).
|
||||
2. Open the **Cliloc** tab and use its **export to CSV** action.
|
||||
3. It writes `CliLoc.csv` to UOFiddler's configured output path, in **three**
|
||||
columns with a header row:
|
||||
|
||||
```
|
||||
Number;Text;Flag
|
||||
1023721;quarter staff;0
|
||||
```
|
||||
|
||||
4. **Strip the trailing flag column.** The site's text parser reads
|
||||
`number<TAB|,|;>text`, so that third field is otherwise absorbed into the name
|
||||
and every item on the site renders as `quarter staff;0`.
|
||||
|
||||
```bash
|
||||
sed -E 's/;[0-9]+$//' CliLoc.csv > clilocs.csv
|
||||
```
|
||||
|
||||
```powershell
|
||||
Get-Content CliLoc.csv |
|
||||
ForEach-Object { $_ -replace ';\d+$','' } |
|
||||
Set-Content -Encoding utf8 clilocs.csv
|
||||
```
|
||||
|
||||
The header row needs no removal — a line whose first field is not an integer
|
||||
is skipped. Blank entries (`1005008;`) survive the fixup correctly and are
|
||||
dropped at import, as intended.
|
||||
|
||||
5. Copy `clilocs.csv` to the server.
|
||||
|
||||
**Why the fixup is not just done for us:** the parser already handles
|
||||
`number,flag,text` — the flag in the *middle*, which is what several exports
|
||||
emit. UOFiddler puts it at the *end*, where it is indistinguishable from a name
|
||||
that genuinely ends in `;0`. One `sed` on the operator's side beats a parser
|
||||
heuristic that would corrupt real names.
|
||||
|
||||
### Point the site at it
|
||||
|
||||
Two ways, the setting winning over the environment:
|
||||
|
||||
| Where | How |
|
||||
|---|---|
|
||||
| **Admin → Shard → cliloc path** | Takes effect on the next refresh, no redeploy |
|
||||
| `UO_CLIENT_PATH` env var | The deploy-time default |
|
||||
|
||||
The value may be **the file itself or a directory to search** — both are natural
|
||||
answers to "where is it", and overlays are picked up either way.
|
||||
|
||||
Setting the path deliberately does **not** import as a side effect. Click
|
||||
**Import** (or `POST /api/v1/admin/shard/clilocs/import`) to load it.
|
||||
|
||||
### Verify
|
||||
|
||||
`GET /api/v1/admin/shard/clilocs`, or the Admin → Shard panel, reports what each
|
||||
source contributed:
|
||||
|
||||
```json
|
||||
"sources": [
|
||||
{ "label": "clilocs.plain", "kind": "base", "entries": 123490, "added": 123490, "overrode": 0 }
|
||||
]
|
||||
```
|
||||
|
||||
Roughly **67,500 rows stored** from a stock table is correct — about half a
|
||||
cliloc table is empty strings for ids the client reserves and never uses.
|
||||
|
||||
Then load any character sheet with equipment: items should show names rather than
|
||||
`id 1023721`.
|
||||
|
||||
<details>
|
||||
<summary>What a refusal means</summary>
|
||||
|
||||
A bad file answers `200` with a `status` and a named reason, not a `500` — you
|
||||
need to be told *which file* to fix.
|
||||
|
||||
| `code` | Meaning |
|
||||
|---|---|
|
||||
| `COMPRESSED` | You pointed at the raw client `Cliloc.enu`. Convert it — this whole page. |
|
||||
| `TRUNCATED` | Half-copied file. Re-copy; the loaded table is untouched. |
|
||||
| `EMPTY` | A text source with no parseable rows — the file is named in the reason. |
|
||||
| `status: needsReview` + `missingSources` | A previously-loaded source has vanished (unmounted volume? deliberate deletion?). Nothing changes until you re-import with `{ "approve": true }`. |
|
||||
|
||||
</details>
|
||||
|
||||
### Custom items — do *not* re-export for these
|
||||
|
||||
Shard-added items carry ids no client table has. Drop a small delimited file in a
|
||||
`custom/` directory beside the base file and re-import:
|
||||
|
||||
```
|
||||
/srv/uo-data/
|
||||
clilocs.plain ← base, from this guide
|
||||
custom/
|
||||
01-uomysticmoon.tsv ← your additions and overrides
|
||||
```
|
||||
|
||||
Files are read in sorted order and **later sources win**, so an overlay both adds
|
||||
new ids and overrides stock ones you have re-purposed. **Adding one item never
|
||||
means re-exporting a 5 MB client file.** Details in [`CLILOCS.md`](CLILOCS.md).
|
||||
**If your shard distributes its own patched client to players, use that copy** —
|
||||
it is what your players actually see. (It is also the copy the shard itself reads
|
||||
from, since a ServUO server resolves `Config/DataPath.cfg` into its own client
|
||||
path at boot, which is the premise the Asset Bridge is built on.)
|
||||
|
||||
---
|
||||
|
||||
@@ -246,7 +83,8 @@ functional as text, and `art` is NULL on every fresh import.
|
||||
|
||||
**This project ships no art and no art-extraction tooling, and never will.**
|
||||
|
||||
1. In `UoFiddler.exe` (paths configured as in Route B step 1), open the
|
||||
1. Open `UoFiddler.exe` and point it at your client directory
|
||||
(**Settings → Paths**), then open the
|
||||
**Animations** tab for creature sprites — or **Items** for object art — find
|
||||
the creature, and export as PNG. Right-click an entry for its export options,
|
||||
or use the tab's *Export All* action for a batch. (4.22.2 added an export
|
||||
|
||||
Reference in New Issue
Block a user