docs(protocol2): add Town Cryer news-gump integration design (§16)
Adds §16: sync website news articles into the modern Town Cryer News gump
(TownCryerSystem.NewsEntries), distinct from the Protocol 1.0 scrolling-crier
lines (GlobalTownCrierEntryList). Grounded in the shard's Town Cryer source.
Key findings / decisions:
- NewsEntries is a public mutable List and TownCryerNewsEntry's ctor is public,
and the display gumps already branch on Title/Body .Number>0 (cliloc) vs
string (AddLabelCropped / AddHtml with HTML support). So website content
needs NO gump changes and NO stock patch — the overlay inserts/removes
directly and tracks its own entries, leaving stock uo.com news intact.
(Refines the pasted guidance, which proposed adding methods to the stock
TownCryerSystem.cs = a patch.)
- Ties the two surfaces together: full article -> news gump; crier "says" just
the title via the existing GlobalTownCrierEntryList path.
- news.add/news.remove verbs (id-correlated, idempotent), POST /news +
DELETE /news/{id}; website is source of truth, re-synced on shard reconnect
since NewsEntries isn't persisted across reboot.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -477,3 +477,71 @@ Deployed the overlay to the ServUO checkout, booted the shard and the real sidec
|
||||
**Not exercised (needs a live UO client, not a headless boot):** `presence.online` with real players, `region.enter`, real-time `guild.join`, and `char.vitals`. And `guild.join`/guild board content needs a guild to exist. These are inherent to a clientless smoke test — the board *plumbing* is proven by `/houses`, which uses the identical path.
|
||||
|
||||
**One operational note surfaced:** the boot-time `Dynamic` script recompile **cannot replace `Scripts.dll` while the server is running**, because the Scripts build tries to copy the locked `ServUO.exe` and fails (the `PLAN.md §3` trap). The fix used here: build `Scripts/Scripts.csproj` once with the server **stopped**, then boot — the offline build produces a fresh `Scripts.dll` the boot then loads. Rely on this, not the in-process rebuild, when deploying new bridge code. The shard's world save was left untouched (hard-kill, no autosave), so the test accounts did not persist.
|
||||
|
||||
---
|
||||
|
||||
## 16. Town Cryer news — website articles into the news gump (Protocol 2.1)
|
||||
|
||||
**Status:** Design, grounded in the shard's `Scripts/Services/Town Cryer/` files. Not yet built.
|
||||
|
||||
There are **two** distinct town-crier surfaces in ServUO, and 2.0 has so far touched only the first:
|
||||
|
||||
1. **The scrolling crier** (`GlobalTownCrierEntryList`) — the wandering Town Crier NPC that *says* short announcement lines. Protocol 1.0 phase 6 (`BridgeTownCrier.cs`, `towncrier.add`/`remove`) already drives this.
|
||||
2. **The Town Cryer News gump** (`TownCryerSystem.NewsEntries`) — the paged news UI with title + body + image + a "more info" URL per article. **Nothing drives this yet.** This section adds it.
|
||||
|
||||
The ask: a website news article should land as a full article in the **news gump** (2), and the crier should also *say* just the **title** through the existing say feature (1) — so players get the audible "Hear ye!" proclamation while the full write-up lives in the gump.
|
||||
|
||||
### 16.1 The hook (verified in the shard's source)
|
||||
|
||||
- **`TownCryerSystem.NewsEntries`** (`TownCryerSystem.cs:40`) — `public static List<TownCryerNewsEntry>`. The setter is private, but the **list is public and mutable**, so it can be inserted into and removed from directly.
|
||||
- **`TownCryerNewsEntry(TextDefinition title, TextDefinition body, int gumpImage, Type questType, string url)`** (`TownCryerNewsEntry.cs`) — public ctor. Pass `questType: null` for website news.
|
||||
- **The display gumps already handle string content**, so no gump edits are needed:
|
||||
- List view (`TownCryerGump.cs:97-103`): `if (entry.Title.Number > 0) AddHtmlLocalized(...) else AddLabelCropped(..., entry.Title)`.
|
||||
- Detail view (`TownCryerNewsGump.cs:27-42`): `if (Entry.Body.Number > 0) AddHtmlLocalized(...) else AddHtml(..., Entry.Body.String, ..., true)` — a **string body renders as HTML** (so `<CENTER>…</CENTER><BR><BR>…` works), `AddImage(..., Entry.GumpImage)`, and `InfoUrl` becomes a `LaunchBrowser` button.
|
||||
- **Stock news is live on this shard.** `TownCryerSystem.Initialize()` adds ~18 hardcoded `uo.com` entries whenever `TownCryerSystem.Enabled` (`TownCryerSystem.cs:93-120`) — *not* gated by `UsePreloadedMessages` (that only gates a reload command). So the list is not empty, and our sync must not clobber it (see §16.3).
|
||||
|
||||
### 16.2 Evaluating the pasted guidance
|
||||
|
||||
The pasted analysis is **substantially correct** and useful — it identifies the right hook (`NewsEntries`), the right constructor, the cliloc-vs-string branching the gump already does, the image/url fields, and the important instinct to keep stock news separate. Two adjustments for *this* architecture:
|
||||
|
||||
- **No stock patch is needed.** The pasted plan adds `AddNewsEntry` / `ClearExternalNews` methods to the stock `TownCryerSystem.cs`. That file is stock ServUO, so editing it would ship as a `patches/` diff (like `PlayerVendorSale`). We can avoid that entirely: because `NewsEntries` is a **public mutable list**, the bridge overlay inserts and removes directly — `TownCryerSystem.NewsEntries.Insert(0, entry)` / `.Remove(entry)` — and keeps the "which entries are ours" bookkeeping in an **overlay-side list**, not in a new field on the stock class. This is exactly how `BridgeTownCrier` already mutates `GlobalTownCrierEntryList` from the overlay. Pure overlay, zero stock edits.
|
||||
- **Track our entries to keep stock intact.** Rather than the pasted `ExternalNewsEntries` field on the stock class, the overlay holds `List<TownCryerNewsEntry> _ours`. On a sync we `Remove` our previous entries from `NewsEntries` and insert the new set — the stock `uo.com` articles are never touched. `MaxNewsEntries` is 100 (`TownCryerSystem.cs:26`); the overlay caps its own contribution well under that.
|
||||
|
||||
Everything else in the pasted note stands, and the "this is one of the easier integrations — you're replacing the content provider" framing is right.
|
||||
|
||||
### 16.3 The two surfaces, tied together
|
||||
|
||||
On an inbound article the bridge does two things on the Core thread:
|
||||
|
||||
1. **News gump** — build `new TownCryerNewsEntry(new TextDefinition(title), new TextDefinition(body), image, null, url)` and `Insert(0, …)` at the top of `TownCryerSystem.NewsEntries`, tracking it in `_ours`; trim `_ours` past the cap by removing the oldest (from both `_ours` and `NewsEntries`).
|
||||
2. **Say the title** — reuse the scrolling-crier path (`GlobalTownCrierEntryList`, as `BridgeTownCrier` does) to announce a single line, the **title only**, for a short duration, so the crier proclaims it in-world. Optional per article (`announce: true`), so silent corrections don't re-proclaim.
|
||||
|
||||
### 16.4 Protocol
|
||||
|
||||
```jsonc
|
||||
// website → sidecar → shard
|
||||
{"kind":"news.add","id":"42","title":"Double XP Weekend",
|
||||
"body":"<CENTER>Double XP Weekend</CENTER><BR><BR>Starts Friday 7PM.",
|
||||
"image":1614,"url":"https://uomysticmoon.com/news/42","announce":true}
|
||||
{"kind":"news.remove","id":"42"}
|
||||
```
|
||||
|
||||
- Correlated by `id` (echoed on the reply), like town-crier. Re-adding an `id` **replaces** the prior entry (find-by-id in `_ours`, remove, re-insert) — idempotent.
|
||||
- `title` required; `body`/`image`/`url` optional (a title-only blurb is valid). `image` defaults to a neutral scroll gump id when absent.
|
||||
- Caps (defense in depth, mirroring `TownCrier*`): title/body length, max external entries. Replies `news.ok` / `news.error`.
|
||||
- Sidecar: `POST /news` (add/replace), `DELETE /news/{id}`. Same `respond`-style status mapping as town-crier.
|
||||
|
||||
### 16.5 Restart & re-sync (the source-of-truth rule)
|
||||
|
||||
`NewsEntries` is **not persisted** by ServUO — it is rebuilt at every boot from stock `Initialize()` plus whatever we have inserted since. So our external articles vanish on a shard restart until re-pushed. The **website is the source of truth**: the sidecar re-sends the current external news set on every shard (re)connect, the same discipline §12.2 uses for the diff boards. (The sidecar persists the external set in its store so it can replay it without the website being up.)
|
||||
|
||||
### 16.6 Where the code goes
|
||||
|
||||
| File | Responsibility |
|
||||
|------|----------------|
|
||||
| `overlay/Scripts/Custom/Bridge/BridgeNews.cs` | **New.** `news.add` / `news.remove`: insert/remove `TownCryerNewsEntry` in the public `NewsEntries` list, track `_ours`, cap; optional title announcement via `GlobalTownCrierEntryList`; replies + caps. No stock edit. |
|
||||
| `overlay/Config/Bridge.cfg` | **Extend.** `NewsMaxTitleLength`, `NewsMaxBodyLength`, `NewsMaxExternal`, default announce duration. |
|
||||
| `sidecar/src/web.rs` + `store.rs` | **Extend.** `POST /news`, `DELETE /news/{id}`; persist the external-news set; replay it on shard (re)connect. |
|
||||
| `docs/INTEGRATION.md` | **Extend.** The `news.*` verbs + endpoints. |
|
||||
|
||||
No core or stock ServUO change — the whole integration rides the public `TownCryerSystem.NewsEntries` list and the existing crier say path.
|
||||
|
||||
Reference in New Issue
Block a user