Merge pull request 'docs(rust): paid RaidableBases spiked on both rigs (PLAN_REDESIGNS §11.4.2, D386–D390)' (#360) from docs/raidablebases-paid-spike into main

Reviewed-on: #360

modules/rust/PLAN_REDESIGNS.md

@@ -11,7 +11,7 @@ chose neither route: Runic Gateway writes its own NPC plugin, RunicNPC, planned
 [`../../runicnpc/PLAN.md`](../../runicnpc/PLAN.md) (D214–D314), and the rest of this plan waits for it.** RunicNPC v1.0.0 shipped on 2026-10-09, and the plan
 resumed with §2 the same day (D331–D334); §2 was built on 2026-10-12, and §11's Economics spike the same day
 raised D335–D336 (§11.2.1). Economics was built on 2026-10-12 too (§11.2.4). The Backpacks spike followed and raised D337–D339 (§11.3.1), and Backpacks was built the same day (D340, D341, §11.3.4). The org lead then added permission rewards (§12,
-D342–D346), planned and built the same day. On 2026-10-14 RaidableBases was deferred until the current paid copy arrives (D347), with both editions to be supported (D348, §11.4.2). The same day the org lead added Rust's own world events to the base module (§13, D349) and six more first-class optional plugins (§14, D350–D352), to be tested together in one phase before their integration plan. Their questions were answered the same day (D353–D359, the end walk now waiting for RaidableBases), and Steam sign-in stays on the website's plan, linked as §15 (D360). **The §14.2 test phase ran the same day on both rigs (§14.2.1)**: the org lead ruled D361–D362 during it and answered its Q19–Q25 the same day (D363–D369). On 2026-10-16 the org lead added console commands as event steps and rewards (§16, D382–D384), to be built before RaidableBases; **they were built the same day (§16.10)**, with D385. **Every item left is built, tested and PR'd first; every walk —
+D342–D346), planned and built the same day. On 2026-10-14 RaidableBases was deferred until the current paid copy arrives (D347), with both editions to be supported (D348, §11.4.2). The same day the org lead added Rust's own world events to the base module (§13, D349) and six more first-class optional plugins (§14, D350–D352), to be tested together in one phase before their integration plan. Their questions were answered the same day (D353–D359, the end walk now waiting for RaidableBases), and Steam sign-in stays on the website's plan, linked as §15 (D360). **The §14.2 test phase ran the same day on both rigs (§14.2.1)**: the org lead ruled D361–D362 during it and answered its Q19–Q25 the same day (D363–D369). On 2026-10-16 the org lead added console commands as event steps and rewards (§16, D382–D384), to be built before RaidableBases; **they were built the same day (§16.10)**, with D385. The same day the paid RaidableBases copy arrived; **its spike ran on both rigs (§11.4.2)**, with D386 and four questions, Q33–Q36, answered the same day (D387–D390). **Every item left is built, tested and PR'd first; every walk —
 theirs and the ones still owed by §3 and §5 — happens together at the end (D331, §9).**
 
 This is a companion to [`PLAN_FIXES.md`](PLAN_FIXES.md) and [`PLAN.md`](PLAN.md). Where they disagree, this
@@ -923,8 +923,9 @@ pulls) is research, not a walk, so it still comes first:
 6. **The step editor and the kit weekend** (§2). It is core's, so it can be built alongside any of the above.
    It goes out as its own website PR with the Module-uo proof.
 7. **The first-class optional plugins** (§11): Economics, then Backpacks, then RaidableBases, each starting
-   with its source pull and rig spike. Economics and Backpacks were built on 2026-10-12. **RaidableBases waits
-   for the current paid copy (D347)** and is built for both editions (D348).
+   with its source pull and rig spike. Economics and Backpacks were built on 2026-10-12. **RaidableBases waited
+   for the current paid copy (D347)** and is built for both editions (D348). **The copy arrived on 2026-10-16
+   and was spiked on both rigs the same day (§11.4.2)**, with D386. Q33–Q36 were answered the same day (D387–D390).
 8. **Permissions as event rewards** (§12), built on 2026-10-12.
 9. **Rust's own world events and six more optional plugins** (§13, §14). First comes one test phase covering
    all of them on both rigs (§14.2, D352); **it ran on 2026-10-14 (§14.2.1)**. Then one integration plan,
