# bnstoolkit M0 — discussion points for testing session

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

## ⚠ Server status: needs a manual Start

The first deploy (`0.1.0`) crashed the dedicated server during mod
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
([http://glados:8080](http://glados:8080)) when you wake up.** The new
boot should load `bnstoolkit-0.1.1` cleanly. Verification:

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