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

Spawn building setup — wiring NPCs to bnstoolkit screens

How to give players access to the Exchange / 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)
Exchange	/bns open exchange	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 (Exchange 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: "Exchange 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 Exchange. 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 exchange
• 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 exchange as that player and the Exchange screen pops up.

Building-to-screen mapping

Building	NPC name suggestion	Open command
Exchange	Exchange Clerk	bns open exchange
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
Exchange	/bns open exchange → 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.