@@ -1103,6 +1104,12 @@ The org lead answered §14.3's Q26–Q32 on 2026-10-14:
 | **D380** | **A guarded crate left standing is noted in the run log when it is placed, not when the run ends:** the *Place a guarded crate* step's success line says the crate is kept when the run ends and how it ends (org lead, 2026-10-15). Core gives a module no hook at a run's end for a step that is kept, so D373's note at the end would need new core work. | A run-end hook in core now (a MODULE_API minor, with the Module-uo proof), or filed for later. | 14.3.5, 14.3.19 |
 | **D381** | **Server Rewards is taken off the plan** (org lead, 2026-10-16: *"I do not want it"*). Stage 8 is not built. Gone with it: `integrations.serverRewards`, `points.pay` / `balances` / `adjust` and the sidecar's three routes, the tally's `points`, the step `rust.points.pay` and its budget, the `rust_player_points` table, staff add and take, the app's RP balance, and the *Hoarder* title and its column. It amends D350 (five plugins, not six), D369 (its wipe half now covers ZLevels only), D375 and D377 (no *Hoarder*). Nothing had been built. §14.2.1's test findings stay as a record. | Building §14.3.7 as planned. | 14, 14.3.7, 14.3.11 |
 
+| **D386** | **RaidableBases' names come from the installed plugin, never from our code** (org lead, 2026-10-16, during the paid spike: *"it has to be loaded from the plugin because people can have different ones and even ones they created themselves"*). Difficulty names and levels, profile names and base names are read at run time and carried as the plugin's own strings, with the plugin's level int. No list of them is written into the plugin, sidecar, module or site, and tests use invented names. The same goes for the plugin's internal types: `RaidableType` is bound by name. This amends D202 and D205 (*"the paid edition offers its five"*): the step offers whatever the installed copy lists. | The five built-in difficulties as a fixed list, with *Normal* for the free edition. | 11.4.2, 11.4.3 |
+| **D387** | **A spot spawn takes the helper's route on both editions whenever the helper is installed (Q33).** The paid edition's own `SpawnRandomBase` is used only without the helper: it gives a position and a difficulty, but no height, no overrides and no area check, and the step says so. One spot path is built and tested for both editions. | The paid call whenever it exists, with the helper adding only the tag and overrides. | 11.4.2, 11.4.5 |
+| **D388** | **The area check refuses for buildings, deployables, raid bases, players and water; rocks and cliffs are a warning (Q34).** The plugin's own reason is read from its message queue and shown in the editor and the run log, and a spot with only rocks or cliffs near it still spawns. This amends D208. | Refusing on every reason the plugin gives (D208 as written); advice only. | 11.4.2, 11.4.5 |
+| **D389** | **"In water" is refused unless the chosen profile is built for it (Q35):** its seabed chance is above 0, or it allows bases to float above water. Both are read from the profile the step picked. This amends D208. | Always refusing water. | 11.4.2, 11.4.5 |
+| **D390** | **Lockouts are dropped from the feed (Q36).** Neither edition raises a hook for them. On the paid edition the feed gains a line when a player buys a base (`OnRaidableBasePurchased`) and when an admin locks one to a player (`OnRaidableBaseLocked`), naming the player only for the presence audience (D376). This amends D202. | Dropping them with no new lines; reading lockouts out of the plugin's data by reflection. | 11.4.2 |
+
 Console commands as event steps and rewards, added on 2026-10-16, were decided as D382–D384, and D385 during the build; they are tabled with their section, in §16.7.
 
 ## 11. First-class optional plugins (D199–D202)
@@ -1598,10 +1605,13 @@ the end" is not possible on the free edition through anything RaidableBases offe
 it does offer is: spawn a named base, somewhere, now; learn where and when it will despawn from the hook;
 and remove every base at once. §11.4.3 asks which way to go.
 
