RunicGateway/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'docs(rust): first-class optional plugins in the redesign plan (D199-D202)' (#292) from docs/rust-optional-plugins into main

Browse Source 
Reviewed-on: #292
This commit is contained in:
Colby Whitlock
2026-09-28 11:37:11 +00:00
parent a9981f59bc 23ce47c6ad
commit 4c996e270f
1 changed files with 88 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
modules/rust/PLAN_REDESIGNS.md
View File

@@ -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.