diff --git a/docs/spawn-building-setup.md b/docs/spawn-building-setup.md new file mode 100644 index 0000000..52c666f --- /dev/null +++ b/docs/spawn-building-setup.md @@ -0,0 +1,143 @@ +# Spawn building setup — wiring NPCs to bnstoolkit screens + +How to give players access to the Counting House / Bounty Board / Plot +Office / Civic Registrar via Easy NPC dialogue at spawn. + +## Prerequisites (one-time, post-wipe) + +``` +/setworldspawn ~ ~ ~ # set the canonical world spawn +/bns admin spawn-init # creates Spawn (cyan) + Plots (gold) + # FTB Teams and claims existing plots +``` + +If you also want spawn protection: switch to the Spawn team and claim +your spawn town chunks via the FTB Chunks map (M key, left-click). + +## The five screens you can expose + +| Screen | Open command | What it does | +|---|---|---| +| Hub | `/bns open hub` | Status overview (tier, balance, bounties, plots) | +| Counting House | `/bns open counthouse` | Wealth exchange — sell diamonds/netherite/ancient debris for spurs | +| Bounty Board | `/bns open bounty` | Today's 5 bounties + accept/cancel/turn-in | +| Plot Office | `/bns open plot` | Buy / release plots | +| Civic Tier | `/bns open tier` | Pay spurs to upgrade tier | +| Adventurer's Journal | `/bns open journal` | Status overview + active bounties + exchange rates | + +`hub` and `journal` are status-only (read). The other four are +transactional — they should be gated behind an NPC at the relevant +spawn building. + +## Per-building setup (Counting House example) + +Repeat for each of the 4 transactional buildings, varying just the +screen name and NPC name. + +### 1. Spawn the NPC + +In creative mode, get an Easy NPC spawn egg: +``` +/give @s easy_npc:custom_egg +``` + +Right-click the ground where you want the NPC. It spawns a customisable +NPC. + +### 2. Configure appearance + name + +Right-click the NPC → **Configuration** (or use the wrench). +- **Skin**: pick a fitting villager / human skin +- **Name**: "Counting House Clerk" (or whatever fits the building) +- **Profession**: optional — purely cosmetic + +### 3. Configure dialog + +In the NPC config → **Dialog** tab. + +Create a new STANDARD dialog. Suggested text: +> Welcome to the Counting House. We exchange diamonds, netherite, and +> ancient debris for spurs deposited directly to your bank account. +> Care to make a trade? + +Add a **Button** to this dialog: +- **Label**: "Open the exchange" +- **Type**: ACTION +- **Action**: COMMAND +- **Command**: `bns open counthouse` +- **Execute as user**: ✅ (must be enabled) +- **Permission level**: 0 (no special permission needed) +- **Trailing action**: CLOSE_DIALOG (optional — closes the dialog after click) + +Add another button "Goodbye" → CLOSE_DIALOG for the polite exit. + +### 4. Configure trigger + +In the NPC config → **Actions** tab: +- Event: **ON_INTERACTION** +- Action: **OPEN_DEFAULT_DIALOG** + +Now when a player right-clicks the NPC, the dialog opens. Clicking +"Open the exchange" runs `/bns open counthouse` as that player and +the Counting House screen pops up. + +## Building-to-screen mapping + +| Building | NPC name suggestion | Open command | +|---|---|---| +| Counting House | Counting House Clerk | `bns open counthouse` | +| Adventurer's Guild | Bounty Officer | `bns open bounty` | +| Plot Office | Plot Clerk | `bns open plot` | +| Civic Hall / Town Hall | Civic Registrar | `bns open tier` | +| (anywhere — optional) | Quartermaster | `bns open hub` | +| (anywhere — optional) | Cartographer | `bns open journal` | + +## Security gate (one-time, already shipped) + +The Easy NPC config at `/srv/fast/brass-sigil-server/server/config/ +easy_npc/security.cfg` has `executeAsUserCommandAllowList.ALL=bns`, +so dialogue actions can run `/bns ...` on the player's behalf. This +ships with the pack as of v0.36.0 — no manual edit required after +fresh installs. + +## Testing your setup + +1. Build the building +2. Place the NPC +3. Configure the dialog as above +4. Switch to survival, walk up, right-click the NPC +5. Click the action button +6. The screen should open on your client immediately + +If nothing happens: +- Check chat for errors ("Blocked execute-as-user command root ...") +- If you see that, the security.cfg allowlist is missing `bns` — see + the security gate section above +- Otherwise: check the server log for `[bnstoolkit] /bns open ` + to confirm the command actually fired + +## What if I just want to test as op (no NPC) + +You can always run `/bns open ` directly from chat or console +to open a screen for yourself. The op-level requirement is none — the +command works for any player. NPCs are just the in-world surface. + +## Pre-wipe testing checklist (current world) + +Each feature, where you'd manually test it before the wipe: + +| Feature | How to test | +|---|---| +| Hub | Press B → see status panel with tier/cash/bank/total/bounties/plots | +| Counting House | `/bns open counthouse` → 4 items in grid (diamond, diamond_block, netherite_ingot, ancient_debris), inventory count badge bottom-right of each cell, fee + per-unit price in detail pane, Sell 1/16/64 buttons grey out when you don't have enough | +| Sell flow | `/give @s minecraft:diamond 64` → click diamond → Sell 16 → bank balance ticks up, sell button updates | +| Bounty Board | `/bns open bounty` → see today's pool, click a bounty for detail, accept, kill the targets, turn in | +| Plot Office | `/bns open plot` → see 3 default plots, buy p001 (tier 3+ required), check FTB Chunks map M — chunk should turn your team colour | +| Plot unclaim guard | After buying a plot, try to unclaim its chunk via FTB Chunks UI → should reject with redirect message | +| Civic Tier | `/give @s numismatics:spur 500` or `/bns wallet deposit ...` → `/bns open tier` → click Upgrade — pays from cash + bank combined | +| Wallet | `/bns wallet`, `/bns wallet deposit 50`, `/bns wallet withdraw 50` | +| Auto-bound card | Look in inventory — should already have a white_card bound to your account | +| Villager rebalance | Trade with a villager — emerald-side replaced with spurs/bevels/cogs | +| Quest Log auto-open population | Press B → click Journal → should show active bounties, rates, plots | + +If any of these break, ping with the details. Pre-wipe is the time to find these bugs. diff --git a/pack/overrides/mods/bnstoolkit-0.8.0.jar b/pack/overrides/mods/bnstoolkit-0.8.1.jar similarity index 66% rename from pack/overrides/mods/bnstoolkit-0.8.0.jar rename to pack/overrides/mods/bnstoolkit-0.8.1.jar index 1993852..50ae386 100644 Binary files a/pack/overrides/mods/bnstoolkit-0.8.0.jar and b/pack/overrides/mods/bnstoolkit-0.8.1.jar differ diff --git a/pack/pack.lock.json b/pack/pack.lock.json index d719a2a..d48bc65 100644 --- a/pack/pack.lock.json +++ b/pack/pack.lock.json @@ -1,13 +1,13 @@ { "$schema": "Brass-and-Sigil pack.lock.json - generated, do not edit by hand unless you know what you are doing", "name": "Brass and Sigil", - "version": "0.41.0", + "version": "0.41.1", "minecraft": "1.21.1", "loader": { "type": "neoforge", "version": "21.1.228" }, - "lockedAt": "2026-06-08T17:52:03Z", + "lockedAt": "2026-06-08T18:14:17Z", "mods": [ { "source": "modrinth",