-#### 11.4.2 The paid edition: an old copy read (2026-10-14), the current copy still to come
+#### 11.4.2 The paid edition: an old copy read (2026-10-14), the current copy spiked (2026-10-16)
 
-**RaidableBases is deferred until the org lead supplies the current paid copy (D347). Runic Gateway supports
-both editions as far as each allows (D348).**
+**RaidableBases was deferred until the org lead supplied the current paid copy (D347). Runic Gateway supports
+both editions as far as each allows (D348).** The current copy arrived on 2026-10-16 and was spiked on both
+rigs the same day ("The current paid copy, spiked" below). **Its names are the operator's: every difficulty,
+profile and base name is read from the installed plugin, never written into our code (D386).** Q33–Q36 were answered
+the same day (D387–D390).
 
 The only paid copy at hand on 2026-10-14 was **3.0.5, from 2025-05-03** (`IsPremium()` returns `true`). By then
 uMod's free edition was **3.2.2**; the spikes above ran on 3.2.0. The org lead asked for the free source to be
@@ -1643,7 +1653,7 @@ than paid against free. The current paid copy settles which.
 | Ranked ladder | A player's `Raids` and `TotalRaids` | Adds `Points`, `TotalPoints` and a count per difficulty | none: *Warlord* counts from the bridge's own `Completed` hook |
 | `loadTime` | `Time.realtimeSinceStartup` | `Time.time` | nothing we read |
 
-**When the current paid copy arrives**, the same spike runs against it on both rigs, and this section records:
+**The spike's checklist**, written for the current paid copy and answered on 2026-10-16 below:
 
 - its version, and a fresh read of the free edition's at the same time, since each may have moved;
 - `IsPremium()`, and whether it has `GetAllDifficulties()`, `GetRaidableModes()` or both;
@@ -1669,12 +1679,176 @@ an edition:
   the helper's route (§11.4.4) where there isn't.
 - **Where a part has no route on the installed copy, the site says so** on the step, the page or the feed,
   as D199 does for a missing plugin. It never offers something that fails at run time. The open cases on
-  3.0.5 are the lock (D206) and lockouts in the feed.
+  3.0.5 were the lock (D206) and lockouts in the feed. On the current copy the lock has its route again, and
+  lockouts still have none (Q36).
 - **The checks D348 adds are part of the build's tests:** each mechanism is exercised against both editions'
   shapes, and the end walk (D331) covers a rig with each edition.
 
 The design in §11.4.3–§11.4.5 stays, and D348 governs how it is built. Which route each part takes on the
