Matt
e770cb55cb
Surfaces the server-needs-Start state and the fix details up top so when matt wakes up he doesn't have to scroll past the M1+ planning to find out the box is down. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
181 lines
6.8 KiB
Markdown
181 lines
6.8 KiB
Markdown
# 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.
|