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>
Stop hacking around the problem -- use the standard cross-recipe-
viewer hide convention that both NeoForge and JEI define.
Source-level confirmation:
mezz/JustEnoughItems @ 1.21.1
CommonApi/.../api/constants/Tags.java
HIDDEN_FROM_RECIPE_VIEWERS = c:hidden_from_recipe_viewers
Library/.../ingredients/IngredientVisibility.java
isIngredientVisible() calls
ingredientHelper.isHiddenFromRecipeViewersByTags(typedIngredient)
-> any item carrying this tag is hidden from JEI.
neoforged/NeoForge @ 1.21.x
common/Tags.java
Tags.Items.HIDDEN_FROM_RECIPE_VIEWERS = c:hidden_from_recipe_viewers
-> same tag, NeoForge agrees with JEI.
EMI / REI also respect this tag (common convention).
So the proper modpack-shippable fix is a single datapack file:
pack/overrides/world/datapacks/bns-fuel/data/c/tags/item/
hidden_from_recipe_viewers.json
{
"replace": false,
"values": [
"alexsmobs:shattered_dimensional_carver",
"alexsmobs:transmutation_table"
]
}
No mod, no KubeJS, no CraftTweaker, no Item Obliterator JEI integration
(which doesn't exist for 1.21.1 NeoForge anyway). Just the tag the
recipe-viewer ecosystem agreed on years ago.
Item Obliterator + Necronomicon stay in the pack for what they actually
deliver on 1.21.1: inventory-pickup block + villager-trade removal +
right-click cancellation. The Capsid recipe override stays too as the
creation block.
The full disable stack now:
- Tag (this commit) -> Hidden from JEI / REI / EMI
- Datapack capsid recipe -> Can't be created in-world
- Item Obliterator -> Can't be picked up / right-clicked
if obtained via /give or creative
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
I removed this datapack override in v0.31.0 on the (incorrect)
assumption that Item Obliterator would also handle Alex's Mobs'
custom capsid_recipes recipe type. It doesn't -- Item Obliterator
intercepts vanilla and some common modded recipes, but the Capsid
uses its own SimpleJsonResourceReloadListener bound to the
"capsid_recipes" folder, and that listener still loaded the
default shipped recipe.
The visible bug: a player could put a regular Dimensional Carver
into a Capsid -- the recipe matched, the Dimensional Carver was
consumed, and the Capsid spat out a Shattered Dimensional Carver.
Item Obliterator then refused the pickup. Net result:
- Player loses their hard-earned regular Carver
- Player can never pick up the Shattered one
- World has an unrecoverable floating item entity
Restore the override at:
pack/overrides/world/datapacks/bns-fuel/data/alexsmobs/
capsid_recipes/shattered_dimensional_carver.json
This swaps the recipe's input from `alexsmobs:dimensional_carver` to
`minecraft:barrier`, which is unobtainable in survival. The recipe
loads cleanly but can never match. The Capsid transformation for
the Shattered Carver effectively no longer exists.
Item Obliterator still handles the JEI / creative tab / inventory /
trade removal -- both layers complement each other.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace the v0.30.x ad-hoc disable mechanisms (KubeJS server script,
datapack recipe override, KubeJS client-side JEI hide -- which was
broken on this KubeJS build) with a single proper tool:
- **Item Obliterator 2.3.0** + dep **Necronomicon API 1.6.0**
Declarative JSON config to remove items from inventories,
creative tabs, all recipes (including modded custom recipe
types), villager trades, and JEI. Exactly the missing capability.
Config: pack/overrides/defaultconfigs/item_obliterator.json5
Blacklists:
alexsmobs:transmutation_table
alexsmobs:shattered_dimensional_carver
Removed (no longer needed):
- pack/overrides/kubejs/server_scripts/disable_alexsmobs_features.js
(Item Obliterator handles transmutation_table recipe removal
and right-click cancel automatically)
- pack/overrides/world/datapacks/bns-fuel/data/alexsmobs/
capsid_recipes/shattered_dimensional_carver.json
(Item Obliterator handles modded recipe removal too)
Both items now correctly:
- Don't appear in JEI search / item list
- Don't appear in creative tabs
- Have no working recipe path
- Can't be right-clicked / used
- Get scrubbed from inventories on join
The Void Worm boss + regular Dimensional Carver still work --
nothing else in Alex's Mobs is affected.
Verified live: both mods discovered, Necronomicon read our config
file successfully ("File exists, reading config"), Item Obliterator
loaded with the blacklist.
Note: config schema is v2; v1 configs get overwritten by the mod's
default. Always write configVersion: 2.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-01 19:21:41 +00:00
5 changed files with 457 additions and 34 deletions
\* Only if we keep emeralds; see §5 — we're moving villagers to spurs, which probably retires the Mint as a currency-conversion station and repurposes it as a wallet/info hub.
---
## 3. Spawn — themed guild buildings
Each guild is a destination. The guild's NPC is both the **entry point** (accept work) and **exit point** (return to claim reward). This pattern applies universally — see §4.
- **FTB Quests** = the *progression* backbone — chapter-by-chapter pack content, one-time rewards, story arcs. The campaign.
- **Spawn-building NPCs** (Easy NPC + KubeJS) = the *daily/repeatable* layer — bounties, sell shops, services. The live activities.
Both pay into the same wallet. Players run the campaign at their pace and the daily content for income/replay value. They reinforce each other rather than compete.
---
## 4. Quest & bounty flow (universal pattern)
**Core principle:** for any guild, the player **accepts** work from an NPC, **completes** it in the world, then **returns** to that NPC to **turn it in** and claim the reward. No instant payouts. This:
- Anchors guilds as destinations
- Creates risk/reward tension (die on the return, lose the reward)
- Encourages waypoint use and travel
- Lets the server centrally control payouts and detect cheating
### State machine
Each quest, per player, lives in one of these states:
```
AVAILABLE ─[player accepts]─► ACTIVE ─[objective met]─► READY ─[turned in]─► COMPLETED
- **AVAILABLE** — NPC offers the quest in dialog. Player has no current copy of it.
- **ACTIVE** — Player accepted. KubeJS tracks objective progress via relevant events (`EntityEvents.death` for kills, `ItemEvents.firstRightClicked` for explorations, etc.).
- **READY** — Objective met. Reward is *promised but not yet paid.* NPC dialog now offers a turn-in option.
- **COMPLETED** — Reward paid out. Quest goes on cooldown for this player.
- **AVAILABLE** (again) — after the cooldown, the NPC will offer it again.
Three surfaces, **all shipping together in Phase 3.** Not iterated, not optional.
| Surface | Role | Mechanism |
|---|---|---|
| **Bossbars** | Always-visible HUD — one bossbar per active quest, shows name + N/M progress bar | Vanilla `/bossbar` commands driven by KubeJS. Native per-player display (scoreboards are global; bossbars aren't). Up to 3 stacked at top of screen. |
| **`/quests` commands** | Management — list, inspect, cancel | KubeJS `ServerEvents.commandRegistry`. Works in chat and over the Telegram bridge. Clickable chat components for `[cancel]` and `[details]`. |
| `/quests` | Lists your ACTIVE / READY quests with progress, source guild, reward |
| `/quests info <id>` | Detail view |
| `/quests cancel <id>` | Drops an active quest, frees the slot. Applies the same cooldown as if completed (prevents accept-cancel-accept RNG-shopping). |
### Why NOT FTB Quests for bounties
FTB Quests is the right tool for **progression** (Phase 5+), not for daily bounties. Confirmed via source review:
- **No abandon/cancel event** — players can `Ctrl+Shift+R` to reset quest progress, but nothing fires that KubeJS can hook → can't enforce cancellation cooldown.
- **Cooldown is per-team, not per-player** — in a 4-player team, one member completing puts it on cooldown for all four.
- **No per-player quest visibility** — gating "5 of 20 active today" requires `CustomTask` gates rather than first-class per-player visibility.
For long-form progression questing, all three are non-issues. So: FTB Quests for the campaign, custom KubeJS system for daily bounties.
### Quest slot limit
Players have a **maximum of 3 active quests at a time.** This is the friction that makes cancel meaningful:
- Forces players to pick which quests they actually want — no "accept all 5, see what's easiest, cancel the rest" RNG-shopping.
- Keeps the state files small.
- Makes ready-to-turn-in queues meaningful (you can hold 3 unrewarded quests in your back pocket).
A quest moving to READY frees the slot for accepting a new one even before turn-in.
### KubeJS implementation — locked specifics
- **State storage:** per-player JSON in `world/data/bns_quests/<uuid>.json`. Schema:
- **Event tracking:** KubeJS event handlers (`EntityEvents.death`, `ItemEvents.pickedUp`, `BlockEvents.broken`) read the player's active quests and increment progress + update bossbar value.
- **Bossbar lifecycle:** on quest accept, KubeJS creates a unique per-player bossbar via `server.runCommandSilent('bossbar add <id> <name>')`, assigns it to that player only, updates `value` and `max` on progress. On turn-in or cancel: `bossbar remove`.
- **Numismatics integration (direct Java access — no events shipped, no KubeJS bindings):**
const ok = acct.deduct(100, ReasonHolder.empty()); // returns false if broke
Numismatics.BANK.markBankDirty(); // force persistence
```
- **Dialog branching:** Easy NPC dialog branches on scoreboard objective `bns.quest.<npc_tag>` that KubeJS mirrors quest state into. Dialog `Command` action triggers `/bns_quest accept <id> <npc_tag>` which routes to KubeJS.
- **Commands:** registered via `ServerEvents.commandRegistry` in KubeJS. Scoped to the player who runs them. The custom `/bns_quest` namespace handles NPC-triggered actions; `/quests` is the player-facing tracker.
- **Trash trades get deleted** — no one ever wanted to sell rotten flesh or buy paper.
- **Sell-to-villager trades exist but are bad** — `64 wheat → 1 spur`, `16 leather → 1 spur`. Farms still possible, but ~10× slower than any other income source.
### Price guidance (initial calibration — tune via playtesting)
#### Buy-from-villager (player pays spurs)
| Item | Tier-1 | Tier-3 | Tier-5 |
|---|---|---|---|
| Standard enchanted book (random) | 50 spurs | 120 spurs | 250 spurs |
| Mending book | — | — | 800 spurs |
| Diamond tool (unenchanted) | — | 80 spurs | — |
| Diamond tool (enchanted) | — | — | 350 spurs |
| Bookshelf | 15 spurs | — | — |
#### Sell-to-villager (player gets spurs)
| Item | Spurs per unit |
|---|---|
| Wheat | 1 per 64 |
| Paper | 1 per 32 |
| Leather | 1 per 16 |
| Iron ingot | 2 per 1 |
| Diamond | 8 per 1 *(matches sell-shop fixed price — players use whichever is closer)* |
### Scope
~60 trades × 5 profession tiers = ~300 trade entries to redesign. One-time data-design pass, implemented via `ServerEvents.villagerTrades` in KubeJS.
---
## 6. Money inflow sources (detailed)
| Source | Cap / DR mechanism | Rough rate |
|---|---|---|
| **Daily bounties** | Per-player per-quest cooldown (24h) | ~200-500 spurs/day for an active player |
| **Sell shop (fixed price + DR)** | Lifetime sales tracker per player, 10% price drop per 64 sold | ~50-200 spurs/hr while diamond stockpile lasts |
| **Dynamic exchange** | Global supply pool — price drops with sales | Self-balancing |
| **First-time milestones** | One-shot per player (`hasFlag`) | 5-50 spurs per milestone, ~10 milestones total |
| **FTB Quest progression** | One-time per quest | Varies; cluster rewards at chapter completion |
| **Villager sell trades** | Inherently slow + bad prices | ~50 spurs/hr from a serious villager farm |
---
## 7. Money outflow sinks (detailed)
| Sink | Cost curve | Why this scales right |
|---|---|---|
| **Plot claims** | Free up to 9 chunks. 50 spurs/chunk to 25. 200 spurs/chunk beyond. | New players claim free starter areas; ambitious players pay real money |
Each phase is independently shippable. Earlier phases unlock value without depending on later ones.
| Phase | Deliverable | Spawn build required? |
|---|---|---|
| **0a** | **Mod additions PR:** FTB Quests + FTB XMod Compat + FTB Ranks (+ minor Easy NPC bump). New pack version. | No |
| **0b** | Spawn skeleton — 7 guild building blockouts (rough). **User does in-game when time permits.** Non-blocking for everything else. | Yes (user) |
| **1** | **Sell shop:** Numismatics shop blocks for diamonds (10 spurs) + netherite ingots (100 spurs). Lifetime-sale tracker for diminishing returns. | No — test anywhere, drop into Bazaar later |
| **2** | **Plot claim cost:** `FTBChunksEvents.before('claim')` deducts spurs. Free first 9 chunks, 50/chunk to 25, 200/chunk beyond. | No |
| **3** | **Bounty engine:** state machine + `/quests` commands + bossbar HUD + 3-slot cap. Daily quest pool with KubeJS-rotated dailies. NPC dialog hooks ready but inert until guild NPCs exist at spawn. | No (NPC layer activates once spawn is built) |
| **4** | **Villager rebalance:** strip vanilla, ship spur-priced trade table via `ServerEvents.villagerTrades`. | No |
| **5** | **Progression quest line:** FTB Quests anchor + first chapter. KubeJS rewards dispense spurs via Numismatics API. | No (anchor NPC at Library once spawn exists) |
| **6** | **Tier upgrades:** FTB Ranks integrated. `/tier upgrade` deducts spurs and promotes via `ftbranks add`. Rank perms gate FTB Chunks claim limits. | No |
| **7** | **Dynamic exchange rates:** global supply-pool pricing for raw mats. | No |
- State data under `world/data/bns_economy/<uuid>.json` per player. Readable, easy to debug. Migration to SQLite considered if dataset grows beyond ~100 players.
- All NPC dialog trees authored in Easy NPC's in-game editor, exported as preset JSONs into `pack/overrides/world/datapacks/bns-fuel/data/easy_npc/`. Dialog `Command` actions call into `/bns_quest` namespace which routes to KubeJS handlers.
- Trade table for villager rebalance: single source file `08_villager_trades.js`. Each profession × tier has its own block. One file = one diff to review during balance passes.
---
## See also
- `MEMORY.md` entries:
- `project-mc-player-economy.md` — earlier higher-level notes on Numismatics + plot system
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Matt
Matt