# bnstoolkit feature-complete — testing notes for 2026-06-07 evening

> Shipped: pack v0.35.0 / bnstoolkit 0.3.1.
> Repo: http://10.16.5.102:3000/minecraft/bnstoolkit
> Server status: ✅ live + verified at 02:41 UTC.

## What's in the build

### 5 screens (FTB Library widgets — matches FTB Quests look)

All opened via key bindings. Rebindable in vanilla controls menu under
"Brass and Sigil" category.

| Key | Screen | What it does |
|---|---|---|
| **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. |
| **J** | Bounty Board | Today's 5-bounty pool + any active set. Detail pane: target, count, reward, progress. Accept / Cancel / Turn In buttons by state. |
| **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. |

### HUD overlay

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.

Auto-hides when F1 is pressed or chat is open (standard NeoForge HUD
layer behavior).

### Villager trade rebalance

Every emerald cost or result in vanilla + modded villager trades is
now Numismatics:
- 1..7 emeralds → spurs
- 8..63 → bevels (1 bevel = 8 spurs)
- 64+ → cogs (1 cog = 64 spurs)

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)

This was the "blocked on API" item. Built it into bnstoolkit instead
of pulling a third-party mod, because the cleanest Modrinth option
needed NeoForge 21.1.230+ and we're on 228.

## Testing path

```
/bns me                            # confirm Peasant tier 1
/give @s numismatics:spur 500      # give spurs for upgrades
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
```

## Architecture

```
KubeJS server_scripts/economy/    ← single source of truth for state + logic
                ↑
                │ (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
```

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.

## Known gaps for future iteration

| Gap | Where to fix |
|---|---|
| No client toast notifications — feedback comes via KubeJS chat messages | Add a dist-isolated `ClientToastDispatcher` class (0.4.0) |
| Bazaar grid doesn't tooltip the per-unit price | One `addMouseOverText` per `ItemCell` |
| 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 |

## File map

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

Source repo: http://10.16.5.102:3000/minecraft/bnstoolkit (main = 14dc69f at time of pack ship).