Files

wtclaude b818f6cf37 feat(bridge): protocol 5 — decay schedule, vendor fee state, and a login result

Three emitter changes and the overlay's protocol declaration, in one PR because
"The bridge is a contract": overlay.toml must be bumped in the same change as the
emitters or the next bundle silently fails to compose.

BridgeSweeps — house.decay gains ownerName and a nested `schedule`
{dynamicDecay, nextStage, decayPeriodSec, estimatedCollapse}.

estimatedCollapse is emitted only where ServUO can actually know it. Dynamic decay
(Core.ML) draws each stage's duration at RANDOM when the stage is entered, so
NextDecayStage is exact for the next transition and nothing beyond it is known —
collapse becomes exact only at IDOC, where the next transition IS the collapse.
Static decay is a pure function of LastRefreshed and DecayPeriod, so it is exact at
every stage. Emitting it anywhere else would publish a guess as a fact, and on the
website's side that becomes a dated promise in someone's mail.

BridgeMarket — vendor.listing gains ownerAcct and a nested `fees` block.

ownerAcct is the one that matters structurally: the frame has carried ownerName
since v3, but a character name joins to nothing — only the game account is the
website's link key. The fees block resolves PlayerVendor.PayTimer's dismissal rule
(pay > totalGold => Destroy) on the shard, because both halves of that comparison
differ between ServUO's two vendor systems and re-deriving them downstream would be
a second implementation of a rule that lives in core.

No daysRemaining: under the old vendor system a pay period is a UO day
(Clock.MinutesPerUODay, about two real hours), so the obvious name would be wrong
by a factor of twelve on exactly the shards least likely to notice. periodsRemaining
plus the interval, and dismissalAt as an instant. A commission vendor has no pay
timer at all and reports exempt with no schedule — "never dismissed" is not the same
as "dismissed in 400 days".

BridgeEvents — a new account.login.result kind.

EventSink.AccountLogin is a veto hook that fires BEFORE the auth decision, and
AccountLoginEventArgs constructs with Accepted = true, so the existing
account.login.attempt fires on successful logins too and cannot carry a verdict. A
security rule built on it would have mailed "someone tried to get into your account"
every time the player logged in.

The verdict is read one Core slice later via DelayCall(Zero). That needs no core
patch AND does not depend on handler subscription order, which ServUO does not define
and a shard's own scripts can change. reason is omitted on an accept, because
ALRReason's zero value is Invalid and would read as a failure reason. The address is
resolved inside the handler, since AccountLogin_ReplyRej disposes the NetState before
the deferred read runs. The password is never read, logged or emitted.

tools/scaffolding/BridgeProtocol5Probe.cs drives all three on a live shard, and the
README records the two traps it took to get there — both of which produce SILENCE
rather than an error, so each looks exactly like a broken emitter:

  * An in-process login probe can never produce accepted:true. AccountHandler calls
    acct.HasAccess(e.State) BEFORE it checks the password, and a null NetState fails
    that. Only a real socket proves the accepted half — and it is the better test
    anyway, since it also produces the real ip.
  * Forcing a decay stage on a house that cannot decay emits nothing at all. Only
    Condemned and ManualRefresh houses decay; an AutoRefresh one — and the owner's
    NEWEST house is always AutoRefresh — has a DecayLevel getter that calls
    ResetDynamicDecay() and reports Ageless, wiping the forced stage before the sweep
    reads it.

Verified on the local rig against the release sidecar: a house walked
Fairly -> Greatly -> IDOC carried estimatedCollapse on the IDOC frame and only there;
every vendor's periodsRemaining matched funds/chargePerPeriod, including one at 0
whose dismissalAt equals its next tick; a real socket login gave
accepted:false reason:BadPass and then accepted:true. Compiles clean against ServUO
57.4 reference assemblies.

Docs: RunicGateway/docs link/v5.md.

Co-Authored-By: Claude <noreply@anthropic.com>

2026-08-31 19:19:34 -05:00

10 KiB

Raw Blame History

Test scaffolding

Not part of the bridge. Never deployed. deploy.ps1 only copies overlay/, so nothing here reaches a server unless you put it there by hand.

These two scripts produced the measured budget in PLAN.md §1. They are kept because those numbers should be reproducible, and because re-running the probe is the only honest way to check whether a change to the plugin's read path got more expensive.

