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.