modules/rust/PLAN_REDESIGNS.md

@@ -1,6 +1,7 @@
 # `module-rust` — the redesigns, planned
 
 **Status:** plan, written 2026-09-27. **Its eleven questions were answered the same day: D188–D198 (§10).**
+On 2026-09-28 the org lead added the first-class optional plugins (§11, D199–D202).
 It is step 3 of [`PLAN_FIXES.md`](PLAN_FIXES.md) §6: the six changes the org lead decided during the first
 player walk, each "planned in detail before code". The org lead asked for all six in one plan (2026-09-27), so
 they can be read together. No code has been written for any of them yet.
@@ -16,6 +17,7 @@ document is later and wins. Its decisions continue PLAN_FIXES' numbering at **D1
 | 4 | The live map's marker types | §4.5, D165 | Module-Rust |
 | 5 | Chat titles: twenty-three conditions | §4.6, D172–D175 | Rust-Plugins, Module-Rust |
 | 6 | NPCs | §4.7 | Rust-Plugins, Module-Rust |
+| 11 | First-class optional plugins: Economics, Backpacks, RaidableBases (Kits stays required) | — (added 2026-09-28) | Rust-Plugins, Module-Rust, installer, Android-app |
 
 **Protocol.** Every wire change here joins **protocol 13**, which is still unreleased on `edge` in all three
 repos. [`PLAN_FIXES.md`](PLAN_FIXES.md) §5 already lists the inventory verb, ZoneManager's flags, zone
@@ -549,6 +551,8 @@ Each item is built on `edge`, walked on both rigs, and PR'd with its spec, like
 5. **NPCs** (§6): the two-route spike, then the org lead's pick, then the build.
 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.
 
 Then PLAN_FIXES §8's re-walk on Oxide and Carbon, and the cutover.
 
@@ -569,3 +573,87 @@ The plan asked eleven questions. The org lead answered them on 2026-09-27, the d
 | **D196** | **The site filters map markers by label**, with a default-off list of minor labels; every other label shows. | The plugin sending Rust's `MonumentType`. | 4 |
 | **D197** | **The NPC spike tries both routes**, extending `rust.npc.place` and HumanNPC, and reports HumanNPC's gotchas before the org lead picks. | Deciding the route before the spike. | 6 |
 | **D198** | **The first inventory on an existing install adopts everything present**, including hand edits waiting for an answer today (D160 as written). | Leaving existing drift rows on the "needs a person" list. | 1.5 |