File	Server path when testing	What
`BridgeSeeder.cs`	`Scripts/Custom/BridgeSeeder.cs`	Populates a synthetic world: 50 accounts, 150 characters, 30 houses, 30 player vendors with 40 listings each.
`BridgeProbe.cs`	`Scripts/Custom/BridgeProbe.cs`	Times every read the plugin performs, on the Core thread. Read-only.
`BridgeEventProbe.cs`	`Scripts/Custom/BridgeEventProbe.cs`	Fires gold/fame/karma/save events through their real code paths so the emit path can be verified without a game client. Mutates the world and saves. Flag: `EventProbeOnStart`.
`BridgeSweepProbe.cs`	`Scripts/Custom/BridgeSweepProbe.cs`	Bumps one seeded house's decay stage after baseline so the decay sweep's transition detection can be observed without waiting a real IDOC stage. Flag: `SweepProbeOnStart`. Pair with short `*SweepSeconds` overrides.
`BridgeLinkProbe.cs`	`Scripts/Custom/BridgeLinkProbe.cs`	Triggers `[link` for seed_001 without a client, then saves so the `WebsiteUserId` tag reaches `accounts.xml`. Flag: `LinkProbeOnStart`. Pair with a sidecar that reads the code and sends `link.confirm`.
`BridgeCrierProbe.cs`	`Scripts/Custom/BridgeCrierProbe.cs`	Logs the global town-crier entry list every 3s so `towncrier.add` / `remove` can be seen landing in game state. Flag: `CrierProbeOnStart`.
`BridgeVendorSaleProbe.cs`	`Scripts/Custom/BridgeVendorSaleProbe.cs`	Fires `PlayerVendorSale` (Phase 7) with real seeded-vendor data so `vendor.sale` can be verified without a live buy. Requires the Phase 7 patches applied. Flag: `VendorSaleProbeOnStart`.
`BridgeDemoDress.cs`	`Scripts/Custom/BridgeDemoDress.cs`	Renames a seeded world so it is presentable in a screenshot: shop signs, vendor and character names, house signs. Also stages a few condemned houses back into IDOC, and sets a known password on `seed_000` so a character can be logged in. Flags: `DemoDressOnStart`, `DemoDressPassword`. In game: `[demodress`.
`BridgeProtocol5Probe.cs`	`Scripts/Custom/BridgeProtocol5Probe.cs`	Drives all three Protocol 5 enrichments so their frames can be observed: walks one house Fairly -> Greatly -> IDOC (the PAIR is the assertion -- `estimatedCollapse` must appear only on the IDOC frame), reports each player vendor's fee state straight off the `PlayerVendor` so the emitted `fees` block can be checked against the shard's own numbers, and fires `EventSink.AccountLogin`. Flags: `Protocol5ProbeOnStart`, `Protocol5ProbeAccount`, `Protocol5ProbePassword`. In game: `[p5probe`. Sets a password on the named account.

Deploy overwrites Bridge.cfg

deploy.ps1 copies overlay/Config/Bridge.cfg, which deliberately omits the scaffolding flags. So every deploy strips SeedOnStart / EventProbeOnStart / etc. Re-append the flag you need after deploying, or the probe silently does nothing on the next boot. (This bit once during Phase 2 testing.)

Using them

Copy both into Scripts/Custom/, then append the flags to Config/Bridge.cfg:

SeedOnStart=True
CensusOnStart=False
ProbeOnStart=False

Boot once to seed and save, then set SeedOnStart=False. CensusOnStart reports what the loaded world actually contains; ProbeOnStart prints timings two seconds after ServerStarted.

Because Config.Get returns false for a missing key, a server whose Bridge.cfg lacks these keys never runs the scaffolding — even if the .cs files are sitting in Scripts/Custom/. That is the safety net, not an excuse to ship them.

