Mana-Loop/docs/specs/attunements/fabricator/systems/golemancy-spec.md

# Golemancy System — Design Spec (Redesign)

> 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 **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:**
- 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

---

## 2. Golem Slot Formula

Golem slots come from **two sources** that add together:

### 2.1 From Attunement Level

```
attunementSlots = floor(fabricatorLevel / 2)
```

| Fabricator Level | Slots |
|---|---|
| 1 | 0 |
| 2–3 | 1 |
| 4–5 | 2 |
| 6–7 | 3 |
| 8–9 | 4 |
| 10 | 5 |

### 2.2 From Discipline

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**

---

## 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.

---

## 4. Core

The Core acts as the golem's power source. It determines:

- **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

---

## 5. Frame

The Frame determines the golem's physical combat characteristics.

### 5.1 Frame Statistics

| Stat | Description |
|---|---|
| **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 |

### 5.2 Frame Definitions

| 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 |

### 5.3 Crystal-Steel Hybrid Frame

**Requirements:**
- Fabricator Attunement 5

**Properties:**
- Only frame capable of housing a **Guardian Core**
- **Required for all Guardian Constructs**
- Highest combined stats of any frame

---

## 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 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({
        ...golemDesign,
        roomsRemaining: golemDesign.core.maxRoomDuration,
        attackProgress: 0,
        currentMana: golemDesign.core.manaCapacity,  // starts full
      })
      activityLog("${golemDesign.name} summoned")
    else:
      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)

---

## 11. Golem Combat

Each active golem attacks on its own `attackProgress` timer:

```
golemProgress += HOURS_PER_TICK × golem.frame.attackSpeed
while golemProgress >= 1:
  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 frames (Sand, Shadowglass) distribute damage across multiple targets
- Elemental matchup applies if the frame has an element
- Enchantment effects apply to basic attacks only

---

## 12. Golem Mana & Regeneration

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):
  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 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

---

## 14. Room Duration Limit

```
onRoomCleared():
  for each activeGolem:
    activeGolem.roomsRemaining -= 1
    if activeGolem.roomsRemaining <= 0:
      dismiss(golem)
      activityLog("${golem.name} has faded after ${maxRoomDuration} rooms")
```

**Key rules:**
- Room duration ticks down on room **clear**, not on room **entry**
- Golems persist through the full room they were summoned in
- When `roomsRemaining` reaches 0, the golem is dismissed

---

## 15. Golem Design Data Shape

```typescript
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;
  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[];
}
```

---

## 16. Discipline Interactions

### 16.1 Golem Crafting Discipline

| Perk | Effect |
|---|---|
| `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) |

### 16.2 Fabricator Level

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

### 16.3 Component Unlocks via Attunements

| 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 |

---

## 17. Known Gaps / Implementation Status

| Feature | Status |
|---|---|
| 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 |

---

## 18. Acceptance Criteria

| # | Criterion |
|---|---|
| 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 |

---

## 19. Files Reference

| File | Role |
|---|---|
| `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) |