+
+The org lead added §11 on 2026-09-28 and answered its questions the same day:
+
+| # | Decision | Rejected | § |
+|---|---|---|---|
+| **D199** | **RaidableBases, Economics and Backpacks become first-class optional plugins, and Kits stays required.** Optional means what it means for PopupNotifications and Clans: the bridge detects each at hello, the steps that need one refuse with a reason when it is absent, and the installer does not require it. | Making Kits optional as well. | 11 |
+| **D200** | **Economics: all four uses.** Coins as an event reward (withdrawn on revert); balances shown to the player (site and app) and to staff; staff deposit, withdraw and set a balance, with an activity row; and a *richest* leaderboard column and chat-title condition. | — | 11.2 |
+| **D201** | **Backpacks: staff view any player's backpack, a player views their own (site and app), and an event can grant extra capacity for a time**, taken back at the end. | Showing backpack sizes as named tiers on the permission screen. | 11.3 |
+| **D202** | **RaidableBases: all four uses, and the paid edition too.** Active bases on the live map and in the feed; an event step that spawns a base at a difficulty and despawns it at the end; bases raided per player on the leaderboard and as a title condition; and the paid edition's extras (five difficulties, lockouts) where it is installed, falling back to what both editions share. | Supporting only what the free edition has. | 11.4 |
+
+## 11. First-class optional plugins (D199–D202)
+
+The org lead named four plugins the module supports as first-class integrations. Kits already is one. The other
+three are new, and none of them is mentioned anywhere in PLAN.md or PLAN_FIXES.md. They are **optional** (D199):
+the pattern PopupNotifications set (D141) and Clans set (D47) before them.
+
+- **Detected at hello.** `integrations` gains `economics`, `backpacks` and `raidableBases`, each as
+  `{ loaded, version }`, and RaidableBases also reports which **edition** it is.
+- **A step or screen that needs one refuses with a reason** when it is absent ("Economics is not installed on
+  this server"). It never disappears and never fails silently, as R3 settled for Kits.
+- **Not required by the installer or the egg.** `overlay.toml`'s `requires_plugins` keeps Kits and ZoneManager
+  only.
+- **Public API only (R2).** Where a plugin lacks what we need, a D168 helper does the rest.
+
+### 11.1 What was found, and what must be pulled before any build
+
+From the research on 2026-09-28. Every exact signature below is confirmed again from the plugin's current
+`umod.org/plugins/<Name>.cs` at the start of its build, the way Kits' was (PLAN.md, "pulled 2026-09-24").
+Personal GitHub mirrors are not a source: k1lly0u's mirror of Kits is two major versions behind.
+
+| Plugin | Author · version · price | API we would use | Hooks it raises | Risk |
+|---|---|---|---|---|
+| **Economics** | Wulf · 3.9.2 · free | `Balance(id)` → double; `Deposit`, `Withdraw`, `SetBalance(id, amount)` → bool; `Transfer` | `OnEconomicsDeposit`, `OnEconomicsWithdrawl` (sic), `OnEconomicsTransfer`, `OnEconomicsBalanceUpdated`, `OnEconomicsDataWiped` | Last released about two years ago; fine as optional, never load-bearing |
+| **Backpacks** | WhiteThunder · 3.17.7 · free | `API_ReadBackpackContentsAsJson(ownerId)`; the capacity family (`API_GetBackpackCapacity`, `API_AddBackpackCapacity`, `API_SetBackpackCapacity`) | `OnBackpackOpened`, `OnBackpackClosed`, `OnBackpackDropped`, `CanOpenBackpack` | Newer builds add `EncryptedValue<ulong>` overloads; one community report of backpack data lost across a **Carbon** restart — a rig test before shipping |
+| **RaidableBases** | nivex · free 3.2.0 on uMod, paid on Codefling | `EventTerritory(Vector3)`, `SpawnRandomBase(type)`; listing and despawn not yet confirmed | `OnRaidableBaseStarted` (two overloads), `OnRaidableBaseEnded`, `OnRaidableBasePrivilegeDestroyed`, `OnRaidableBaseDespawn` — signatures not yet confirmed from source | Two products with different features and release lines; data path differs by framework; needs a PvE-damage plugin (TruePVE) for players to raid |
+
+### 11.2 Economics (D200)
+
+- **Coins as a reward.** A step `rust.coins.pay` gives each recipient N coins (the same recipient modes as
+  `rust.kit.entitle`, plus §2.5's `linked`). It is ledgered per recipient like D103's kit credits, and
+  **revert withdraws what the step paid**. A withdrawal the player cannot cover, because they have spent it,
+  takes what is there and says so in the run log. It never goes negative.
+- **Balances.** A new read verb, `economics.balances {steamIds[]}` (bounded like `kits.uses`), and the
+  `OnEconomicsBalanceUpdated` hook folded into the tally (rule 2: aggregates only), so the site keeps each
+  player's last balance per server. The player's account page and the app show it; staff see anyone's.
+- **Staff adjust.** Deposit, withdraw and set from the player's admin page, through the plugin's API. Each is
+  an activity row with the amount before and after.
+- **Richest.** A leaderboard column (the last known balance) and a title condition, *Magnate* by default,
+  admin-renamable like every other category (D175). It is a *best* column in §5.5's sense, the current value
+  rather than a sum.
+
+### 11.3 Backpacks (D201)
+
+- **Read, never write (R2).** A new verb, `backpacks.read {steamId}`, returns
+  `API_ReadBackpackContentsAsJson` reduced to shortname, amount, skin and slot. It never uses the write
+  counterpart, so the site cannot change a backpack.
+- **Staff** open any player's backpack from the player's admin page. **A player** sees their own on the
+  account page and in the app, only for accounts they have linked (the player tier's usual scoping).
+- **Extra space as a reward.** A step `rust.backpack.capacity` adds N slots for the event's duration through
+  `API_AddBackpackCapacity`, and takes them back at teardown, ledgered like a lease. If the player is offline
+  at either end, it waits for their next connection: the capacity calls take a `BasePlayer`.
+- **The spike first:** the Carbon restart report. Fill a backpack on `rust-carbon`, restart, and check it.
+
+### 11.4 RaidableBases (D202)
+
+- **Live map and feed.** `OnRaidableBaseStarted` / `Ended` / `Despawn` / `PrivilegeDestroyed` become events
+  (`raid.started`, `raid.ended`, …) carrying the base's position, difficulty and owner. The map draws active
+  bases as a layer with its own audience switch (D114), and the feed says who raided what.
+- **An event step, `rust.raidbase.spawn`**, spawns a base at a difficulty near a monument or position, owned
+  by the run. The run's teardown despawns it, and D170's expiry pattern marks it `expired` if the plugin ends
+  it first.
+- **Stats and titles.** Bases completed per player per wipe (the player credited with the tool cupboard, as
+  the plugin credits it), a leaderboard column, and a title condition, *Warlord* by default.
+- **The paid edition (D202).** Hello reports the edition. Where it is the paid one, the spawn step offers its
+  five difficulties and the feed carries lockouts. On the free edition the step offers the one difficulty it
+  has. **Testing the paid edition needs a licence for the rigs**, which is the org lead's to buy or supply.
+- **The spike first:** pull the free source, confirm every hook and API signature above, and find the listing
+  and despawn calls. Then load it on both rigs, with TruePVE, and raid one base.
+
+### 11.5 Protocol
+
+These are new verbs, events and hello fields. If they are built before the cutover they join the unreleased
+protocol 13 like everything else here; if the cutover comes first, they open protocol 14. Which one is decided
+when §9 reaches item 7.