New companion-mod design doc covering:
Architecture
- Purpose & scope (what's in the mod vs what stays in KubeJS)
- High-level diagram showing client/server/KubeJS/FTB-stack roles
- Full Java package layout under uk.sijbers.bnstoolkit
- Six GUI screens specified individually with layouts + network calls
(Quest Log, Bounty Board, Tier Upgrade, Plot Purchase, Shop Browser,
Quest Progress HUD)
- Three mixin targets into FTB Chunks' ChunkScreenPanel (drawBackground,
ChunkButton.addMouseOverText, ChunkButton.onClicked) -- no FTB fork
- Network packet contract (7 S2C + 5 C2S packets, versioned)
- Data persistence model (SavedData for plots + sethomes, in-memory
for death locations, KubeJS for quest state)
- Two config files documented (tiers.json + plots.json) with example
JSON5 schemas
- KubeJS integration surface (8 /bnstoolkit_internal commands)
- Build & release setup (separate Gitea repo, standard NeoForge
ModDevGradle, semver)
- 6 mod implementation phases (M0-M6), each independently shippable
Detailed perk specifications
- Wilderness chunks: FTB Ranks permission node, native FTB Chunks
enforcement, no mod-side work
- Plot slots: SavedData-backed ownership tracking, 50% refund on
release
- Sethomes: full sethome system built in bnstoolkit (no other sethome
mod exists in pack). Per-tier cap, 30s cooldown, /sethome /home
/delhome /listhomes commands
- Daily bounty slots: enforced in KubeJS engine, UI greys Accept when
at cap
- Shop fee discount: base 25% Bazaar fee reduced by tier discount.
Only applies to NPC Bazaar shop, not player-to-player Numismatics.
Worked example showing -25% Sovereign = 0% fee = full 10 spurs/diamond
- Chat colour: full colour ladder per tier (grey to rainbow at
Sovereign with character-by-character cycling)
- Join broadcast: 6 levels documented (none, simple, fancy, epic,
epic+particles, epic+spectacular) with example ASCII
- /back after death: in-memory storage, 60s cooldown, dimension-aware
- Future perk dimensions: 7 candidates the schema supports without
code changes (particle trails, custom join sounds, custom title
prefix, priority bounty access, tier-gated vendors, daily login
bonus, keep-inventory chance)
Six open implementation questions flagged for resolution during
build, none blocking.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Tier ladder extended from 8 -> 13 tiers, with cleaner historical
progression. Replaces the previous Peasant/Citizen/Patron/Notable/
Baron/Noble/Lord/Sovereign ladder which mixed commoner-economic terms
with noble terms.
New 13-tier ladder (Civic + British peerage):
1 Peasant free
2 Farmer 200
3 Citizen 750
4 Merchant 2,500
5 Knight 6,500 (gentry threshold)
6 Baron 15,000 (lowest noble)
7 Viscount 35,000
8 Earl 75,000
9 Marquess 150,000
10 Duke 300,000
11 Archduke 700,000
12 Grand Duke 1,500,000
13 Sovereign 10,000,000 (apex, "finished the game")
Rationale:
- Yeoman -> Farmer, Burgher -> Merchant: both replaced with
recognizable terms while keeping the period feel.
- Earl kept as the British equivalent of Count (Viscount sits below
Earl correctly because Viscount = vice-count).
- Top tier extended above Duke with Archduke -> Grand Duke ->
Sovereign. Avoids singular-feeling Emperor/King/Prince titles.
- Sovereign at 10M is intentionally extreme -- months of dedicated
play to reach, properly mythical.
Full perk table updated to spread cleanly across 13 tiers:
- Plot slots: 0/0/1/1/2/2/3/3/4/5/6/7/10
- Sethomes: 1/1/2/3/4/5/6/8/10/12/16/20/unlimited
- Daily bounties: 3/3/3/4/4/5/5/6/6/7/7/8/10
- Shop fee: 0% down to -25% at Sovereign
- Chat colours: grey -> white -> yellow -> green -> cyan -> blue
-> purple -> gold -> orange -> red -> bright red -> rainbow
Knight (tier 5) is the gentry threshold -- the first meaningful
"I'm somebody" upgrade with colored chat, join broadcast, and /back.
Founder cosmetic flag added for matt (server owner). Permanent chat
prefix [Founder] alongside the normal rank. No gameplay perks; just
identification. Founder still grinds the regular ladder.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Architectural revisions:
- UI approach: custom companion mod (working name 'bnstoolkit') built
on FTB Library's UI framework. Polished GUI screens for Quest Log,
Bounty Board, Tier upgrade, Shop browser, Plot purchase. Quest
progress as a custom HUD render layer (no stacked vanilla bossbars).
All player interaction through GUI + NPC dialogue, no chat commands
to memorise. FTB Library UI chosen for visual consistency with the
rest of the FTB stack already in the pack.
- Tier ladder locked: 8 tiers, Civic theme, starting at Peasant.
Peasant -> Citizen -> Patron -> Notable -> Baron -> Noble -> Lord
-> Sovereign. Replaced Burgess with Baron; reordered ascending.
- Tier perks: full table with chunks claimable, spawn plot slots,
sethome count, daily bounty slots, shop fee, chat colour, join
broadcast tier, /back access. JSON-configured at
config/bnstoolkit/tiers.json, hot-reloadable. Easy to tune any
column without code changes.
- Spawn plots clarified as distinct from wilderness chunk claims:
predefined regions at spawn, purchased individually for spurs,
primary use is shops, slot-limited by tier. Purchase happens
inside the FTB Chunks map UI via custom mod mixin. Plot data
lives in the custom mod, not in FTB Chunks.
- Wilderness chunk claims: tier-allocated, free within allowance,
refused above. NO per-chunk pricing (dropped from v0.2). Powered
by FTB Ranks -> FTB Chunks permission nodes.
- Phasing updated to add Phase 0c (mod scaffolding) and reorder
Phases 1-7 to fit the mod-supplied UI work.
- Implementation notes: KubeJS script layout, custom mod package
layout, state data locations, config file locations all
documented.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Final architecture for the economy + quest system. No more V1/V2/V3
iteration cycles. Resolved against actual mod source code and verified
APIs via research spike.
Key decisions locked:
- Bounty UI: custom (bossbar + /quests commands + Easy NPC dialog).
NOT FTB Quests -- it lacks per-player visibility, has no abandon
event, and cooldown is per-team. Confirmed via FTBQ source review.
- Progression UI: FTB Quests (right tool for long-form content where
per-team cooldowns and one-shot rewards are fine).
- Numismatics: direct Java.loadClass access (no events shipped, no
KubeJS bindings). Documented exact API surface and call patterns.
- FTB Chunks claim cost: FTBChunksEvents.before('claim') with
event.setResult() to refuse. Requires adding FTB XMod Compat.
- Tier system: FTB Ranks (CurseForge only) + permission-driven chunk
limits + KubeJS-mediated upgrades via runCommandSilent('ftbranks add').
- Per-player HUD: bossbars, not scoreboards. Vanilla scoreboards are
global; bossbars natively per-player.
- Custom mod for V1: NOT NEEDED. Re-evaluate if blocked.
Mods to add in Phase 0a (one PR before any implementation):
- FTB Quests 2101.1.25
- FTB XMod Compat (latest)
- FTB Ranks 2101.1.3
Phasing updated: Phase 0a (mod additions) blocks the rest. Phase 0b
(spawn build) is non-blocking and user-paced; all systems can be
built and verified before spawn exists.
KubeJS file layout documented for clean implementation:
pack/overrides/kubejs/server_scripts/economy/{01..99}_*.js
11 open decisions resolved. 3 remain non-blocking.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Three-layer visibility plan:
V1 (Phase 3): /quests, /quests info, /quests cancel commands.
Mobile-friendly via the bridge, no extra mods.
V2 (Phase 3.5): Quest Log book item with dynamic pages.
V3 (later): optional sidebar HUD via vanilla scoreboards.
3-slot active-quest cap so cancellation is a real choice:
- Prevents accept-all-then-cancel-easy-ones RNG shopping
- Keeps state files small
- READY frees the slot so turn-in backlogs are workable
State storage schema documented (active + completed/cooldown).
Phase 3.5 added to the roadmap for the book item.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Full design for the unified spawn economy:
- Seven themed guild buildings (Adventurer's, Merchant's, Civic,
Library, Tavern, Foundry, Mint)
- Universal accept → complete → return quest pattern
- Villagers moved fully to spurs with rebalance principles +
initial price guidance
- Money flow architecture (bounded inflows, scaling sinks)
- Phasing plan (8 phases, each independently shippable)
- Mod stack confirmed (we have everything we need for V1)
- Risk register + open decisions to make before implementation
Status: design, not yet implemented. Phase 0 (spawn skeleton)
is the next concrete deliverable.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Matt