# bnstoolkit M0 — discussion points for testing session

> Built 2026-06-07 (early hours UTC). Shipped via pack v0.34.0.
> Repo: http://10.16.5.102:3000/minecraft/bnstoolkit
> Jar: `bnstoolkit-0.1.0.jar` (15.6 KB)

## 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` |
| Bounty board | B | `BountyBoardScreen` |
| Plot map | P | `PlotPurchaseScreen` |

**Question**: any conflicts with mods you already use? `T` is vanilla's
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?

Each major screen has two viable open paths:

- **Keybind** (already drafted): bnstoolkit binds T/B/P
- **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
TierUpgrade + Plots, keybind-only for QuestLog, block-only for ShopBrowser
and BountyBoard". But that's a 30-second call you make tomorrow.

### 3. FTB Library UI swap timing

Right now the placeholder screens extend vanilla `Screen`. The
architecture doc commits to `dev.ftb.mods.ftblibrary.ui.BaseScreen` for
visual consistency with FTB Quests / Chunks. The swap is one line per
screen — happens in M1 alongside the first real screen layout.

Reason it's deferred: the FTB maven coords need to be wired into
`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)
pack/pack.lock.json                                version 0.33.0 -> 0.34.0
docs/bnstoolkit-discussion-points-2026-06-07.md    NEW (this file)
```

The bnstoolkit source itself lives at `http://10.16.5.102:3000/minecraft/bnstoolkit`
— one initial commit on `main` with the full M0 scaffold. Build:

```
cd /home/matt/dev/bnstoolkit
./gradlew build
```

## What you'll see in-game when you log in

**Nothing yet.** That's the point of M0 — it loads cleanly with zero
visible surface. Verification path:

1. Server log: grep for `[bnstoolkit] mod entry constructed` and
   `common setup complete (M0 scaffold — no surface yet)`
2. Client log on connect: `registered 3 key bindings under key.category.bnstoolkit`
3. Controls menu → "Brass and Sigil" category → 3 unbound-looking lines
   (Open Tier Ladder, Open Bounty Board, Open Plot Map) on T/B/P

If you bind one of those keys and press it in-game, **nothing happens**.
That's correct — the handlers are M1 work.

## Milestones — concrete next deliverables

| Milestone | Scope | Estimated work |
|---|---|---|
| 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.