In-game, [seedworld and [unseedworld (Administrator) do the same work on a live shard.

Dressing a seeded world for screenshots

BridgeSeeder builds a world at realistic scale, which is all the bridge ever needed. It does not build one that looks like anything: a vendor is seed vendor trading as Seed Shop 810, a character is Seed004A, a house sign says Seed House 12. Those strings travel the whole bridge and land on the marketplace, the guild roster and the housing pages of the website — fine for a protocol test, wrong for a screenshot.

BridgeDemoDress.cs renames them in place. It seeds nothing: prices, listing counts, decay stages, fame and skills stay exactly as the seeder left them and as the shard has moved them since, so the data keeps its provenance and only the strings a human reads change. Names are drawn from fixed tables by a hash of each object's serial, so a re-run reproduces the same world, and shop and house names are re-dressed when they are names the pass itself produced — so a change to the tables can be applied to a world that has already been through here.

DemoDressOnStart=True
DemoDressPassword=<a password you choose>

Boot once, then set DemoDressOnStart=False. The password is written to seed_000 so a real client can log a character in — the only way to make the website's online roster non-empty — and it is read from the config rather than compiled in, so it never lands in source control.

It dresses seeded objects only, which means your own characters keep their names. That is the right behaviour for a test shard and a thing to remember before pointing a camera at one: a dev world usually also holds the accounts, characters, guilds and houses of whoever built it, and those are real identifiers on a page that may end up public.

The sidecar's board is cached, so the website lags a rename. A shop name reaches the site on the next market sweep, and a sweep advances MarketSweepBatch vendors per tick — 27 vendors at the defaults is two ticks. Allow a couple of minutes before concluding that a rename failed. This cost a debugging detour once: the shard had the new names all along and the sidecar was still serving the previous ones.

Back up `Saves/` first

[seedworld and SeedOnStart write to the live world. Copy Saves/ somewhere outside the repo before running either. Backups/Automatic is rotated by AutoSave.cs and Backups/Temp is deleted outright, so neither is a safe destination.

[unseedworld deletes every seed_* account, which takes their characters and houses with it — but not necessarily their PlayerVendor mobiles. Restoring a backup is the reliable reset.

What the seeder had to work around

Worth knowing before you trust its output:

Plate needs strength. BaseArmor.CanEquip rejects when from.Str < strReq (PlateChest needs 95). A rejected EquipItem leaves the item parentless, and the Cleanup pass later deletes it en masse. The seeder gives characters Str 100–125 and deletes any item whose equip is refused, rather than orphaning it.
VendorItem.Price is get-only and PlayerVendor.SetVendorItem is private. Dropping an item into a vendor's pack fires OnSubItemAdded, which registers the item at the default price of 999. The seeder reaches SetVendorItem by reflection to set a real price. Acceptable in throwaway scaffolding; do not do this in the plugin.
Houses only decay when condemned. BaseHouse.CanDecay is true only for DecayType.Condemned or ManualRefresh. An active owner's newest house is AutoRefresh and never decays. The seeder backdates 18 accounts past Account.InactiveDuration (180 days) to condemn them, then forces stages with SetDynamicDecay — not by backdating LastRefreshed, because DynamicDecay.Enabled is true on this expansion and GetOldDecayLevel is unreachable.

Reference output

Census after a fresh load of the seeded world:

[BridgeSeeder] houses=35
[BridgeSeeder]   decay Ageless 13, Slightly 3, Somewhat 7, Fairly 3, Greatly 3, IDOC 6
[BridgeSeeder] seeded chars=150 avgEquipped=8.00 naked=0
[BridgeSeeder] playervendors=30

Probe, best-of-20 on the Core thread:

[BridgeProbe] char.profile      0.069 ms/char     2386 bytes json
[BridgeProbe] vitals sweep      0.223 ms  for 150 chars   (0.0015 ms/char)
[BridgeProbe] decay sweep       0.007 ms  for 35 houses   (0.0002 ms/house)
[BridgeProbe] economy sweep     0.001 ms  for 51 accounts (supply 110,478,209 gold)
[BridgeProbe] vendor snap       0.343 ms  for 30 vendors  (1200 listings)

Seeded characters carry 8 items with ~6 mods each and ~12 trained skills. A real endgame character has more of both, so profile cost and payload are a floor — budget 2–4× for a fully-kitted character.

BridgeProtocol5Probe fires EventSink.InvokeAccountLogin directly, which proves the REJECTED half of account.login.result and nothing more. ServUO's own AccountHandler calls acct.HasAccess(e.State) before it ever checks the password, and a null NetState fails that -- so an in-process probe logs Access denied for a correct password too, and never produces an accepted:true.

To prove the accepted half, speak the wire. A real socket also gives the frame a real ip, which is one of the fields being tested:

# 4-byte seed, then 0x80 = [0x80][30b username][30b password][1b]
s = socket.create_connection(('127.0.0.1', 2593))
s.sendall(b'\x7f\x00\x00\x01')
s.sendall(b'\x80' + pad(user) + pad(password) + b'\x5d')

The shard logs Invalid password for '<acct>' or Valid credentials for '<acct>', and the sidecar's /history?kind=account.login.result should show accepted:false reason:BadPass and accepted:true respectively. Both saying accepted:true is the bug the kind exists to prevent -- it means the verdict was read inside the handler, before it existed.

Walking a house into IDOC needs a house that can decay

Only a Condemned or ManualRefresh house decays. An AutoRefresh one -- and the owner's NEWEST house is always AutoRefresh -- has a DecayLevel getter that calls ResetDynamicDecay() and reports Ageless, so a forced SetDynamicDecay is wiped on the very next read, the sweep sees no change, and nothing is emitted at all. That looks exactly like a broken emitter. Filter on house.CanDecay, and expect a seeded world to have only one or two houses that qualify -- both probably already at IDOC, so the walk has to put one back down first.

10 KiB Raw Blame History Unescape Escape