-current paid edition is recorded here after its spike, before any §11.4 code.
+current paid edition is recorded below, from its spike, before any §11.4 code.
+
+##### The current paid copy, spiked (2026-10-16)
+
+The org lead supplied the paid plugin, CopyPaste and the author's **tier-3 base pack** (50 bases, ten for each
+of the pack's five difficulties, with their profiles, loot tables and a config). Builds: Rust 25902425,
+Oxide 2.0.7830, Carbon 2.0.262, all the latest. Both rigs (the 6000 map, seed 981448696) got CopyPaste 4.3.0,
+the paid plugin and the pack, and a throwaway spike plugin drove everything below by console. Afterwards the
+bases were despawned, and the spike plugin, RaidableBases and CopyPaste were deleted from both rigs. The
+pack's config and data stay on the rigs for the end walk, which only has to put the two plugins back (and
+waits up to ten minutes for the grid, below). The paid source and the pack stay on the org lead's machine, as
+§14 requires.
+
+**Version and drift.** The paid copy is **3.2.2**, the same version as uMod's free edition (re-read the same
+day: still 3.2.2). The two share their whole public surface. **So the 3.0.5 table above was old against new,
+not paid against free**, except for the rows marked here:
+
+- **The same in both now:** `GetAllDifficulties()`; `GetAllEvents()` and `GetAllEventsNonAlloc` with the same
+  18-field tuple, and the two count calls; `BypassUseOwners()` and the Manual and Management lock pairs;
+  `loadTime` from `Time.realtimeSinceStartup`; `OnRaidableBaseUnlocked` and the 17-argument
+  `OnRaidableAwardOwner`.
+- **Paid only, still:** `GetRaidableModes()`; the private `SpawnRandomBase` that takes a position; the
+  seabed option; the buying hooks; a 5-argument `OnRaidableBaseCompleted` overload,
+  `(Vector3, int level, bool pvp, ulong owner, List<ulong> raiders)`; the area check's optional last
+  parameter.
+- **New:** **the paid `RaidableType` has `Purchased` at 3**, so `Maintained` and `Grid` are 4 and 5 there
+  but 3 and 4 in the free edition. Anything that passes a type binds it by name.
+
+**`IsPremium()`** returns `true`. Both rigs answered every call below the same way.
+
+**Difficulties are the operator's data, not a list in the plugin (D386).** A paid profile carries
+`"Difficulty"` (a name) and `"Difficulty Level"` (an int), and the console command `rb.difficulty` makes new
+ones. The pack ships Easy (0), Medium (1), Hard (2), Expert (3) and Nightmare (4). The spike added a profile
+of its own, *Wobbly* at level 7. After `rb.reloadprofiles` (no plugin reload), `GetAllDifficulties()` and
+`GetRaidableModes()` both listed it on both rigs, `rbevent Wobbly` spawned its base, and `Started` carried
+`level=7`. The two calls answer differently:
+
+- `GetAllDifficulties()` returns one `(name, level)` per **profile**, unsorted, so a name repeats when two
+  profiles share it.
+- `GetRaidableModes()` returns each name once, sorted by level.
+- The free edition's `GetAllDifficulties()` returns `("Normal", 512)`.
+
+**Spawning through the plugin's own call.** `SpawnRandomBase(string b, Vector3 a, int m, int t, bool free)` is
+still there. It is private and not a `[HookMethod]`, but **`Call` reaches it on both Oxide and Carbon**:
+
+- `m` is the difficulty's **level** (from the list above); `t` is the `RaidableType` value of Manual, bound by
+  name; `b` is a base file name or null; `a` is a position, or zero to let the plugin pick.
+- It answers `true` when the base is queued, or `"API_INVALID_PROFILE"`. It returns before the paste, so the
+  base is learned from the next `Started` (D203).
+- Proven both rigs: level 7 with no position (the plugin picked, and chose Wobbly's base); `raidhard2` at
+  level 2 at a given x and z, which landed 1.6 m from the spot.
+- **Given a position, it runs no area check**: the queue pastes straight at the spot. There is no height
+  argument and no despawn of one base, and every base's `id` is still `"0"`.
+
+**The hooks.** The six 17-argument lifecycle hooks and the 14-argument Entered/Exited keep their shapes, and
+`level` carries the profile's `Difficulty Level`. Seen live on both rigs: `Started`, `Despawn`, `Ended`,
+`Despawned`, both `Completed` shapes. Read from the source:
+
+- `OnRaidableBaseLocked` (9 arguments: buyer id, position, grid, level, PvP, load time, base name, spawn,
+  despawn) and `OnRaidableBasePurchased` (8 arguments, the same without the load time) come only from
+  `TrySetPayLock`. That runs when a player buys a base, or when an admin runs
+  `rbevent setowner <player> [lockout]`. `OnRaidableBaseUnlocked` (8 arguments) is its undoing.
+- **Locking to the first attacker raises no hook**, and neither does a **lockout** (the per-player cooldown
+  after a raid, kept in the plugin's own data). So D202's "the feed carries lockouts" still has nothing to
+  listen to (Q36).
+- **Trap: an unload fires `Completed` for every live base.** A `c.reload` / `oxide.reload RaidableBases`
+  with bases up raised both `Completed` shapes for each of them, owner 0 and no raiders, then `Despawn` and
+  `Ended`. It was seen on both rigs. `rbevent despawnall` and a base's own `Despawn()` do not do it. The free
+  edition has the same code path. **The bridge does not count or announce a `Completed` with no owner and no
+  raiders**, so a reload never credits *Warlord* or puts "completed" lines in the feed.
+
+**The helper's internals (§11.4.4), rerun on both rigs.** Everything the helper reached on free 3.2.0 is
+there by the same name. The plugin's `GetBuilding` now takes the difficulty's name (between the type and the
+base name), and finds no profile without it, so the helper passes the name it read.
+
+| Test | Oxide | Carbon |
+| --- | --- | --- |
+| Postfix on `OpenEvent` tags the base: the spot route by its own request object, the plugin's call by base name | ✓ | ✓ |
+| One base's `Despawn()` removes that base only, with the usual `Despawn` / `Ended` / `Despawned` | ✓ | ✓ |
+| Overrides on a deep copy: NPCs off, NPC count, despawn minutes (inactive and total) | ✓ | ✓ |
+| PvP off: **only when also set on the base after `OpenEvent`** (below) | ✓ | ✓ |
+| `BypassUseOwners()` prefix answers from the tag; untagged bases follow the config | ✓ | ✓ |
+| Height +5: blocks from 5.9 on ground 0.0 (Oxide), 7.5 on ground 1.6 (Carbon); a plain base starts at about 1 | ✓ | ✓ |
+| Height = 30: blocks from 31.0; the shared profile's height settings stay untouched | ✓ | ✓ |
+| A RaidableBases reload drops the patches; the helper re-patches in `OnPluginLoaded` | ✓ | ✓ |
+
+**PvP has to be set on the base.** The plugin applies its config's per-type switches ("Convert PVE To PVP",
+"Convert PVP To PVE") inside `OpenEvent`, after reading the profile. A PvP setting in the profile copy loses to
+them, and the tier-3 pack's config turns "Convert PVE To PVP" on for Manual bases. So the helper sets PvP on
+the base in its `OpenEvent` postfix, as it does for a base the plugin's call spawned.
+
+**The area check.** It still binds by parameter count, now 10. **Its refusal reason is readable**: the plugin
+puts it in its own message queue, which the helper can read and send with the refusal. The reasons seen were
+*"Rock is too large"*, *"Cliff formation is too large"*, *"Already occupied by a raidable base"* and *"Blocked by
+a deployable"*. **It is strict on this map:** at the 50 m radius the plugin's own `rbe` uses, 4 of 40 points from
+the plugin's own spawn grid passed, all on beaches, and most refusals were rocks (Q34). The plugin's `rbe`
+skips the check for an admin. **It still passes the seabed**: a spot 50 m under water passed. The helper's own
+water test caught it, comparing the ocean level (`WaterSystem.OceanLevel`) with the terrain. The water map
+read −500 everywhere on this map, so it cannot be used for this.
+
+**The seabed** is a profile's *"Chance For Underwater Bases To Spawn (0-100)"*, which the plugin marks as
+beta. The pack's five profiles leave it at 0, and the grid found no seabed points (Q35).
+
+**The grid is a ten-minute wait on this map.** After a **plugin load**, not only a boot, the grid took
+**666 s on Oxide and 507 s on Carbon** (3,265 and 3,270 points on the 6000 map). The free edition took 52 s on
+the rigs' old 3000 map. Until it finishes, the plugin refuses every spawn and also **refuses
+`rb.reloadprofiles`** ("The grid is loading"). So the step's wait (§11.4.4), and the profile editor's watched
+reload (D205), both have to allow for minutes and say what they are waiting for. Once the grid is built, a
+`rb.reloadprofiles` does not rebuild it.
+
+**The pack's config spawns bases by itself.** "Maintained Events" keeps five bases up whenever a player is
+online. That is the operator's choice. But an event's base shares the server with them, which is one more
+reason the helper tags the run's base rather than matching by name.
+
+**The ranked ladder** adds `Points` and `TotalPoints`, and counts per difficulty only for the five built-in
+names. Nothing reads it: *Warlord* counts from the bridge's own `Completed` (with the rule above).
+
+##### Routes per part (D348)
+
+| Part | Free 3.2.2 | Paid 3.2.2 | Needs the helper? |
+| --- | --- | --- | --- |
+| Edition and version at hello | `IsPremium()`, plugin version | the same | no |
+| Difficulty list for the step | `GetAllDifficulties()`: `Normal` | `GetAllDifficulties()` names and levels (D386) | no |
+| Profile and base lists | the plugin's profiles, read at hello | the same | no |
+| Live map, feed, *Warlord* | the lifecycle hooks | the same | no |
+| Spawn, the plugin picks the spot | `rbevent [base]` (no difficulty, no answer) | `SpawnRandomBase(base, zero, level, Manual)` by `Call` | no |
+| Spawn at a spot | helper route (§11.4.4) | `SpawnRandomBase` with a position (no height, no check), or the helper route | free: yes; paid: Q33 |
+| Height at the spot | helper route | helper route | yes |
+| Per-event overrides | helper, PvP set on the base | the same | yes |
+| Lock to first attacker per event (D206) | helper's `BypassUseOwners()` prefix | the same | yes |
+| Despawn only the run's base (D204) | helper | the same | yes |
+| Area check and its reason (D208) | helper | the same | yes |
+| Purchases and admin locks in the feed | no hooks | `OnRaidableBasePurchased` / `Locked` / `Unlocked` | no (Q36) |
+| Lockouts in the feed | none | none | no route (Q36) |
+
+##### Questions (Q33–Q36)
+
+**All four were answered the same day with the proposed option (a): D387–D390** (§10). The build may start.
+
+- **Q33: on the paid edition with the helper installed, which route spawns at a spot?** For example, an
+  admin's Saturday event places a Hard base at x 650, z 2037, 5 m up, with no NPCs.
+  - (a) **The helper's route on both editions** whenever the helper is installed, and the plugin's call
+    only without it. One path is built and tested for both editions, and the height, overrides and area check
+    need the helper anyway. **Proposed.**
+  - (b) The plugin's call on the paid edition whenever it exists, with the helper adding only the tag and the
+    overrides. The height would then be refused on the paid edition, or done another way.
+- **Q34: how strict is the area check?** For example, an admin picks a flat beach, and a boulder 40 m away
+  makes the plugin answer *"Rock is too large"*.
+  - (a) **Refuse for buildings, deployables, raid bases, players and water. Show rocks and cliffs as a
+    warning in the editor and the run log, and spawn anyway.** **Proposed.**
+  - (b) Refuse on every reason the plugin gives, which is D208 as written.
+  - (c) Make it all advice: never refuse, always log.
+- **Q35: what does the water test do for a profile built for the seabed?** For example, an operator sets
+  *Nightmare Bases*' seabed chance to 50 and wants an event's base under the sea.
+  - (a) **Refuse "in water" unless the chosen profile's seabed chance is above 0, or it allows bases to
+    float above water.** **Proposed.**
+  - (b) Always refuse water, as D208 says.
+- **Q36: lockouts have no hook in either edition. What does the feed carry instead?**
+  - (a) **Drop lockouts. On the paid edition, add a line when a player buys a base, and when an admin locks
+    one to a player** (`OnRaidableBasePurchased` / `Locked`), with the presence audience rule of D376 for the
+    name. **Proposed.**
+  - (b) Drop them, with no new lines.
+  - (c) Read lockouts out of the plugin's data by reflection. Not proposed: it would be a third patch target
+    the plugin can move at any update.
 
 #### 11.4.3 Decided (2026-09-28)
 
@@ -1696,6 +1870,8 @@ The org lead answered the spike's three questions the same day:
   profiles.**
   - **Profile and difficulty.** The step picks a RaidableBases profile, and a difficulty from the installed
     plugin's `GetAllDifficulties()`. The free edition offers "Normal"; the paid edition offers its five.
+    *D386 amends this: the paid edition's difficulties are the operator's own, so the step offers whatever
+    the installed copy lists (§11.4.2).*
   - **Per-event overrides.** The step may override a bounded set of a profile's settings for this spawn
     only. The first set is PvP on/off, despawn minutes, NPCs on/off and count, and the lock-to-first-attacker
     rule; the build's spike settles which of them the plugin lets a helper change after `Started`. The free