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

Golemancy System — Design Spec

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.

---

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.

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

---

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

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. Golem Loadout Configuration

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 loadout is a prioritized list of golem IDs. On each room entry, the system iterates the loadout in order, attempting to summon each golem.

---

4. All 10 Golem Types

4.1 Base Golems (1)

Field	Earth Golem
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

4.2 Elemental Golems (3)

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

4.3 Hybrid Golems (6) — Require Enchanter 5 + Fabricator 5

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

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

---

5. 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)
      activeGolems.push({
        ...golemDef,
        roomsRemaining: golemDef.maxRoomDuration,
        attackProgress: 0,
      })
      activityLog("${golem.name} summoned")
    else:
      activityLog("Not enough mana to summon ${golem.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

---

6. Golem Combat

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

golemProgress += HOURS_PER_TICK × golem.attackSpeed
while golemProgress >= 1:
  dmg = golem.baseDamage
  if golem.element:
    dmg ×= getElementalBonus(golem.element, enemy.element)
  applyGolemEffects(golem, dmg, enemy)
  applyDamageToRoom(dmg)
  golemProgress -= 1

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

---

7. Maintenance Cost

Each tick, each active golem checks its maintenance cost:

tickGolemMaintenance(golem):
  if player mana[golem.maintenanceCostType] >= golem.maintenanceCost × HOURS_PER_TICK:
    deductMana(golem.maintenanceCost × HOURS_PER_TICK, golem.maintenanceCostType)
  else:
    dismiss(golem)
    activityLog("${golem.name} dismissed — insufficient ${golem.maintenanceCostType} mana")

Key rules:

• 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

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

---

9. Golem Data Shape

interface GolemDefinition {
  id: string;
  name: string;
  tier: number;                    // 1–4 (determines general power)
  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;
}

---

10. Discipline Interactions

10.1 Golem Crafting Discipline

Perk	Effect
golem-1 (once @ 200 XP)	Unlocks golem summoning ability
golem-2 (capped @ 500, maxTier 2)	+1 Golem Capacity per tier (max +2)

10.2 Fabricator Level

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

10.3 Dual Attunement Requirement

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.

---

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

---

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

---

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