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

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:

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)