brass-and-sigil/docs/bnstoolkit-discussion-points-2026-06-07.md

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