brass-and-sigil/docs/spawn-building-setup.md

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 <screen> to confirm the command actually fired

What if I just want to test as op (no NPC)

You can always run /bns open <screen> 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.