docs: bnstoolkit architecture + detailed perk specs #65

2026-06-06T23:09:35Z

Matt commented

2026-06-06 23:09:35 +00:00

New design doc for the custom companion mod, plus expanded perk specifications so every column in the 13-tier ladder is fully designed before any Java is written.

Covers: package layout, six GUI screen specs, three FTB Chunks mixin targets, network packet contract (7 S2C + 5 C2S), data persistence model, config file schemas, KubeJS integration surface, 6-phase mod-implementation plan, and detailed per-perk specs for all 8 V1 perks (wilderness chunks, plot slots, sethomes, daily bounty slots, shop fee discount, chat colour, join broadcast, /back).

Seven future perk dimensions documented as JSON-extensible without code changes.

Nothing implemented yet — this is the source-of-truth design that must be reviewed before scaffolding begins.

New design doc for the custom companion mod, plus expanded perk specifications so every column in the 13-tier ladder is fully designed before any Java is written. Covers: package layout, six GUI screen specs, three FTB Chunks mixin targets, network packet contract (7 S2C + 5 C2S), data persistence model, config file schemas, KubeJS integration surface, 6-phase mod-implementation plan, and detailed per-perk specs for all 8 V1 perks (wilderness chunks, plot slots, sethomes, daily bounty slots, shop fee discount, chat colour, join broadcast, /back). Seven future perk dimensions documented as JSON-extensible without code changes. Nothing implemented yet — this is the source-of-truth design that must be reviewed before scaffolding begins.

Matt added 1 commit 2026-06-06 23:09:35 +00:00

docs: bnstoolkit architecture + detailed perk specifications 25107efcf1

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>

Matt merged commit 367056e2ba into main

2026-06-06 23:09:35 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: minecraft/brass-and-sigil#65