feat: redesign golemancy system spec - component-based construction (Core + Frame + Mind Circuit + Enchantments)

2026-06-05 15:36:17 +02:00
parent 6aed5c8d2b
commit c40e4ee940
3 changed files with 399 additions and 182 deletions
@@ -1,4 +1,4 @@
 # Circular Dependencies
-Generated: 2026-06-04T17:52:04.001Z
+Generated: 2026-06-05T12:07:36.291Z

 No circular dependencies found. ✅
@@ -1,6 +1,6 @@
 {
  "_meta": {
-    "generated": "2026-06-04T17:52:02.064Z",
+    "generated": "2026-06-05T12:07:34.394Z",
    "description": "Import dependency graph for src/lib/game. Keys are files, values are arrays of files they import.",
    "usage": "To find what a file affects, search for its path in the VALUES. To find what a file depends on, look at its KEY entry."
  },
@@ -1,29 +1,21 @@
-# Golemancy System — Design Spec
+# Golemancy System — Design Spec (Redesign)

-> Describes the Fabricator attunement's combat system: golem types, loadout
-> configuration, summoning lifecycle, maintenance costs, room duration, combat
-> behavior, and discipline interactions.
->
-> **⚠ Undergoing full redesign (see issue #268).** The golemancy system is being
-> redesigned from predefined golem types to a component-based construction system
-> (Core + Frame + Mind Circuit + Enchantments). The current data definitions exist
-> but are disconnected from the combat pipeline.
+> Describes the Fabricator attunement's combat system using the new **component-based construction system** (Core + Frame + Mind Circuit + Enchantments).
+> This replaces the previous predefined golem type system.
+> See Gitea issue #268 for the full redesign rationale.

 ---

 ## 1. Objective

-Golemancy is the Fabricator attunement's combat contribution. The player configures
-a golem loadout outside the spire, then golems are automatically summoned at each
-room entry, fight alongside the player, and disappear after a fixed number of rooms
-or if their maintenance cost cannot be met.
+Golemancy is the Fabricator attunement's combat contribution. The player **designs** custom golems by assembling components, then configures a loadout of these custom golems outside the spire. Golems are automatically summoned at each room entry, fight alongside the player, and disappear after a fixed number of rooms or if their maintenance cost cannot be met.

 **Design goals:**
- Golems provide parallel combat damage independent of the player's spells
- Different golem types offer tactical variety (single-target, AoE, fast, tanky)
- Maintenance cost and room duration create resource management decisions
- Hybrid golems require dual-attunement investment (Enchanter 5 + Fabricator 5)
- Golem loadout configuration outside spire allows strategic planning
+- Deep customization: players build golems from components rather than selecting predefined types
+- Strategic resource management: Core determines mana types, capacity, regen, and upkeep
+- Meaningful progression: higher-tier components unlock through attunement investment
+- Guardian Constructs: ultimate endgame golems requiring Invoker 5 + Fabricator 5 + Guardian Core
+- Component synergy: Frame + Core + Mind Circuit + Enchantments create unique builds

 ---

@@ -48,184 +40,333 @@ attunementSlots = floor(fabricatorLevel / 2)

 ### 2.2 From Discipline

-The Golem Crafting discipline provides:
+The **Golem Crafting** discipline provides:
 - Base `golemCapacity`: +2
 - Perk `golem-2` (capped, threshold 500, maxTier 2): +1 per tier = up to +2

 **Maximum total golem slots: 5 (attunement) + 2 (discipline) = 7**

-> **Note:** The AGENTS.md states `floor(fabricatorLevel / 2)` with max 5 at level 10.
-> The discipline-based capacity is additive on top of this.
+---
+
+## 3. Component-Based Construction
+
+Every golem consists of **three mandatory components** and **one optional component**:
+
+1. **Core** — Power source, determines mana types, capacity, regen, upkeep, duration
+2. **Frame** — Physical combat characteristics (damage, speed, armor pierce, magic affinity, special)
+3. **Mind Circuit** — Behavior logic (basic attacks, spell casting, spell selection)
+4. **Enchantments** (optional) — Sword effects applied to basic attacks
+
+The player designs golems in the Golemancy tab by selecting one of each mandatory component, then optionally adding enchantments.

 ---

-## 3. Golem Loadout Configuration
+## 4. Core

-The player configures a **golem loadout** from the Golemancy tab before entering
-the spire. The loadout defines which golems to attempt to summon and in what order.
-This configuration persists across rooms but not across spire runs.
+The Core acts as the golem's power source. It determines:

-The loadout is a prioritized list of golem IDs. On each room entry, the system
-iterates the loadout in order, attempting to summon each golem.
+- **Mana Types Available** — Which mana types the golem can use for spells/upkeep
+- **Mana Capacity** — Maximum mana the golem can hold
+- **Mana Regeneration** — Mana restored per in-game hour
+- **Summon Duration** — Max rooms the golem persists (`maxRoomDuration`)
+- **Player Upkeep Cost** — Mana cost per hour to maintain the golem
+
+**Player upkeep formula:**
+```
+Upkeep per hour = Mana Regen × 2
+```
+(This is deducted from the player's mana pools each tick)
+
+### 4.1 Core Tiers
+
+| Core Tier | Mana Types | Mana Capacity | Mana Regen | Max Room Duration | Summon Cost | Upkeep Cost (per hr) | Unlock Requirement |
+|---|---|---|---|---|---|---|---|
+| **Basic Core** | 1 (Earth) | 50 | 0.5 | 3 | 10 Earth | 1.0 Earth | Fabricator 2 |
+| **Intermediate Core** | 2 | 100 | 1.5 | 4 | 20 Crystal | 3.0 Crystal | Fabricator 4, Enchanter 2 |
+| **Advanced Core** | 3 | 200 | 3.0 | 5 | 30 Crystal | 6.0 Crystal | Fabricator 6, Enchanter 3 |
+| **Guardian Core** | Guardian-specific | 500 | 10.0 | 8 | Guardian-specific | 20.0 Guardian-specific | Invoker 5 + Fabricator 5, Guardian Pact signed |
+
+### 4.2 Core Mana Types
+
+- **Basic Core:** Only Earth mana
+- **Intermediate Core:** Player chooses 2 mana types from unlocked elements
+- **Advanced Core:** Player chooses 3 mana types from unlocked elements
+- **Guardian Core:** Provides **all mana types granted by the chosen Guardian** (e.g., a Metal Guardian Core provides Metal + Earth + Lightning)
+
+### 4.3 Guardian Core
+
+**Requirements:**
+- Invoker Attunement 5
+- Fabricator Attunement 5
+- Guardian Pact signed (for the specific guardian)
+
+**Properties:**
+- Provides all mana types granted by the chosen Guardian
+- Massive mana capacity (500) and regeneration (10/hr)
+- **Required for Guardian Constructs** (see §8)
+- Summon cost and upkeep use Guardian-specific mana types

 ---

-## 4. All 10 Golem Types
+## 5. Frame

-### 4.1 Base Golems (1)
+The Frame determines the golem's physical combat characteristics.

-| Field | Earth Golem |
+### 5.1 Frame Statistics
+
+| Stat | Description |
 |---|---|
-| **ID** | `earthGolem` |
-| **Tier** | 1 |
-| **Element** | Earth |
-| **Damage** | 8 |
-| **Attack Speed** | 1.5/hr |
-| **HP** (display) | 50 |
-| **Armor Pierce** | 15% |
-| **AoE** | No |
-| **Max Room Duration** | 3 |
-| **Summon Cost** | 10 earth |
-| **Maintenance Cost** | 0.5 earth/hr |
-| **Unlock** | Fabricator level 2 |
+| **Damage** | Base damage per basic attack |
+| **Speed** | Attack speed (attacks per in-game hour) |
+| **Armor Pierce** | Fraction of enemy armor bypassed (0–1) |
+| **Magic Affinity** | Percentage — determines spell damage efficiency (50% = spells deal 50% normal damage) |
+| **Special Effect** | Unique passive or active ability |

-### 4.2 Elemental Golems (3)
+### 5.2 Frame Definitions

-| Field | Steel Golem | Crystal Golem | Sand Golem |
-|---|---|---|---|
-| **ID** | `steelGolem` | `crystalGolem` | `sandGolem` |
-| **Tier** | 2 | 3 | 2 |
-| **Element** | Metal | Crystal | Sand |
-| **Damage** | 12 | 18 | 10 |
-| **Attack Speed** | 1.2/hr | 1.0/hr | 2.0/hr |
-| **HP** (display) | 60 | 40 | 45 |
-| **Armor Pierce** | 35% | 25% | 15% |
-| **AoE** | No | No | **Yes (2 targets)** |
-| **Max Room Duration** | 3 | 4 | 3 |
-| **Summon Cost** | 8 metal + 5 earth | 6 crystal + 3 earth | 10 sand + 4 earth |
-| **Maintenance Cost** | 0.6 metal + 0.2 earth/hr | 0.4 crystal + 0.2 earth/hr | 0.6 sand + 0.25 earth/hr |
-| **Unlock** | Metal mana unlocked | Crystal mana unlocked | Sand mana unlocked |
+| Frame | Damage | Speed | Armor Pierce | Magic Affinity | Special Effect | Unlock Requirement |
+|---|---|---|---|---|---|---|
+| **Earth** | Very Low | Medium | Very Low | Very Low | None | Fabricator 2 |
+| **Sand** | Low–Medium | Slow | **Very High** | Medium | **AoE** (attacks hit 2 targets) | Sand mana unlocked |
+| **Frost** | Medium | Medium | Medium | **High** | Attacks apply **Slow** | Frost mana unlocked |
+| **Crystal** | High | Fast | Medium–Low | **Very High** | None | Crystal mana unlocked |
+| **Steel** | Very High | Fast | High | Medium | None | Metal mana unlocked |
+| **Shadowglass** | Very High | **Very Fast** | Very High | **Very High** | **AoE** (attacks hit 2 targets) | Shadow Glass mana unlocked |
+| **Crystal-Steel Hybrid** | **Very High** | **Very Fast** | **Very High** | **Highest** | Supports Guardian Constructs | Fabricator 5 |

-### 4.3 Hybrid Golems (6) — Require Enchanter 5 + Fabricator 5
+### 5.3 Crystal-Steel Hybrid Frame

-| Field | Lava Golem | Galvanic Golem | Obsidian Golem |
-|---|---|---|---|
-| **ID** | `lavaGolem` | `galvanicGolem` | `obsidianGolem` |
-| **Tier** | 3 | 3 | 4 |
-| **Elements** | Earth + Fire | Metal + Lightning | Earth + Dark |
-| **Damage** | 15 | 10 | 25 |
-| **Attack Speed** | 1.0/hr | 3.5/hr | 0.8/hr |
-| **HP** (display) | 70 | 45 | 55 |
-| **Armor Pierce** | 20% | 45% | 50% |
-| **AoE** | **Yes (2 targets)** | No | No |
-| **Max Room Duration** | 4 | 4 | 5 |
-| **Summon Cost** | 15 earth + 12 fire | 12 metal + 8 lightning | 18 earth + 10 dark |
-| **Maintenance Cost** | 0.6 earth + 0.7 fire/hr | 0.4 metal + 0.7 lightning/hr | 0.5 earth + 0.6 dark/hr |
-| **Special** | Burn DoT | Lightning Speed | Devastating Strike |
-| **Unlock** | Enchanter 5 + Fabricator 5 | Enchanter 5 + Fabricator 5 | Enchanter 5 + Fabricator 5 |
+**Requirements:**
+- Fabricator Attunement 5

-| Field | Prism Golem | Quicksilver Golem | Voidstone Golem |
-|---|---|---|---|
-| **ID** | `prismGolem` | `quicksilverGolem` | `voidstoneGolem` |
-| **Tier** | 4 | 3 | 4 |
-| **Elements** | Crystal + Light | Metal + Water | Earth + Void |
-| **Damage** | 28 | 14 | **40** |
-| **Attack Speed** | 2.0/hr | **4.0/hr** | 0.6/hr |
-| **HP** (display) | 60 | 55 | **100** |
-| **Armor Pierce** | 45% | 35% | **60%** |
-| **AoE** | **Yes (3 targets)** | No | **Yes (3 targets)** |
-| **Max Room Duration** | 5 | 4 | 5 |
-| **Summon Cost** | 16 crystal + 10 light | 10 metal + 8 water | 22 earth + 14 void |
-| **Maintenance Cost** | 0.6 crystal + 0.6 light/hr | 0.4 metal + 0.4 water/hr | 0.5 earth + 0.9 void/hr |
-| **Special** | Piercing Beams | Flow (evasion) | Void Infusion |
-| **Unlock** | Enchanter 5 + Fabricator 5 | Enchanter 5 + Fabricator 5 | Enchanter 5 + Fabricator 5 |
-
-### 4.4 Summary Table
-
-| Golem | Tier | DMG | SPD | HP | Pierce | AoE | Targets | Rooms | Unlock |
-|---|---|---|---|---|---|---|---|---|---|
-| Earth | 1 | 8 | 1.5 | 50 | 15% | No | 1 | 3 | Fabricator Lv2 |
-| Steel | 2 | 12 | 1.2 | 60 | 35% | No | 1 | 3 | Metal mana |
-| Crystal | 3 | 18 | 1.0 | 40 | 25% | No | 1 | 4 | Crystal mana |
-| Sand | 2 | 10 | 2.0 | 45 | 15% | Yes | 2 | 3 | Sand mana |
-| Lava | 3 | 15 | 1.0 | 70 | 20% | Yes | 2 | 4 | Ench5+Fab5 |
-| Galvanic | 3 | 10 | 3.5 | 45 | 45% | No | 1 | 4 | Ench5+Fab5 |
-| Obsidian | 4 | 25 | 0.8 | 55 | 50% | No | 1 | 5 | Ench5+Fab5 |
-| Prism | 4 | 28 | 2.0 | 60 | 45% | Yes | 3 | 5 | Ench5+Fab5 |
-| Quicksilver | 3 | 14 | 4.0 | 55 | 35% | No | 1 | 4 | Ench5+Fab5 |
-| Voidstone | 4 | 40 | 0.6 | 100 | 60% | Yes | 3 | 5 | Ench5+Fab5 |
+**Properties:**
+- Only frame capable of housing a **Guardian Core**
+- **Required for all Guardian Constructs**
+- Highest combined stats of any frame

 ---

-## 5. Summoning on Room Entry
+## 6. Mind Circuit
+
+The Mind Circuit controls the golem's behavior and spell usage.
+
+### 6.1 Simple Logic Circuit
+
+| Property | Value |
+|---|---|
+| **Cost** | Earth Mana (summon) |
+| **Behavior** | Performs basic attacks only. Targets nearest enemy. |
+| **Requirements** | None |
+| **Spell Slots** | 0 |
+
+### 6.2 Intermediate Logic Circuit
+
+| Property | Value |
+|---|---|
+| **Cost** | Crystal Mana (summon) |
+| **Behavior** | Player selects **1 spell** from unlocked Spell Enchantments (caster pool). Golem attempts to cast the spell whenever enough mana is available. Otherwise performs basic attacks. |
+| **Requirements** | Enchanter 2 + Fabricator 3 |
+| **Spell Slots** | 1 |
+
+### 6.3 Advanced Logic Circuit
+
+| Property | Value |
+|---|---|
+| **Cost** | Crystal Mana (summon) |
+| **Behavior** | Player selects **2 spells**. Golem alternates: Spell A → Spell B → Spell A → Spell B... If unable to cast (insufficient mana), performs basic attacks. |
+| **Requirements** | Enchanter 3 + Fabricator 4 |
+| **Spell Slots** | 2 (alternating) |
+
+### 6.4 Guardian Circuit
+
+| Property | Value |
+|---|---|
+| **Cost** | Guardian-specific mana (summon) |
+| **Behavior** | Required for Guardian Constructs. Player selects **1 spell for each mana type** available to the Guardian Core. Cycles through all selected spells in order. |
+| **Requirements** | Invoker 5 + Fabricator 5 |
+| **Spell Slots** | = Number of mana types from Guardian Core (typically 3–4) |
+
+---
+
+## 7. Enchantments (Optional)
+
+Enchantments add sword effects to a golem's **basic attacks**.
+
+**Requirements:**
+- Enchanter Attunement 5
+- Fabricator Attunement 5
+
+**Enchantment Capacity:**
+Determined by: `Frame.MagicAffinity × Core.TierMultiplier`
+- Basic Core: ×1.0
+- Intermediate Core: ×1.5
+- Advanced Core: ×2.0
+- Guardian Core: ×3.0
+
+Each enchantment consumes capacity. Capacity is a soft limit — exceeding it reduces Magic Affinity proportionally.
+
+**Summon Cost Increase:**
+```
+Summon Cost += Enchantment Base Cost (per enchantment)
+```
+
+### 7.1 Enchantment Examples
+
+| Enchantment | Effect on Basic Attack |
+|---|---|
+| **Sword_Fire** | Applies **Burn** DoT |
+| **Sword_Frost** | Applies additional **Slow** |
+| **Sword_Lightning** | Chance to **Shock** (stun) |
+| **Sword_Shadow** | Chance to **Weaken** (reduce enemy damage) |
+| **Sword_Metal** | Bonus **Armor Pierce** |
+| **Sword_Crystal** | Bonus **Critical Chance** |
+
+*(Full list mirrors sword enchantment effects from the enchanting system)*
+
+---
+
+## 8. Guardian Constructs
+
+Guardian Constructs are the ultimate golems, combining a **Guardian Core** + **Crystal-Steel Hybrid Frame** + **Guardian Circuit** + Enchantments.
+
+### 8.1 Requirements
+
+- Invoker Attunement 5
+- Fabricator Attunement 5
+- Guardian Pact signed for the chosen guardian
+- Guardian Core (crafted from guardian materials)
+
+### 8.2 Properties
+
+- **Mana Types:** All types granted by the Guardian (e.g., Metal Guardian → Metal, Earth, Lightning)
+- **Frame:** Must use Crystal-Steel Hybrid Frame
+- **Mind Circuit:** Must use Guardian Circuit
+- **Spell Selection:** One spell per mana type, cycled in order
+- **Enchantments:** Can apply enchantments up to high capacity (Guardian Core ×3.0 multiplier)
+- **Duration:** 8 rooms (Guardian Core base)
+- **Power Level:** Highest in the game — intended for endgame spire pushing
+
+---
+
+## 9. Golem Loadout Configuration
+
+The player configures a **golem loadout** from the Golemancy tab before entering the spire.
+
+- Each loadout slot contains a **complete golem design** (Core + Frame + Mind Circuit + Enchantments)
+- The loadout is a prioritized list of golem designs
+- On each room entry, the system iterates the loadout in order, attempting to summon each golem
+- Loadout persists across rooms but **not** across spire runs
+
+---
+
+## 10. Summoning on Room Entry

 When the player enters a new combat room:

 ```
 onRoomEntry():
-  for each golem in golemLoadout:
-    if player has enough mana of golem.summonCostType >= golem.summonCost:
-      deductMana(golem.summonCost, golem.summonCostType)
+  for each golemDesign in golemLoadout:
+    totalSummonCost = golemDesign.core.summonCost
+                     + golemDesign.frame.summonCost
+                     + golemDesign.mindCircuit.summonCost
+                     + sum(golemDesign.enchantments[i].summonCost)
+    
+    if player has enough mana for totalSummonCost:
+      deductMana(totalSummonCost)
      activeGolems.push({
-        ...golemDef,
-        roomsRemaining: golemDef.maxRoomDuration,
+        ...golemDesign,
+        roomsRemaining: golemDesign.core.maxRoomDuration,
        attackProgress: 0,
+        currentMana: golemDesign.core.manaCapacity,  // starts full
      })
-      activityLog("${golem.name} summoned")
+      activityLog("${golemDesign.name} summoned")
    else:
-      activityLog("Not enough mana to summon ${golem.name} — skipped")
+      activityLog("Not enough mana to summon ${golemDesign.name} — skipped")
 ```

 **Key rules:**
 - Golems that cannot be summoned (insufficient mana) are **not re-attempted** within the same room
 - Failed golems will be attempted again on the next room entry
 - Summoning order follows the loadout priority list
+- Golem starts with full mana (from Core capacity)

 ---

-## 6. Golem Combat
+## 11. Golem Combat

-Each active golem attacks on its own `attackProgress` timer, identical to swords:
+Each active golem attacks on its own `attackProgress` timer:

 ```
-golemProgress += HOURS_PER_TICK × golem.attackSpeed
+golemProgress += HOURS_PER_TICK × golem.frame.attackSpeed
 while golemProgress >= 1:
-  dmg = golem.baseDamage
-  if golem.element:
-    dmg ×= getElementalBonus(golem.element, enemy.element)
-  applyGolemEffects(golem, dmg, enemy)
-  applyDamageToRoom(dmg)
+  if golem.mindCircuit.hasSpells and golem.currentMana >= spellCost:
+    castSpell(golem, spell)
+    golem.currentMana -= spellCost
+  else:
+    dmg = golem.frame.baseDamage
+    if golem.frame.element:
+      dmg ×= getElementalBonus(golem.frame.element, enemy.element)
+    applyGolemEffects(golem, dmg, enemy)  // includes enchantment effects
+    applyDamageToRoom(dmg)
  golemProgress -= 1
 ```

+**Spell Casting:**
+- Spell damage = `baseSpellDamage × golem.frame.magicAffinity`
+- Spell uses golem's mana pool (not player's)
+- Golem mana regenerates at `core.manaRegen` per hour
+
 **Key rules:**
 - Golems ignore Executioner and Berserker discipline specials
- AoE golems distribute damage across multiple targets
- Elemental matchup applies if the golem has an element
+- AoE frames (Sand, Shadowglass) distribute damage across multiple targets
+- Elemental matchup applies if the frame has an element
+- Enchantment effects apply to basic attacks only

 ---

-## 7. Maintenance Cost
+## 12. Golem Mana & Regeneration

-Each tick, each active golem checks its maintenance cost:
+Each golem has its **own mana pool** (separate from player):
+
+- **Capacity:** Determined by Core tier
+- **Regeneration:** `core.manaRegen` per in-game hour (ticks every game tick)
+- **Usage:** Spells consume golem mana; basic attacks are free
+
+```
+tickGolemMana(golem):
+  golem.currentMana = min(golem.core.manaCapacity, golem.currentMana + golem.core.manaRegen × HOURS_PER_TICK)
+```
+
+---
+
+## 13. Maintenance Cost (Player Upkeep)
+
+Each tick, each active golem checks its **player upkeep cost** (derived from Core):

 ```
 tickGolemMaintenance(golem):
-  if player mana[golem.maintenanceCostType] >= golem.maintenanceCost × HOURS_PER_TICK:
-    deductMana(golem.maintenanceCost × HOURS_PER_TICK, golem.maintenanceCostType)
+  upkeepPerHour = golem.core.manaRegen × 2
+  upkeepPerTick = upkeepPerHour × HOURS_PER_TICK
+  
+  // Upkeep uses the Core's primary mana type(s)
+  // For multi-type cores, cost is split evenly across types
+  
+  if player has enough mana for upkeepPerTick:
+    deductMana(upkeepPerTick, golem.core.primaryManaTypes)
  else:
    dismiss(golem)
-    activityLog("${golem.name} dismissed — insufficient ${golem.maintenanceCostType} mana")
+    activityLog("${golem.name} dismissed — insufficient mana for upkeep")
 ```

 **Key rules:**
+- Upkeep is paid from **player's mana**, not golem's mana
 - A dismissed golem is **not re-summoned mid-room**
 - It will be re-attempted on the next room entry if mana has recovered
 - Maintenance is checked every tick, not just on room transitions

 ---

-## 8. Room Duration Limit
+## 14. Room Duration Limit

 ```
 onRoomCleared():
@@ -243,92 +384,168 @@ onRoomCleared():

 ---

-## 9. Golem Data Shape
+## 15. Golem Design Data Shape

 ```typescript
-interface GolemDefinition {
-  id: string;
-  name: string;
-  tier: number;                    // 1–4 (determines general power)
+interface GolemDesign {
+  id: string;                    // Player-assigned or auto-generated
+  name: string;                  // Player-defined name
+  core: CoreDefinition;
+  frame: FrameDefinition;
+  mindCircuit: MindCircuitDefinition;
+  enchantments: EnchantmentDefinition[];  // Optional, 0-N
+  
+  // Computed fields (derived from components)
+  maxRoomDuration: number;
+  totalSummonCost: ManaCost[];
+  upkeepCostPerHour: ManaCost[];
+  manaCapacity: number;
+  manaRegen: number;
  baseDamage: number;
-  attackSpeed: number;             // attacks per in-game hour
-  element?: ElementType;           // optional elemental type for matchup
-  maxRoomDuration: number;         // rooms before disappearing
-  summonCost: number;
-  summonCostType: ElementType | 'raw';
-  maintenanceCost: number;         // per in-game hour
-  maintenanceCostType: ElementType | 'raw';
-  onHitEffect?: GolemHitEffect;    // DoT, AoE, etc.
-  armorPierce?: number;            // 0-1, bypasses this fraction of enemy armor
-  aoe?: boolean;
-  aoeTargets?: number;
+  attackSpeed: number;
+  armorPierce: number;
+  magicAffinity: number;
+  aoeTargets: number;
+  spellSlots: number;
+  availableManaTypes: string[];
+}
+```
+
+Component definitions:
+
+```typescript
+interface CoreDefinition {
+  id: 'basic' | 'intermediate' | 'advanced' | 'guardian';
+  tier: 1 | 2 | 3 | 4;
+  manaTypes: string[];           // Player-selected (for intermediate/advanced/guardian)
+  manaCapacity: number;
+  manaRegen: number;
+  maxRoomDuration: number;
+  summonCost: ManaCost[];
+  primaryManaType: string;       // For upkeep calculation
+}
+
+interface FrameDefinition {
+  id: 'earth' | 'sand' | 'frost' | 'crystal' | 'steel' | 'shadowglass' | 'crystalSteelHybrid';
+  baseDamage: number;
+  attackSpeed: number;
+  armorPierce: number;
+  magicAffinity: number;         // 0.0–1.0+
+  aoeTargets: number;
+  element?: string;              // For elemental matchup
+  specialEffect: 'none' | 'aoe' | 'slow' | 'guardianConstruct';
+  summonCost: ManaCost[];
+}
+
+interface MindCircuitDefinition {
+  id: 'simple' | 'intermediate' | 'advanced' | 'guardian';
+  spellSlots: number;
+  spellSelection: string[];      // Spell IDs selected by player
+  behavior: 'basicOnly' | 'castSpell1' | 'alternate2' | 'cycleAll';
+  summonCost: ManaCost[];
+}
+
+interface EnchantmentDefinition {
+  id: string;                    // e.g., 'sword_fire'
+  effect: string;                // Effect description
+  capacityCost: number;
+  summonCost: ManaCost[];
 }
 ```

 ---

-## 10. Discipline Interactions
+## 16. Discipline Interactions

-### 10.1 Golem Crafting Discipline
+### 16.1 Golem Crafting Discipline

 | Perk | Effect |
 |---|---|
-| `golem-1` (once @ 200 XP) | Unlocks golem summoning ability |
+| `golem-1` (once @ 200 XP) | Unlocks golem **design** ability (can create custom golems) |
 | `golem-2` (capped @ 500, maxTier 2) | +1 Golem Capacity per tier (max +2) |

-### 10.2 Fabricator Level
+### 16.2 Fabricator Level

 Directly determines base golem slots: `floor(fabricatorLevel / 2)`.

-### 10.3 Dual Attunement Requirement
+### 16.3 Component Unlocks via Attunements

-All 6 hybrid golems require **Enchanter 5 + Fabricator 5**. This means the player
-must have both attunements active and leveled to at least 5 to access the most
-powerful golem types.
+| Component | Unlock Requirement |
+|---|---|
+| Basic Core | Fabricator 2 |
+| Intermediate Core | Fabricator 4 + Enchanter 2 |
+| Advanced Core | Fabricator 6 + Enchanter 3 |
+| Guardian Core | Invoker 5 + Fabricator 5 + Guardian Pact |
+| Earth Frame | Fabricator 2 |
+| Sand Frame | Sand mana unlocked |
+| Frost Frame | Frost mana unlocked |
+| Crystal Frame | Crystal mana unlocked |
+| Steel Frame | Metal mana unlocked |
+| Shadowglass Frame | Shadow Glass mana unlocked |
+| Crystal-Steel Hybrid Frame | Fabricator 5 |
+| Simple Logic Circuit | None |
+| Intermediate Logic Circuit | Enchanter 2 + Fabricator 3 |
+| Advanced Logic Circuit | Enchanter 3 + Fabricator 4 |
+| Guardian Circuit | Invoker 5 + Fabricator 5 |
+| Enchantments | Enchanter 5 + Fabricator 5 |

 ---

-## 11. Known Gaps / Implementation Status
+## 17. Known Gaps / Implementation Status

 | Feature | Status |
 |---|---|
-| Golem data definitions | ✅ Complete (10 golems in `data/golems/`) |
-| Golem loadout UI | ✅ Partial (GolemancyTab exists) |
-| Summoning on room entry | ❌ Not wired into combat tick |
-| Maintenance cost per tick | ❌ Not wired into combat tick |
-| Room duration tracking | ❌ Not wired into room clear |
-| Golem combat (attack timer) | ❌ Not wired into combat tick |
-| Golemancy combat pipeline | ❌ `golem-combat-actions.ts` exists but disconnected |
+| Core definitions & data | ❌ Not implemented |
+| Frame definitions & data | ❌ Not implemented |
+| Mind Circuit definitions & data | ❌ Not implemented |
+| Enchantment system for golems | ❌ Not implemented |
+| Golem design builder UI | ❌ Not implemented |
+| Golem loadout with designs | ❌ Not implemented |
+| Golem mana pool & regen | ❌ Not implemented |
+| Spell casting from golem mana | ❌ Not implemented |
+| Guardian Core + Guardian Constructs | ❌ Not implemented |
+| Summoning on room entry (new system) | ❌ Not implemented |
+| Maintenance cost (player upkeep) | ❌ Not implemented |
+| Room duration tracking | ❌ Not implemented |
+| Golem combat (new system) | ❌ Not implemented |

 ---

-## 12. Acceptance Criteria
+## 18. Acceptance Criteria

 | # | Criterion |
 |---|---|
-| AC-1 | Golem slots = `floor(fabricatorLevel / 2)` + discipline bonus. |
-| AC-2 | Golems are summoned on room entry if mana allows; failed summons are skipped for that room. |
-| AC-3 | Each golem attacks on its own timer using its `attackSpeed` stat. |
-| AC-4 | Elemental matchup applies to golem attacks when the golem has an element. |
-| AC-5 | AoE golems distribute damage across `aoeTargets` enemies. |
-| AC-6 | Maintenance cost is deducted each tick; golems dismiss if cost cannot be met. |
-| AC-7 | Dismissed golems are not re-summoned mid-room. |
-| AC-8 | Room duration ticks down on room clear, not entry. |
-| AC-9 | Golems disappear after `maxRoomDuration` rooms. |
-| AC-10 | Hybrid golems require Enchanter 5 + Fabricator 5. |
-| AC-11 | Golem loadout is configured outside the spire and persists across rooms. |
-| AC-12 | Golem HP is display-only; golems don't take damage from enemies. |
+| AC-1 | Player can design golems by selecting Core + Frame + Mind Circuit + Enchantments |
+| AC-2 | Core determines mana types, capacity, regen, duration, and upkeep cost |
+| AC-3 | Frame determines damage, speed, armor pierce, magic affinity, and special |
+| AC-4 | Mind Circuit determines spell behavior (0, 1, 2 alternating, or cycle all) |
+| AC-5 | Enchantments add sword effects to basic attacks, consume capacity |
+| AC-6 | Golem slots = `floor(fabricatorLevel / 2)` + discipline bonus (max 7) |
+| AC-7 | Golems summoned on room entry if player can afford total summon cost |
+| AC-8 | Each golem has own mana pool; regens at Core rate; spells consume golem mana |
+| AC-9 | Spell damage scaled by Frame's Magic Affinity |
+| AC-10 | Player upkeep = Core.manaRegen × 2 per hour; deducted from player mana |
+| AC-11 | Golems dismissed if upkeep unpaid; not re-summoned mid-room |
+| AC-12 | Room duration ticks down on room clear; golems fade after maxRoomDuration |
+| AC-13 | Guardian Constructs require Guardian Core + Crystal-Steel Frame + Guardian Circuit |
+| AC-14 | Guardian Constructs: one spell per mana type, cycled |
+| AC-15 | Component unlocks gated by attunement levels per §16.3 |
+| AC-16 | Loadout configured outside spire, persists across rooms, resets per run |

 ---

-## 13. Files Reference
+## 19. Files Reference

 | File | Role |
 |---|---|
-| `src/lib/game/data/golems/golems-data.ts` | All 10 golem definitions |
-| `src/lib/game/data/golems/types.ts` | Golem type definitions |
-| `src/lib/game/data/disciplines/fabricator.ts` | Golem Crafting discipline |
-| `src/lib/game/stores/golem-combat-actions.ts` | Golem combat actions (disconnected) |
-| `src/lib/game/stores/pipelines/golem-combat.ts` | Golem combat pipeline (disconnected) |
-| `src/components/game/tabs/GolemancyTab.tsx` | Golemancy UI |
-| `docs/specs/spire-combat-spec.md` §9 | Authoritative golemancy spec |
+| `src/lib/game/data/golems/cores.ts` | Core definitions (to be created) |
+| `src/lib/game/data/golems/frames.ts` | Frame definitions (to be created) |
+| `src/lib/game/data/golems/mindCircuits.ts` | Mind Circuit definitions (to be created) |
+| `src/lib/game/data/golems/golemEnchantments.ts` | Golem enchantment definitions (to be created) |
+| `src/lib/game/data/golems/types.ts` | TypeScript interfaces for component system |
+| `src/lib/game/data/golems/index.ts` | Barrel exports |
+| `src/lib/game/data/disciplines/fabricator.ts` | Golem Crafting discipline (update perks) |
+| `src/lib/game/stores/golem-combat-actions.ts` | Golem combat actions (rewrite) |
+| `src/lib/game/stores/pipelines/golem-combat.ts` | Golem combat pipeline (rewrite) |
+| `src/components/game/tabs/GolemancyTab.tsx` | Golemancy UI (major rewrite — design builder) |
+| `docs/specs/spire-combat-spec.md §9` | Authoritative runtime spec (needs update) |