Architecture

Status: Planned

The project should be built as a CurseForge pack plus a custom core mod.

For the exact pre-review pack choice and canonical phase table, use Pack Baseline and Phase Registry alongside this page.

Why This Split

Existing mods already solve several non-unique problems well:

• Quest UI
• Recipe visibility
• Per-player loot
• Travel network
• Some combat feel
• Some dungeon scaffolding

The custom mod should be reserved for what actually makes the overhaul unique:

• Biome progression rules
• Boss encounters
• Material families
• Armor sets
• Weapon identities
• Station ladder and station-gated recipe progression
• Non-breaking gear rules, gear upgrade lines, and Etching systems
• Relics and slot progression
• Mounts, bond sigils, and tack
• Grapnels
• Worldshift state changes
• Stormfront events
• Death handling and fortification-pressure rules
• Regional mob mutations
• Vertical world features such as living cave content, sky routes, and otherworld progression
• Quest gating flags
• Adventure pacing

Product Layers

Layer 1: Pack Infrastructure

Purpose:

• User install flow
• Dependency management
• Shared configs
• Server and client parity

Likely contents:

• CurseForge profile
• Config overrides
• Datapacks
• KubeJS scripts

Layer 2: Custom Core Mod

Purpose:

• Registries and code-driven content
• Boss AI and encounter logic
• Custom equipment systems
• Content flags and unlock states

Layer 3: Server Bundle

Purpose:

• Prepared dedicated server root
• Importable zip for Crafty
• Locked config set for multiplayer play

Recommended Repo Layout

Target structure once implementation starts:

docs/
  wiki/
mod/
  src/
pack/
  config/
  defaultconfigs/
  kubejs/
  datapacks/
server/
  export/

Responsibility Split

Use the custom mod for:

• Boss entities and arenas
• Summon items and gate items
• Boss summon logic and rematch flow
• Armor, weapons, relics, curios integration
• Crafting station blocks, upgrades, and station-aware crafting screens
• Nearby-storage ingredient lookup and local Craft Radius rules
• Gear upgrade recipes, Etch Scrolls, and Etching application flow
• Mount and tack registries
• Grapnel items and custom traversal behavior
• Death retention rules and any non-item-loss penalty handling
• Fortification tiers, breach timings, and hostile-mob structure-damage rules
• Controller-safe custom UI for project systems
• Custom loot tables that must be code-aware
• Biome challenge logic if pack tooling is not enough
• Regional mob mutation logic
• Worldshift and Stormfront state management

Use KubeJS or datapacks for:

• Recipe edits
• Loot tweaks
• Structure pool tuning
• Quest unlock glue
• Minor balance passes
• Some event scheduling and spawn weight tuning

Use pack mods for:

• Quest UI
• Loot instancing
• Travel nodes
• Equipment slot framework if adopted
• Recipe browser
• Recipe browsing and discovery support around the custom station ladder
• Base structure scaffolding

Design Constraints

• Do not let generic content mods flood the progression with irrelevant gear
• Do not add multiple mods that solve the same loot or travel problem
• Do not start by implementing settlement automation before the exploration loop works
• Keep multiplayer deterministic where progression is shared
• Do not outsource the mount system to a random pack mod if it defines the project identity