Merge pull request 'docs: rewrite bnstoolkit handoff for feature-complete state' (#73 ) from docs/bnstoolkit-feature-complete into main

docs: rewrite bnstoolkit handoff for feature-complete state
The original handoff doc described an empty M0 scaffold with placeholder screens to "discuss tomorrow". 0.3.1 actually ships the full UI plus villager trade rebalance, so the doc now is a testing guide for the working features rather than a discussion-points list. Includes the architecture diagram for how Java + KubeJS interact, the key bindings table, a step-by-step testing path, and a known-gaps list for future iteration. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-07 02:43:56 +00:00 · 2026-06-07 02:43:42 +00:00
1 changed files with 86 additions and 152 deletions
@@ -1,180 +1,114 @@
-# bnstoolkit M0 — discussion points for testing session
+# bnstoolkit feature-complete — testing notes for 2026-06-07 evening
-> Built 2026-06-07 (early hours UTC). Shipped via pack v0.34.0 then hotfixed via v0.34.1.
+> Shipped: pack v0.35.0 / bnstoolkit 0.3.1.
 > Repo: http://10.16.5.102:3000/minecraft/bnstoolkit
-> Jar: `bnstoolkit-0.1.1.jar` (15.6 KB)
+> Server status: ✅ live + verified at 02:41 UTC.
-## ⚠ Server status: needs a manual Start
+## What's in the build
-The first deploy (`0.1.0`) crashed the dedicated server during mod
+### 5 screens (FTB Library widgets — matches FTB Quests look)
 construction — see "Bug caught + fixed" below. The fixed jar (`0.1.1`)
 is already staged in `/srv/fast/brass-sigil-server/server/mods/`, but
 the JVM exited cleanly so systemd didn't auto-restart and I deliberately
 didn't try to brute-force the admin panel credentials.
-**To bring the server back: click Start in the web admin panel
+All opened via key bindings. Rebindable in vanilla controls menu under
-([http://glados:8080](http://glados:8080)) when you wake up.** The new
+"Brass and Sigil" category.
 boot should load `bnstoolkit-0.1.1` cleanly. Verification:
-```
+| Key | Screen | What it does |
 sudo journalctl -u brass-sigil-server.service --since "2 minutes ago" \
  | grep -E "bnstoolkit|Done \([0-9]+|ModLoadingException"
 ```
 Look for `[bnstoolkit] common setup complete` AND no `ModLoadingException`.
 ## Bug caught + fixed (0.1.0 → 0.1.1)
 ```
 IllegalArgumentException: class uk.sijbers.bnstoolkit.BnsToolkit
 has no @SubscribeEvent methods, but register was called anyway.
 ```
 I called `NeoForge.EVENT_BUS.register(this)` in the @Mod constructor
 without yet having any `@SubscribeEvent` methods on the class. NeoForge
 21.1 treats that as fatal at construct-mods time. Removed the call;
 will come back together with the first real event handler in M1.
 **Why local `./gradlew build` didn't catch it:** the build step only
 compiles + jars. The construct-mods phase only runs when a real
 NeoForge instance loads the mod. Action item for M1: add a
 `gameTestServer` Gradle run config that boots the dedicated server
 profile in CI-style so this class of bug fails locally next time.
 ## What this is
 The skeleton of the custom companion mod. It loads cleanly on the client
 and the dedicated server, registers nothing visible yet, and exposes the
 package layout we'll fill in over M1–M4. The point of this milestone is:
 1. Tooling proven end-to-end (Java 21, ModDevGradle, NeoForge 21.1.228, jar in pack)
 2. Mod-id, package, and resource paths locked so future commits only ADD code
 3. One C2S/S2C packet pair wired to prove the network plumbing
 4. Placeholder screens in place so wiring keybinds to real UI is M1's first task
 ## Open decisions — please walk through these tomorrow
 Each is marked with `TODO(matt …)` in the source.
 ### 1. Key bindings (BnsKeyBindings.java)
 Defaults I picked, all unbinding is in the vanilla controls menu:
 | Binding | Key | Opens |
 |---|---|---|
-| Tier ladder | T | `TierUpgradeScreen` |
+| **K** | Civic Tier ladder | 13 rows, current tier highlighted. Right pane shows next tier's cost + perks + Upgrade button. Disabled if you can't afford it or are at Sovereign. |
-| Bounty board | B | `BountyBoardScreen` |
+| **J** | Bounty Board | Today's 5-bounty pool + any active set. Detail pane: target, count, reward, progress. Accept / Cancel / Turn In buttons by state. |
-| Plot map | P | `PlotPurchaseScreen` |
+| **N** | Plot Office | Plot list with ownership state-coding (yours / taken / free). Detail pane: size, chunks, price. Buy / Release buttons. |
 | **H** | Bazaar shop | 9-cell sell item grid. Click an item, see DR-aware effective price for current tier. Sell 1 / 16 / 64 quick buttons. |
 | **M** | Quest Log | At-a-glance status: tier + balance + active bounties (with progress bars) + owned plots. |
-**Question**: any conflicts with mods you already use? `T` is vanilla's
+### HUD overlay
 chat-open IIRC — I should probably move it. Pick a free combo when you
 playtest, I'll bump the defaults.
-### 2. Screen open triggers — keybind only, or block + keybind?
+Top-left of the screen, always visible: `<tier-colour><tier-name>` on
 one line, `<balance> spurs` on the second. Refreshes 1Hz from server
 push — picks up coin pickups immediately, no inventory polling.
-Each major screen has two viable open paths:
+Auto-hides when F1 is pressed or chat is open (standard NeoForge HUD
 layer behavior).
- **Keybind** (already drafted): bnstoolkit binds T/B/P
+### Villager trade rebalance
 - **In-world block**: e.g. a "Bounty Board" block placed at the spawn
  guild building. Right-click opens the screen. More immersive, ties the
  feature to a physical location.
-Both can coexist easily — they're not exclusive. I'd default to "both for
+Every emerald cost or result in vanilla + modded villager trades is
-TierUpgrade + Plots, keybind-only for QuestLog, block-only for ShopBrowser
+now Numismatics:
-and BountyBoard". But that's a 30-second call you make tomorrow.
+- 1..7 emeralds → spurs
 - 8..63 → bevels (1 bevel = 8 spurs)
 - 64+ → cogs (1 cog = 64 spurs)
-### 3. FTB Library UI swap timing
+Works automatically on:
 - All 14 vanilla villager professions
 - Wandering trader (generic + rare)
 - Any modded villager professions (we wrap the event's list, no enum
  of professions needed)
-Right now the placeholder screens extend vanilla `Screen`. The
+This was the "blocked on API" item. Built it into bnstoolkit instead
-architecture doc commits to `dev.ftb.mods.ftblibrary.ui.BaseScreen` for
+of pulling a third-party mod, because the cleanest Modrinth option
-visual consistency with FTB Quests / Chunks. The swap is one line per
+needed NeoForge 21.1.230+ and we're on 228.
 screen — happens in M1 alongside the first real screen layout.
-Reason it's deferred: the FTB maven coords need to be wired into
+## Testing path
 `build.gradle`, and I don't want to pin the wrong artifact name. Will
 verify against the pack's installed FTB Library version (2101.1.31) before
 the M1 build.
 ### 4. HUD overlay layout
 The architecture doc shows a small panel "tier-icon | tier-name | spurs"
 at top-left. Drop me a sketch when you have time and I'll lay it out for
 M4. Current placeholder draws nothing — won't appear in game at all yet.
 ### 5. Network smoke-test packet
 `RequestTierStatePacket` / `TierStateUpdatePacket` are the only wire
 pair I shipped. They prove the codec + handler pattern. M1 fills in the
 server-side handler that reads `player.persistentData.bnsTier` (the
 KubeJS-owned NBT) and replies. **No client code yet sends the request** —
 the round trip is dormant in M0.
 ### 6. Mod settings screen
 Not addressed. Will be a small screen in M4 with toggles for the HUD,
 keybind reminders, and (eventually) a colour-blind mode for tier ranks.
 Low priority unless you've got a specific UX concern.
 ---
 ## Files added/changed (PR for v0.34.0)
 ```
-pack/overrides/mods/bnstoolkit-0.1.0.jar           NEW (15.6 KB)
+/bns me                            # confirm Peasant tier 1
-pack/pack.lock.json                                version 0.33.0 -> 0.34.0
+/give @s numismatics:spur 500      # give spurs for upgrades
-docs/bnstoolkit-discussion-points-2026-06-07.md    NEW (this file)
+K                                  # open tier ladder
 # click Upgrade — should pay 200 and bump you to Farmer
 /bns admin tier set <you> 5        # jump to Knight for plot testing
 K                                  # confirm new tier visible
 H                                  # open bazaar
 # click diamond, click Sell 1 (you'll need a diamond in inventory)
 J                                  # open bounty board, accept one
 # kill the target mobs — progress shows in chat AND the screen
 # turn in via the J screen
 N                                  # open plot office, buy p001
 M                                  # quest log shows everything
 # Test villager trades:
 /summon villager ~ ~ ~
 # Right-click the villager once it picks a profession (place a workstation)
 # Trades should show spurs/bevels/cogs instead of emeralds
 ```
-The bnstoolkit source itself lives at `http://10.16.5.102:3000/minecraft/bnstoolkit`
+## Architecture
 — one initial commit on `main` with the full M0 scaffold. Build:
 ```
-cd /home/matt/dev/bnstoolkit
+KubeJS server_scripts/economy/    ← single source of truth for state + logic
-./gradlew build
+                ↑
                │ (chat commands via server.getCommands)
                │
 ServerEconomyBridge.java          ← reads NBT, sums Numismatics coins,
                                    routes write verbs through /bns
                ↑↓
       4 snapshot + 2 command packets
                ↑↓
 ClientBnsState.java               ← single static state holder
                ↑
        Screens read this each frame
 ```
-## What you'll see in-game when you log in
+Source of truth stays in KubeJS. Java is just the UI layer and a thin
 write-path proxy. If you want to rebalance prices or add bounties, you
 do it in KubeJS — Java auto-reflects.
-**Nothing yet.** That's the point of M0 — it loads cleanly with zero
+## Known gaps for future iteration
 visible surface. Verification path:
-1. Server log: grep for `[bnstoolkit] mod entry constructed` and
+| Gap | Where to fix |
-   `common setup complete (M0 scaffold — no surface yet)`
+|---|---|
-2. Client log on connect: `registered 3 key bindings under key.category.bnstoolkit`
+| No client toast notifications — feedback comes via KubeJS chat messages | Add a dist-isolated `ClientToastDispatcher` class (0.4.0) |
-3. Controls menu → "Brass and Sigil" category → 3 unbound-looking lines
+| Bazaar grid doesn't tooltip the per-unit price | One `addMouseOverText` per `ItemCell` |
-   (Open Tier Ladder, Open Bounty Board, Open Plot Map) on T/B/P
+| Plot office doesn't show a minimap | Render bluemap PNG snippet as background or use FTB Chunks' map widget |
 | Quest log doesn't show FTB Quests progression | Hook into FTB Quests' API once first chapter ships |
 | Numismatics coins as bunch — no fractional change | Bazaar pays in highest denom that fits; player converts at the Bank |
 | Wanderer rare-trade rebalance is greedy (every rare item costs are converted) | Profession-aware exclusion list if anything weird sneaks through |
-If you bind one of those keys and press it in-game, **nothing happens**.
+## File map
 That's correct — the handlers are M1 work.
-## Milestones — concrete next deliverables
+| File | Purpose |
 |---|---|
 | `pack/overrides/mods/bnstoolkit-0.3.1.jar` | The mod itself (95 KB) |
 | `pack/overrides/kubejs/server_scripts/economy/*.js` | State + business logic (unchanged from v0.33.0) |
 | `pack/overrides/world/serverconfig/ftbranks/ranks.snbt` | 13-tier rank config (unchanged) |
 | `docs/bnstoolkit-architecture.md` | Original architecture spec |
-| Milestone | Scope | Estimated work |
+Source repo: http://10.16.5.102:3000/minecraft/bnstoolkit (main = 14dc69f at time of pack ship).
 |---|---|---|
 | M1 | TierUpgradeScreen + KubeJS bridge (tier/balance) + FTB Library swap | 1 evening |
 | M2 | QuestLogScreen + ShopBrowserScreen | 1 evening |
 | M3 | BountyBoardScreen + PlotPurchaseScreen | 1 evening |
 | M4 | SpurHud, mod settings screen, polish | 1 evening |
 Each milestone ends with a deployable jar + a screen you can poke in
 game. None of them require server downtime — drop the new jar in
 `pack/overrides/mods/`, the wrapper sync handles the rest.
 ## Quick recovery
 If the mod misbehaves and bricks the world:
 ```
 # 1. Stop the server
 sudo systemctl stop brass-sigil-server.service
 # 2. Pull the jar out of the live mods dir
 sudo rm /srv/fast/brass-sigil-server/server/mods/bnstoolkit-0.1.0.jar
 # 3. Restart
 sudo systemctl start brass-sigil-server.service
 ```
 That leaves `pack/overrides/mods/bnstoolkit-0.1.0.jar` in the pack repo
 so the next sync would put it back — to fully revert, also `git revert`
 the v0.34.0 commit on the pack.