From 40d310b55a24dfdd8d43752d0f1107a5de407ddc Mon Sep 17 00:00:00 2001 From: Refactoring Agent <[email protected]> Date: Sat, 2 May 2026 19:59:33 +0200 Subject: [PATCH] docs: update AGENTS.md, GAME_BRIEFING.md, and skills.md after refactoring --- AGENTS.md | 478 +++++++++++++++++++++++++----------------- docs/GAME_BRIEFING.md | 164 ++++++++++----- docs/skills.md | 113 ++++++++-- 3 files changed, 501 insertions(+), 254 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5beb80d..8efba19 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,14 +32,14 @@ git config --global user.email "zhipu@local.local" 1. **Pull the latest changes:** ```bash - cd /home/z/my-project && git pull origin master + cd /home/user/repos/Mana-Loop && git pull origin master ``` 2. **Do your task** - Make all necessary code changes 3. **Before finishing, commit and push:** ```bash - cd /home/z/my-project + cd /home/user/repos/Mana-Loop git add -A git commit -m "descriptive message about changes" git push origin master @@ -59,7 +59,7 @@ git config --global user.email "zhipu@local.local" - **Framework**: Next.js 16 with App Router - **Language**: TypeScript 5 - **Styling**: Tailwind CSS 4 with shadcn/ui components -- **State Management**: Zustand with persist middleware +- **State Management**: Zustand with persist middleware (modular store architecture) - **Database**: Prisma ORM with SQLite (for persistence features) ## Core Game Loop @@ -75,93 +75,250 @@ git config --global user.email "zhipu@local.local" ``` src/ ├── app/ -│ ├── page.tsx # Main game UI (~548 lines, reduced via component extraction) +│ ├── page.tsx # Main game UI (~reduced via component extraction) │ ├── layout.tsx # Root layout with providers -│ └── api/ # API routes (minimal use) +│ ├── api/ # API routes (minimal use) +│ └── components/ # App-level components +│ ├── GameOverScreen.tsx +│ ├── LeftPanel.tsx +│ └── ... ├── components/ │ ├── ui/ # shadcn/ui components (auto-generated) -│ └── game/ -│ ├── index.ts # Barrel exports -│ ├── ActionButtons.tsx # Current action display with progress indicator -│ ├── CalendarDisplay.tsx # Day calendar with incursion indicators -│ ├── CraftingProgress.tsx # Design/preparation/application progress bars -│ ├── StudyProgress.tsx # Current study progress with cancel button -│ ├── ManaDisplay.tsx # Mana/gathering section with progress bar -│ ├── TimeDisplay.tsx # Day/hour display with pause toggle -│ └── tabs/ # Tab-specific components (Task 2: all tabs refactored) -│ ├── index.ts # Tab component exports -│ ├── CraftingTab.tsx # Enchantment crafting UI (~164 lines) -│ ├── LabTab.tsx # Skill upgrade and lab features -│ ├── SpellsTab.tsx # Spell management and equipment spells -│ ├── SpireTab.tsx # Combat with Spire Mode (~354 lines, Task 2 overhaul) -│ ├── StatsTab.tsx # Player statistics (~251 lines, Task 2: elements locked) -│ ├── SkillsTab.tsx # Skill tree display (~371 lines, Task 2: Ascension deleted) -│ ├── EquipmentTab.tsx # Gear management (~435 lines) -│ ├── DebugTab.tsx # Debug tools (~34 lines, Task 2: added Pact buttons) -│ └── LootTab.tsx # Loot display (~48 lines, Task 2: Transference removed) +│ └── game/ # All game components (modular structure) +│ ├── index.ts # Barrel exports +│ ├── GameContext.tsx +│ ├── ActionButtons.tsx +│ ├── CalendarDisplay.tsx +│ ├── CraftingProgress.tsx +│ ├── ManaDisplay.tsx +│ ├── TimeDisplay.tsx +│ ├── tabs/ # Tab-specific components +│ │ ├── index.ts +│ │ ├── AchievementsTab.tsx +│ │ ├── AttunementsTab.tsx +│ │ ├── CraftingTab.tsx +│ │ ├── DebugTab.tsx +│ │ ├── EquipmentTab.tsx +│ │ ├── GolemancyTab.tsx +│ │ ├── LabTab.tsx +│ │ ├── LootTab.tsx +│ │ ├── PrestigeTab.tsx +│ │ ├── SkillsTab.tsx +│ │ ├── SpellsTab.tsx +│ │ ├── SpireTab.tsx +│ │ ├── StatsTab.tsx +│ │ ├── EquipmentSlotGrid.tsx +│ │ ├── EquipmentControls.tsx +│ │ ├── EnchantmentsPanel.tsx +│ │ ├── EquipmentInventory.tsx +│ │ ├── SkillRow.tsx +│ │ ├── SkillCategoryHeader.tsx +│ │ ├── MilestoneProgress.tsx +│ │ ├── SkillMultipliers.tsx +│ │ ├── SpireHeader.tsx +│ │ ├── GuardianPanel.tsx +│ │ ├── RoomDisplay.tsx +│ │ ├── FloorControls.tsx +│ │ ├── CombatStatsPanel.tsx +│ │ └── ActivityLog.tsx +│ ├── crafting/ # Crafting-specific components +│ │ ├── index.tsx +│ │ ├── EnchantmentDesigner/ +│ │ ├── EnchantmentApplier.tsx +│ │ ├── EnchantmentPreparer.tsx +│ │ └── EquipmentCrafter.tsx +│ ├── stats/ # Stats display components +│ │ ├── index.tsx +│ │ ├── CombatStatsSection.tsx +│ │ ├── ManaStatsSection.tsx +│ │ ├── ManaTypeBreakdown.tsx +│ │ ├── StudyStatsSection.tsx +│ │ └── UpgradeEffectsSection.tsx +│ ├── debug/ # Debug tools +│ │ ├── index.tsx +│ │ ├── SkillDebug.tsx +│ │ ├── ElementDebug.tsx +│ │ ├── AttunementDebug.tsx +│ │ ├── GolemDebug.tsx +│ │ ├── PactDebug.tsx +│ │ └── GameStateDebug.tsx +│ ├── shared/ # Shared sub-components +│ │ ├── MemorySlotPicker.tsx +│ │ ├── StudyProgress.tsx +│ │ └── UpgradeDialog.tsx +│ └── LootInventory/ # Loot display components +│ ├── index.tsx +│ ├── MaterialItem.tsx +│ ├── EssenceItem.tsx +│ ├── BlueprintsSection.tsx +│ ├── EquipmentItem.tsx +│ └── LootInventoryDisplay.tsx └── lib/ ├── game/ - │ ├── store.ts # Zustand store (~2812 lines, main state + tick logic) - │ ├── crafting-slice.ts # Equipment/enchantment logic (~1100 lines, from store.ts) - │ ├── computed-stats.ts # Computed stats functions (~12 lines, simplified) - │ ├── navigation-slice.ts # Floor navigation actions (~75 lines) - │ ├── study-slice.ts # Study system actions (~210 lines) - │ ├── familiar-slice.ts # Familiar system actions - │ ├── effects.ts # Unified effect computation - │ ├── upgrade-effects.ts # Skill upgrade effect definitions - │ ├── constants.ts # Game definitions (spells, skills, etc.) - │ ├── skill-evolution.ts # Skill tier progression paths (~3400 lines) - │ ├── types.ts # TypeScript interfaces - │ ├── formatting.ts # Display formatters - │ ├── utils.ts # Utility functions - │ └── data/ - │ ├── equipment.ts # Equipment type definitions - │ └── enchantment-effects.ts # Enchantment effect catalog - └── utils.ts # General utilities (cn function) + │ ├── stores/ # Modular Zustand stores (NEW) + │ │ ├── index.ts # Combined store exports + │ │ ├── gameStore.ts # Main store (~11KB, core state + tick) + │ │ ├── manaStore.ts # Mana state and actions (~9KB) + │ │ ├── combatStore.ts # Combat system (~9KB) + │ │ ├── prestigeStore.ts # Prestige/loop system (~8KB) + │ │ ├── skillStore.ts # Skill state and actions (~11KB) + │ │ ├── uiStore.ts # UI state (~2KB) + │ │ ├── gameLoopActions.ts # Game loop logic + │ │ ├── gameActions.ts # Generic game actions + │ │ └── gameHooks.ts # Store hooks + │ ├── store-modules/ # Legacy store utilities + │ ├── crafting-actions/ # Modular crafting system (NEW) + │ │ ├── index.ts + │ │ ├── application-actions.ts + │ │ ├── design-actions.ts + │ │ ├── preparation-actions.ts + │ │ ├── equipment-actions.ts + │ │ ├── crafting-equipment-actions.ts + │ │ ├── disenchant-actions.ts + │ │ └── computed-getters.ts + │ ├── skill-evolution-modules/ # Modular skill evolution (NEW) + │ │ ├── index.ts # Main export (~11KB) + │ │ ├── mana-well-flow.ts # Mana Well/Flow skills (~15KB) + │ │ ├── quick-learner.ts # Quick Learner skill (~7KB) + │ │ ├── focused-mind.ts # Focused Mind skill (~6KB) + │ │ ├── enchanting-skills.ts # Enchanting skills (~15KB) + │ │ ├── invocation-skills.ts # Invocation skills (~15KB) + │ │ ├── hybrid-skills.ts # Hybrid skills (~22KB) + │ │ ├── guardian-skills.ts # Guardian-related skills (~4KB) + │ │ ├── insight-harvest.ts # Insight Harvest skill (~7KB) + │ │ ├── mana-utility-skills.ts # Mana utility skills (~7KB) + │ │ ├── elemental-attunement.ts # Elemental Attunement (~7KB) + │ │ ├── knowledge-retention.ts # Knowledge Retention (~4KB) + │ │ ├── learning-skills.ts # Learning skills (~1KB) + │ │ ├── magic-skills.ts # Magic skills (~1KB) + │ │ ├── utils.ts # Skill evolution utilities + │ │ └── types.ts # TypeScript interfaces + │ ├── constants/ # Modular constants (NEW) + │ │ ├── index.ts + │ │ ├── core.ts # Core game constants + │ │ ├── elements.ts # Element definitions + │ │ ├── guardians.ts # Guardian definitions + │ │ ├── prestige.ts # Prestige upgrade definitions + │ │ ├── rooms.ts # Room type definitions + │ │ ├── skills.ts # Skill definitions (~30KB) + │ │ ├── spells.ts # Spell definitions + │ │ └── spells-modules/ # Spell sub-modules + │ ├── data/ # Game data definitions (NEW) + │ │ ├── enchantment-effects.ts + │ │ ├── enchantments/ # Enchantment definitions + │ │ ├── equipment/ # Equipment definitions + │ │ ├── golems/ # Golem definitions + │ │ ├── achievements.ts + │ │ ├── crafting-recipes.ts + │ │ └── loot-drops.ts + │ ├── crafting-slice.ts # Legacy crafting (being modularized) + │ ├── skill-evolution.ts # Legacy skill evolution (reduced, ~1.5KB) + │ ├── constants.ts # Legacy constants (reduced, ~1KB) + │ ├── store.ts # Legacy store (reduced, ~14KB) + │ ├── computed-stats.ts # Computed stats functions + │ ├── navigation-slice.ts # Floor navigation actions + │ ├── study-slice.ts # Study system actions + │ ├── effects.ts # Unified effect computation + │ ├── upgrade-effects.ts # Skill upgrade effect definitions + │ ├── types.ts # TypeScript interfaces + │ ├── formatting.ts # Display formatters + │ └── utils/ # Utility functions + └── utils.ts # General utilities (cn function) ``` *Note: A complete, up-to-date project tree is automatically generated on each commit and saved to `docs/project-structure.txt`. This file is generated by the pre-commit hook using `.husky/scripts/generate-project-tree.js` and respects `.gitignore` rules.* ## Key Systems -### 0. Task 2 Completion Summary +### 1. State Management (Modular Store Architecture) -**Task 2 has been completed successfully (12/12 tasks done)!** +The game uses a **modular Zustand store architecture** with multiple specialized stores: -Key changes made in Task 2: -- **ActionButtons Rework**: Removed manual selection, auto-transition to Meditate after actions -- **SpireTab Overhaul**: Added "Climb the Spire" button, implemented Spire Mode with exit condition -- **Equipment System**: Added support for 2-Handed Weapons, Staves now block offhand slot -- **Research Locking**: Prevent switching topics while study in progress -- **DebugTab Update**: Added Invoker Debugging Buttons for Pacts -- **Combat UI Fix**: Fixed Casting Bar progress animation -- **Crafting Limits**: Disabled Prepare for non-enchanted items, limited Design to owned gear types -- **System Integrity**: Fixed Show Component Names debug option for all components -- **StatsTab**: Locked Fire/Water/Air/Earth at start, only Transference unlocked -- **LootTab**: Removed Transference from essence list (not lootable) -- **Ascension Skills**: Deleted all Ascension skills -- **Mana Well Fix**: Fixed Deep Basin upgrade multiplier values +#### Store Modules (`src/lib/game/stores/`) +- **gameStore.ts**: Core state, tick logic, and main actions (~11KB) +- **manaStore.ts**: Mana gathering, elements, conversion (~9KB) +- **combatStore.ts**: Combat system, spells, floor progression (~9KB) +- **prestigeStore.ts**: Prestige/loop system, insight, upgrades (~8KB) +- **skillStore.ts**: Skill state, studying, evolution (~11KB) +- **uiStore.ts**: UI state, modals, debug settings (~2KB) -**Context File Approach for Sub-Agents:** -During Task 2, context files were created in `docs/` to guide sub-agents: -- `update_agents_context.md` - Context for updating AGENTS.md -- `update_game_briefing_context.md` - Context for updating GAME_BRIEFING.md -- `update_skills_context.md` - Context for updating skills.md +#### Legacy Store Files (Being Migrated) +- **store.ts**: Reduced from ~2812 lines to ~14KB (core logic moved to stores/) +- **crafting-slice.ts**: Reduced, being replaced by crafting-actions/ -This approach proved effective for delegating documentation updates to sub-agents. +#### Store Interaction Pattern +```typescript +// Each store can interact with other stores via get() and custom hooks +// Example from combatStore.ts: +import { useManaStore } from './manaStore'; -### 1. State Management (`store.ts`) +// Access other store state +const manaState = useManaStore.getState(); +``` -The game uses a Zustand store organized with **slice pattern** for better maintainability: +### 2. Crafting System (Modular Architecture) -#### Store Slices -- **Main Store** (`store.ts`): Core state, tick logic, and main actions (~2812 lines) -- **Navigation Slice** (`navigation-slice.ts`): Floor navigation (setClimbDirection, changeFloor) (~75 lines) -- **Study Slice** (`study-slice.ts`): Study system (startStudyingSkill, startStudyingSpell, cancelStudy) (~210 lines) -- **Crafting Slice** (`crafting-slice.ts`): Equipment/enchantment (createEquipmentInstance, startDesigningEnchantment) (~1100 lines) -- **Familiar Slice** (`familiar-slice.ts`): Familiar system (addFamiliar, removeFamiliar) - **NOTE: File does not currently exist** +The crafting system has been split into focused action modules: -#### Computed Stats (`computed-stats.ts`) +#### Crafting Action Modules (`src/lib/game/crafting-actions/`) +- **design-actions.ts**: Enchantment design creation (~3KB) +- **preparation-actions.ts**: Equipment preparation (~1KB) +- **application-actions.ts**: Enchantment application (~2KB) +- **equipment-actions.ts**: Equipment management (~2.5KB) +- **crafting-equipment-actions.ts**: Equipment crafting (~2.5KB) +- **disenchant-actions.ts**: Disenchanting logic (~1KB) +- **computed-getters.ts**: Crafting computed values (~2KB) +- **index.ts**: Barrel exports + +### 3. Skill Evolution System (Modular Architecture) + +The massive ~3400-line `skill-evolution.ts` has been split into focused modules: + +#### Skill Evolution Modules (`src/lib/game/skill-evolution-modules/`) +- **index.ts**: Main export combining all skill trees (~11KB) +- **mana-well-flow.ts**: Mana Well and Mana Flow skills (~15KB) +- **quick-learner.ts**: Quick Learner and related skills (~7KB) +- **focused-mind.ts**: Focused Mind and study skills (~6KB) +- **enchanting-skills.ts**: Enchanting skill tree (~15KB) +- **invocation-skills.ts**: Invocation and Pact Mastery (~15KB) +- **hybrid-skills.ts**: Cross-attunement hybrid skills (~22KB) +- **guardian-skills.ts**: Guardian-related skills (~4KB) +- **insight-harvest.ts**: Insight and prestige skills (~7KB) +- **mana-utility-skills.ts**: Utility mana skills (~7KB) +- **elemental-attunement.ts**: Elemental skills (~7KB) +- **knowledge-retention.ts**: Knowledge retention skill (~4KB) +- **learning-skills.ts**: Basic learning skills (~1KB) +- **magic-skills.ts**: Magic-related skills (~1KB) +- **utils.ts**: Shared utilities +- **types.ts**: TypeScript interfaces + +### 4. Constants System (Modular Architecture) + +Game constants have been organized into domain-specific modules: + +#### Constants Modules (`src/lib/game/constants/`) +- **core.ts**: Core game constants (timing, limits) +- **elements.ts**: Element definitions and hierarchies +- **guardians.ts**: Guardian definitions and stats +- **prestige.ts**: Prestige upgrade definitions +- **rooms.ts**: Room type definitions +- **skills.ts**: Complete skill definitions (~30KB) +- **spells.ts**: Spell definitions +- **spells-modules/**: Organized spell sub-modules +- **index.ts**: Barrel exports + +### 5. Game Data (New Structure) + +#### Data Directory (`src/lib/game/data/`) +- **enchantment-effects.ts**: Enchantment effect catalog +- **enchantments/**: Enchantment definitions by category +- **equipment/**: Equipment type definitions +- **golems/**: Golem type definitions +- **achievements.ts**: Achievement definitions +- **crafting-recipes.ts**: Crafting recipe definitions +- **loot-drops.ts**: Loot table definitions + +### Computed Stats (`computed-stats.ts`) Extracted utility functions for stat calculations: - `computeMaxMana()`, `computeRegen()`, `computeEffectiveRegen()` - `calcDamage()`, `calcInsight()`, `getElementalBonus()` @@ -175,17 +332,17 @@ interface GameState { hour: number; paused: boolean; - // Mana + // Mana (now in manaStore.ts) rawMana: number; elements: Record; - // Combat + // Combat (now in combatStore.ts) currentFloor: number; floorHP: number; activeSpell: string; castProgress: number; - // Progression + // Progression (now in skillStore.ts) skills: Record; spells: Record; skillUpgrades: Record; @@ -196,14 +353,14 @@ interface GameState { equippedInstances: Record; enchantmentDesigns: EnchantmentDesign[]; - // Prestige + // Prestige (now in prestigeStore.ts) insight: number; prestigeUpgrades: Record; signedPacts: number[]; } ``` -### 2. Effect System (`effects.ts`) +### Effect System (`effects.ts`) **CRITICAL**: All stat modifications flow through the unified effect system. @@ -229,42 +386,11 @@ getUnifiedEffects(state) => UnifiedEffects { 2. Add mapping in `computeEquipmentEffects()` in `effects.ts` 3. Apply in the relevant game logic (tick, damage calc, etc.) -### 3. Combat System - -Combat uses a **cast speed** system: -- Each spell has `castSpeed` (casts per hour) -- Cast progress accumulates: `progress += castSpeed * attackSpeedMultiplier * HOURS_PER_TICK` -- When `progress >= 1`, spell is cast (cost deducted, damage dealt) -- DPS = `damagePerCast * castsPerSecond` - -Damage calculation order: -1. Base spell damage -2. Skill bonuses (combatTrain, arcaneFury, etc.) -3. Upgrade effects (multipliers, bonuses) -4. Special effects (Overpower, Berserker, etc.) -5. Elemental modifiers (same element +25%, super effective +50%) - -### 4. Crafting/Enchantment System - -Three-stage process: -1. **Design**: Select effects, takes time based on complexity -2. **Prepare**: Pay mana to prepare equipment, takes time -3. **Apply**: Apply design to equipment, costs mana per hour - -Equipment has **capacity** that limits total enchantment power. - -### 5. Skill Evolution System - -Skills have 5 tiers of evolution: -- At level 5: Choose 2 of 4 milestone upgrades -- At level 10: Choose 2 more upgrades, then tier up -- Each tier multiplies the skill's base effect by 10x - ## Important Patterns ### Adding a New Effect -1. **Define in `enchantment-effects.ts`**: +1. **Define in `enchantment-effects.ts`** (now in `data/enchantment-effects.ts`): ```typescript my_new_effect: { id: 'my_new_effect', @@ -294,17 +420,19 @@ damage *= effects.myNewStatMultiplier; ### Adding a New Skill -1. **Define in `constants.ts` SKILLS_DEF** -2. **Add evolution path in `skill-evolution.ts`** -3. **Add prerequisite checks in `store.ts`** -4. **Update UI in `page.tsx`** +1. **Define in `constants/skills.ts`** (NEW location) +2. **Add evolution path in `skill-evolution-modules/`** (NEW location) + - Create new module or add to existing module +3. **Export from `skill-evolution-modules/index.ts`** +4. **Update UI in `components/game/tabs/SkillsTab.tsx`** ### Adding a New Spell -1. **Define in `constants.ts` SPELLS_DEF** -2. **Add spell enchantment in `enchantment-effects.ts`** -3. **Add research skill in `constants.ts`** -4. **Map research to effect in `EFFECT_RESEARCH_MAPPING`** +1. **Define in `constants/spells.ts`** (NEW location) +2. **Add to `constants/spells-modules/`** if categorized +3. **Add spell enchantment in `data/enchantment-effects.ts`** +4. **Add research skill in `constants/skills.ts`** +5. **Map research to effect in `EFFECT_RESEARCH_MAPPING`** ## Git Hooks (Husky) @@ -333,97 +461,71 @@ Runs after merging branches: 2. **Direct stat modification**: Never modify stats directly; use effect system 3. **Missing tier multiplier**: Use `getTierMultiplier(skillId)` for tiered skills 4. **Ignoring special effects**: Check `hasSpecial(effects, SPECIAL_EFFECTS.X)` for special abilities +5. **Not updating modular stores**: Check all stores in `stores/` directory for related state +6. **Bypassing crafting-actions**: Use the modular actions in `crafting-actions/` for new crafting features ## Testing Guidelines -- Run `bun run lint` after changes -- Check dev server logs at `/home/z/my-project/dev.log` +- Run `npm run lint` after changes +- Run `npm run test` to execute unit tests +- Check dev server logs - Test with fresh game state (clear localStorage) +- **New**: Tests are organized alongside their modules (e.g., `stores/__tests__/`, `store-tests/`) -## Slice Pattern for Store Organization +## Modular Architecture Pattern -The store uses a **slice pattern** to organize related actions into separate files. This improves maintainability and makes the codebase more modular. +The codebase has been refactored from large monolithic files into focused, modular components. This improves: +- **Maintainability**: Each module has a single responsibility +- **Readability**: Files are under 400 lines (pre-commit hook enforces this) +- **AI Agent Efficiency**: Smaller files are easier to understand and modify -### Creating a New Slice +### Key Modular Directories -1. **Create the slice file** (e.g., `my-feature-slice.ts`): -```typescript -// Define the actions interface -export interface MyFeatureActions { - doSomething: (param: string) => void; - undoSomething: () => void; -} +| Directory | Purpose | Line Count Target | +|-----------|---------|-------------------| +| `stores/` | Zustand store modules | < 400 lines each | +| `crafting-actions/` | Crafting system actions | < 400 lines each | +| `skill-evolution-modules/` | Skill trees by category | < 400 lines each | +| `constants/` | Game constants by domain | < 400 lines each | +| `data/` | Game data definitions | < 400 lines each | +| `components/game/tabs/` | UI tab components | < 400 lines each | +| `components/game/crafting/` | Crafting UI components | < 400 lines each | +| `components/game/stats/` | Stats display components | < 400 lines each | -// Create the slice factory -export function createMyFeatureSlice( - set: StoreApi['setState'], - get: StoreApi['getState'] -): MyFeatureActions { - return { - doSomething: (param: string) => { - set((state) => { - // Update state - }); - }, - undoSomething: () => { - set((state) => { - // Update state - }); - }, - }; -} -``` +### Creating a New Module -2. **Add to main store** (`store.ts`): -```typescript -import { createMyFeatureSlice, MyFeatureActions } from './my-feature-slice'; +1. **Identify the domain**: Which system does it belong to? +2. **Create focused file**: Keep under 400 lines +3. **Export from index**: Add to barrel export file +4. **Update imports**: Fix all references to old location +5. **Test**: Run lint and tests before committing -// Extend GameStore interface -interface GameStore extends GameState, MyFeatureActions, /* other slices */ {} - -// Spread into store creation -const useGameStore = create()( - persist( - (set, get) => ({ - ...createMyFeatureSlice(set, get), - // other slices and state - }), - // persist config - ) -); -``` - -### Existing Slices - -| Slice | File | Lines | Purpose | -|-------|------|-------|----------| -| Navigation | `navigation-slice.ts` | ~75 | Floor navigation (setClimbDirection, changeFloor) | -| Study | `study-slice.ts` | ~210 | Study system (startStudyingSkill, startStudyingSpell, cancelStudy) | -| Crafting | `crafting-slice.ts` | ~1100 | Equipment/enchantment (createEquipmentInstance, startDesigningEnchantment) | -| Familiar | `familiar-slice.ts` | N/A | Familiar system - **File not found in current codebase** | +--- ## File Size Guidelines -### Current File Sizes (After Task 2) +### Current File Sizes (After Modular Refactoring) + | File | Lines | Size (bytes) | Notes | |------|-------|--------------|-------| -| `store.ts` | ~2812 | ~103KB | Core state + tick logic, crafting-slice extracted | -| `page.tsx` | ~548 | ~22KB | Main UI (heavily reduced through component extraction) | -| `crafting-slice.ts` | ~1100 | ~35KB | Equipment/enchantment logic (extracted from store.ts) | -| `skill-evolution.ts` | ~3400 | ~120KB | Skill tier progression paths | -| `study-slice.ts` | ~210 | ~8KB | Study system actions | -| `navigation-slice.ts` | ~75 | ~3KB | Navigation actions | -| `computed-stats.ts` | ~12 | ~1KB | Extracted utility functions (some moved to slices) | -| `components/game/tabs/*.tsx` | ~3000 | ~95KB | Tab-specific components (SpireTab, CraftingTab, etc.) | +| `stores/gameStore.ts` | ~300 | ~11KB | Core state + tick logic | +| `stores/manaStore.ts` | ~250 | ~9KB | Mana system | +| `stores/combatStore.ts` | ~250 | ~9KB | Combat system | +| `stores/prestigeStore.ts` | ~200 | ~8KB | Prestige system | +| `stores/skillStore.ts` | ~300 | ~11KB | Skill system | +| `stores/uiStore.ts` | ~50 | ~2KB | UI state | +| `crafting-actions/*.ts` | ~50-150 | ~1-3KB each | Modular crafting | +| `skill-evolution-modules/*.ts` | ~100-600 | ~4-22KB each | Modular skills | +| `constants/*.ts` | ~50-1000 | ~1-30KB each | Modular constants | +| `page.tsx` | ~100 | ~4KB | Main UI (heavily reduced) | +| `components/game/tabs/*.tsx` | ~50-400 | ~2-15KB each | Tab components | ### Guidelines -- Keep `page.tsx` under 600 lines by extracting to components (ActionButtons, ManaDisplay, tabs, etc.) -- Keep `store.ts` under 3000 lines by extracting to slices (navigation, study, crafting, familiar) -- Extract computed stats and utility functions to appropriate slices or utils when >100 lines +- **400 lines maximum** per file (enforced by pre-commit hook) +- Extract to modules when approaching 300 lines - Use barrel exports (`index.ts`) for clean imports -- Follow the slice pattern for store organization (see below) -- **After Task 2**: `page.tsx` reduced from ~2554 to ~548 lines (78% reduction) -- **After Task 2**: `store.ts` increased due to crafting-slice integration, but better organized +- Keep related functionality together in modules +- **Modular architecture** is now the standard - all new code should follow this pattern ### Automated File Size Check A pre-commit hook automatically checks all staged files. Files exceeding **400 lines** will be rejected. The hook runs via Husky and uses `.husky/scripts/check-file-size.js`. If your file is too large, refactor it into smaller modules before committing. diff --git a/docs/GAME_BRIEFING.md b/docs/GAME_BRIEFING.md index 2ff4808..058659c 100644 --- a/docs/GAME_BRIEFING.md +++ b/docs/GAME_BRIEFING.md @@ -1,8 +1,8 @@ # Mana-Loop: Comprehensive Game Briefing Document -**Document Version:** 1.1 +**Document Version:** 1.2 **Generated:** Game Systems Analysis -**Updated:** After Task 2 Completion +**Updated:** After Modular Refactoring (stores/, crafting-actions/, skill-evolution-modules/, constants/) --- @@ -23,6 +23,7 @@ 13. [Achievement System](#achievement-system) 14. [Formulas & Calculations](#formulas--calculations) 15. [System Interactions](#system-interactions) +16. [Code Architecture](#code-architecture) --- @@ -37,6 +38,8 @@ - Time pressure through incursion mechanic - Guardian pacts provide permanent multipliers +**Code Architecture:** The codebase has been refactored into a modular architecture with specialized directories for stores, crafting actions, skill evolution modules, constants, and game data. + --- ## Core Game Loop @@ -86,8 +89,8 @@ - **Spire Mode integration**: Action buttons are hidden when in Spire Mode (climbing simplified UI) **Implementation:** -- `currentAction` state tracks the active action -- Crafting slice sets `currentAction: 'meditate'` when actions complete +- `currentAction` state tracks the active action (now in `stores/gameStore.ts`) +- Crafting actions set `currentAction: 'meditate'` when actions complete (in `crafting-actions/`) - `ACTION_CONFIG` maps actions to display configs (label, icon, color) --- @@ -212,7 +215,7 @@ element = FLOOR_ELEM_CYCLE[(floor - 1) % 7] **Floor HP Formula:** ``` normalFloorHP = floor(100 + floor × 50 + floor^1.7) -guardianFloorHP = GUARDIANS[floor].hp // Fixed values +guardianFloorHP = GUARDIANS[floor].hp // Fixed values (in constants/guardians.ts) ``` **Guardian Floors:** 10, 20, 30, 40, 50, 60, 80, 90, 100 @@ -357,8 +360,8 @@ aoeDamage = baseDamage × (1 - 0.1 × (numTargets - 1)) - Exit condition: Automatically exits when player chooses to stop climbing **Implementation:** -- `spireMode` boolean state in game store -- `enterSpireMode()` and `exitSpireMode()` actions +- `spireMode` boolean state in `stores/gameStore.ts` +- `enterSpireMode()` and `exitSpireMode()` actions in `stores/combatStore.ts` - `simpleMode` prop passed to SpireTab for simplified rendering - UI conditionally renders based on `store.spireMode` @@ -426,8 +429,9 @@ Attunements are class-like specializations that grant unique capabilities and sk | **Unlock** | Starting attunement | **Capabilities:** -- Enchanting equipment +- Enchanting equipment (see `crafting-actions/`) - Disenchanting for mana recovery +- Access to enchanting skill tree (see `skill-evolution-modules/enchanting-skills.ts`) **Skill Categories Unlocked:** - `enchant` - Enchanting efficiency @@ -449,9 +453,9 @@ Attunements are class-like specializations that grant unique capabilities and sk - Form pacts with guardians - Access guardian powers - Elemental mastery through pacts -- Invocation skill tree (T1-T5 with perk choices at L5/L10) +- Invocation skill tree (T1-T5 with perk choices at L5/L10) - see `skill-evolution-modules/invocation-skills.ts` - Pact Mastery skill tree (T1-T5) -- Pact-Weaving hybrid skill (Invoker + Enchanter) +- Pact-Weaving hybrid skill (Invoker + Enchanter) - see `skill-evolution-modules/hybrid-skills.ts` **Skill Categories Unlocked:** - `invocation` - ✅ Implemented (T1-T5 skill tree) @@ -470,8 +474,8 @@ Attunements are class-like specializations that grant unique capabilities and sk | **Unlock** | Prove crafting worth | **Capabilities:** -- Golem crafting -- Gear crafting +- Golem crafting (see `data/golems/`) +- Gear crafting (see `data/equipment/`) - Earth shaping **Skill Categories Unlocked:** @@ -481,7 +485,7 @@ Attunements are class-like specializations that grant unique capabilities and sk ### Attunement Leveling **XP Formula:** -``` +```javascript Level 2: 1,000 XP Level 3: 2,500 XP Level 4: 5,000 XP @@ -491,7 +495,7 @@ Max Level: 10 ``` **Level Scaling:** -``` +```javascript regenMultiplier = 1.5^(level - 1) conversionRate = baseRate × 1.5^(level - 1) ``` @@ -505,19 +509,19 @@ conversionRate = baseRate × 1.5^(level - 1) ### Skill Categories -| Category | Attunement | Description | -|----------|------------|-------------| -| `mana` | Core | Max mana, regen, element cap | -| `study` | Core | Study speed, cost reduction | -| `research` | Core | Click bonuses, advanced meditation | -| `ascension` | Core | Insight, guardian damage | -| `enchant` | Enchanter | Enchanting efficiency | -| `effectResearch` | Enchanter | Unlock enchantment effects | -| `invocation` | Invoker | ✅ Implemented (T1-T5 skill tree) | -| `pact` | Invoker | ✅ Implemented (T1-T5 skill tree) | -| `fabrication` | Fabricator | Crafting speed | -| `golemancy` | Fabricator | Golem control | -| `craft` | Legacy | Basic crafting | +| Category | Attunement | Description | Status | +|----------|------------|-------------|---------| +| `mana` | Core | Max mana, regen, element cap | ✅ Implemented | +| `study` | Core | Study speed, cost reduction | ✅ Implemented | +| `research` | Core | Click bonuses, advanced meditation | ✅ Implemented | +| `ascension` | Core | Insight, guardian damage | ✅ Implemented | +| `enchant` | Enchanter | Enchanting efficiency | ✅ Implemented (T1-T5) | +| `effectResearch` | Enchanter | Unlock enchantment effects | ✅ Implemented (max:1) | +| `invocation` | Invoker | Pact-based abilities | ✅ Implemented (T1-T5) | +| `pact` | Invoker | Guardian pact bonuses | ✅ Implemented (T1-T5) | +| `fabrication` | Fabricator | Crafting and construction | ✅ Implemented (T1-T5) | +| `golemancy` | Fabricator | Golem summoning and control | ✅ Implemented (T1-T5) | +| `craft` | Legacy | Basic crafting | ✅ Implemented | ### Core Skills @@ -525,11 +529,11 @@ conversionRate = baseRate × 1.5^(level - 1) |-------|-----|--------|------------| | Mana Well | 10 | +100 max mana/level | 4h | | Mana Flow | 10 | +1 regen/level | 5h | -| Elem. Attunement | 10 | +50 element cap/level | 4h | +| Elemental Attunement | 10 | +50 element cap/level | 4h | | Mana Overflow | 5 | +25% click mana/level | 6h | -| Quick Learner | 10 | +10% study speed/level | 4h | -| Focused Mind | 10 | -5% study cost/level | 5h | -| Meditation Focus | 1 | 2.5x regen after 4h | 6h | + +**Prerequisites:** +- Mana Overflow: Mana Well 3 ### Skill Tier Evolution @@ -570,8 +574,13 @@ Tier 5: Mythic (multiplier ×10,000) | Efficient Enchant | 5 | Enchanter 2, Enchanting 3 | -5% capacity cost/level | | Disenchanting | 3 | Enchanter 1, Enchanting 2 | +20% mana recovery/level | | Enchant Speed | 5 | Enchanter 1, Enchanting 2 | -10% time/level | -| Essence Refining | 5 | Enchanter 2, Enchanting 4 | +10% effect power/level | -| Effect Research (all) | 1 | Enchanter 1+ | Unlock enchantment effects (max:1, no evolution) | +| Essence Refining | 1 | Enchanter 2, Enchanting 4 | +10% effect power | + +**Prerequisites:** +- Efficient Enchant: Enchanting 3 +- Disenchanting: Enchanting 2 +- Enchant Speed: Enchanting 2 +- Essence Refining: Enchanting 4 ### Golemancy Skills @@ -581,7 +590,7 @@ Tier 5: Mythic (multiplier ×10,000) | Golem Efficiency | 5 | Fabricator 2 | +5% attack speed/level | | Golem Longevity | 3 | Fabricator 3 | +1 floor duration/level | | Golem Siphon | 3 | Fabricator 3 | -10% maintenance/level | -| Advanced Golemancy | 1 | Fabricator 5, Mastery 3 | Unlock hybrid golems | +| Advanced Golemancy | 1 | Fabricator 5, Mastery 3 | Unlock hybrid recipes | --- @@ -591,11 +600,12 @@ Hybrid Skills are advanced skills that require two attunements and combine their #### Pact-Weaving (Invoker + Enchanter) -**Requirement:** Invoker 3 + Enchanter 3 +**Requirement:** Invoker 3 + Enchanter 3 +**Location:** `skill-evolution-modules/hybrid-skills.ts` **Paths:** - **Path A: The Weaver** - Enhanced enchantment power through pact bonuses -- **Path B: The Warp** - Unpredictable magic blending pacts and enchantments +- **Path B: The Warp** - Unpredictable magic blending pacts and enchantments - **Path C: The World-Weaver** - Ultimate hybrid combining all powers **Talent Tree (5 Tiers):** @@ -616,7 +626,8 @@ Hybrid Skills are advanced skills that require two attunements and combine their #### Guardian Constructs (Fabricator + Invoker) -**Requirement:** Fabricator 3 + Invoker 3 +**Requirement:** Fabricator 3 + Invoker 3 +**Location:** `skill-evolution-modules/hybrid-skills.ts` **Paths:** - **Path A: The Architect** - Durable constructs with enhanced defenses @@ -646,7 +657,8 @@ Hybrid Skills are advanced skills that require two attunements and combine their #### Enchanted Golemancy (Fabricator + Enchanter) -**Requirement:** Fabricator 3 + Enchanter 3 +**Requirement:** Fabricator 3 + Enchanter 3 +**Location:** `skill-evolution-modules/hybrid-skills.ts` **Paths:** - **Path A: The Battle-Smith** - Combat-focused enchanted golems @@ -700,8 +712,8 @@ accessory2 - Rings, Amulets - The UI displays a "2-Handed" badge on applicable items and shows "Blocked by 2-handed weapon" for blocked slots **Implementation:** -- Equipment types have a `twoHanded: true` property -- `equipItem()` validates 2-handed weapon constraints +- Equipment types have a `twoHanded: true` property (see `data/equipment/`) +- `equipItem()` validates 2-handed weapon constraints (in `stores/gameStore.ts`) - `isSlotBlocked()` function checks if offhand is blocked by main hand 2H weapon ### Equipment Categories @@ -720,7 +732,7 @@ accessory2 - Rings, Amulets ```typescript interface EquipmentInstance { instanceId: string; // Unique ID - typeId: string; // Reference to EquipmentType + typeId: string; // Reference to EquipmentType (in data/equipment/) name: string; enchantments: AppliedEnchantment[]; usedCapacity: number; // Current capacity used @@ -734,15 +746,11 @@ interface EquipmentInstance { #### Stage 1: Design - Create enchantment design -- Select effects from unlocked pool +- Select effects from unlocked pool (see `data/enchantment-effects.ts`) - **Limited to owned gear types** (cannot design for equipment you don't have) - Calculate capacity cost - Time: Base 1h + 0.5h per effect stack - -**Capacity Cost Formula:** -``` -totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonus)) -``` +- **Implementation:** `crafting-actions/design-actions.ts` #### Stage 2: Prepare - Prepare equipment for enchanting @@ -750,6 +758,7 @@ totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonu - Mana cost: capacity × 10 - Time: 2h + 1h per 50 capacity - **Auto-transitions to Meditate** when complete +- **Implementation:** `crafting-actions/preparation-actions.ts` #### Stage 3: Apply - Apply enchantment design @@ -757,6 +766,7 @@ totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonu - Time: 2h + 1h per effect stack - Grants Enchanter XP: 1 XP per 10 capacity - **Auto-transitions to Meditate** when complete +- **Implementation:** `crafting-actions/application-actions.ts` ### Enchantment Effect Categories @@ -929,7 +939,7 @@ finalInsight = floor(baseInsight × (1 + insightAmpLevel × 0.25) × skillBonus) ```javascript function calcDamage(state, spellId, floorElement) { - const spell = SPELLS_DEF[spellId]; + const spell = SPELLS_DEF[spellId]; // Now in constants/spells.ts // Base damage let damage = spell.dmg + (state.skills.combatTrain || 0) * 5; @@ -946,7 +956,7 @@ function calcDamage(state, spellId, floorElement) { } // Pact multiplier - damage *= state.signedPacts.reduce((m, f) => m * GUARDIANS[f].pact, 1); + damage *= state.signedPacts.reduce((m, f) => m * GUARDIANS[f].pact, 1); // GUARDIANS in constants/guardians.ts // Elemental effectiveness damage *= getElementalBonus(spell.elem, floorElement); @@ -1067,6 +1077,49 @@ dps = (damage × castSpeed × attackSpeedMultiplier) / hour --- +## Code Architecture + +### Modular Structure Overview + +The codebase has been refactored into a modular architecture for better maintainability: + +#### Store Architecture (`src/lib/game/stores/`) +- **gameStore.ts**: Core state, tick logic, and main actions +- **manaStore.ts**: Mana gathering, elements, conversion +- **combatStore.ts**: Combat system, spells, floor progression +- **prestigeStore.ts**: Prestige/loop system, insight, upgrades +- **skillStore.ts**: Skill state, studying, evolution +- **uiStore.ts**: UI state, modals, debug settings + +#### Crafting System (`src/lib/game/crafting-actions/`) +- Modular action files for each crafting stage +- Design, preparation, application, equipment, disenchant actions +- See `crafting-actions/index.ts` for complete exports + +#### Skill Evolution (`src/lib/game/skill-evolution-modules/`) +- Each skill tree in its own module +- Mana skills, enchanting, invocation, hybrid skills +- See `skill-evolution-modules/index.ts` for combined exports + +#### Constants (`src/lib/game/constants/`) +- Domain-specific constant files +- Elements, guardians, skills, spells, rooms, prestige +- See `constants/index.ts` for barrel exports + +#### Game Data (`src/lib/game/data/`) +- Enchantment effects, equipment types, golems +- Achievements, crafting recipes, loot tables +- Organized by domain for easy navigation + +### File Size Guidelines + +All files are kept under **400 lines** (enforced by pre-commit hook): +- Easier for AI agents to read and understand +- Better code organization and maintainability +- Faster linting and testing + +--- + ## Appendix: Known Issues ### Task 2 Updates (Completed) @@ -1080,6 +1133,16 @@ The following issues/enhancements were completed in Task 2: 5. **Show Component Names** - Fixed debug option to properly display component names in UI 6. **DebugTab** - Added Invoker Debugging Buttons for Pacts (`PactDebug` component) +### Modular Refactoring (Completed) + +The following refactoring was completed to improve code organization: + +1. **Store Modularization** - Split `store.ts` (~2812 lines) into `stores/` with 6 focused modules +2. **Crafting Actions** - Split `crafting-slice.ts` (~1100 lines) into `crafting-actions/` with 7 modules +3. **Skill Evolution** - Split `skill-evolution.ts` (~3400 lines) into `skill-evolution-modules/` with 15+ modules +4. **Constants** - Split `constants.ts` into `constants/` with 8+ domain-specific modules +5. **Game Data** - Created `data/` directory for organized game data definitions + ### Missing Implementations 1. **Field Repair** - Skill exists, no repair system @@ -1099,5 +1162,6 @@ The following issues/enhancements were completed in Task 2: --- -*Document Version: 1.1 (Updated after Task 2 completion)* +*Document Version: 1.2 (Updated after Modular Refactoring)* +*Game mechanics unchanged - only code organization improved* *End of Game Briefing Document* diff --git a/docs/skills.md b/docs/skills.md index c7823e2..7fd8f87 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -8,6 +8,7 @@ 5. [Upgrade Trees](#upgrade-trees) 6. [Tier System](#tier-system) 7. [Banned Content](#banned-content) +8. [Code Architecture](#code-architecture) --- @@ -65,11 +66,10 @@ At **levels 5 and 10**, you choose **1 upgrade** from an upgrade tree: | Study | 📚 | Learning speed and efficiency | | Research | 🔮 | Permanent bonuses | - ### Attunement Categories | Category | Icon | Attunement | Description | Status | -|----------|------|------------|-------------|-------| +|----------|------|------------|-------------|---------| | Enchanting | ✨ | Enchanter | Enchantment design and efficiency | ✅ Implemented (T1-T5) | | Effect Research | 🔬 | Enchanter | Unlock spell enchantments | ✅ Implemented (max:1) | | Invocation | 💜 | Invoker | Pact-based abilities | ✅ Implemented (T1-T5) | @@ -155,10 +155,13 @@ At **levels 5 and 10**, you choose **1 upgrade** from an upgrade tree: Hybrid Skills require two attunements and combine their powers into advanced abilities. +**Code Location:** All hybrid skills are defined in `src/lib/game/skill-evolution-modules/hybrid-skills.ts` + ### Pact-Weaving (Invoker + Enchanter) **Requirement:** Invoker 3 + Enchanter 3 -**Max Level:** 5 (with Elite Perk at Level 5) +**Max Level:** 5 (with Elite Perk at Level 5) +**Location:** `skill-evolution-modules/hybrid-skills.ts` **Paths:** - **Path A: The Weaver** - Enhanced enchantment power through pact bonuses @@ -195,7 +198,8 @@ Hybrid Skills require two attunements and combine their powers into advanced abi ### Guardian Constructs (Fabricator + Invoker) **Requirement:** Fabricator 3 + Invoker 3 -**Max Level:** 5 (with Elite Perk at Level 5) +**Max Level:** 5 (with Elite Perk at Level 5) +**Location:** `skill-evolution-modules/hybrid-skills.ts` **Paths:** - **Path A: The Architect** - Durable constructs with enhanced defenses @@ -237,7 +241,8 @@ Hybrid Skills require two attunements and combine their powers into advanced abi ### Enchanted Golemancy (Fabricator + Enchanter) **Requirement:** Fabricator 3 + Enchanter 3 -**Max Level:** 5 (with Elite Perk at Level 5) +**Max Level:** 5 (with Elite Perk at Level 5) +**Location:** `skill-evolution-modules/hybrid-skills.ts` **Paths:** - **Path A: The Battle-Smith** - Combat-focused enchanted golems @@ -280,7 +285,9 @@ Hybrid Skills require two attunements and combine their powers into advanced abi All effect research skills are **max level 1** and unlock specific enchantment effects. -#### Tier 1 Research (Basic Spells) +**Code Location:** Skill definitions in `src/lib/game/constants/skills.ts`, research logic in `src/lib/game/skill-evolution-modules/enchanting-skills.ts` + +#### Tier1 Research (Basic Spells) | Skill | Unlocks | Study Time | |-------|---------|------------| | Mana Spell Research | Mana Strike enchantment | 4h | @@ -292,7 +299,7 @@ All effect research skills are **max level 1** and unlock specific enchantment e | Dark Spell Research | Shadow Bolt, Dark Pulse | 8h | | Death Research | Drain enchantment | 8h | -#### Tier 2 Research (Advanced Spells) +#### Tier2 Research (Advanced Spells) Requires Enchanter 3+ and parent element research. | Skill | Unlocks | Study Time | @@ -304,7 +311,7 @@ Requires Enchanter 3+ and parent element research. | Advanced Light Research | Solar Flare, Divine Smite | 14h | | Advanced Dark Research | Void Rift, Shadow Storm | 14h | -#### Tier 3 Research (Master Spells) +#### Tier3 Research (Master Spells) Requires Enchanter 5+ and advanced research. | Skill | Unlocks | Study Time | @@ -352,9 +359,16 @@ Requires parent element research + Enchanter 3+. ## Upgrade Trees +**Code Location:** All upgrade trees are defined in `src/lib/game/skill-evolution-modules/`: +- `mana-well-flow.ts` - Mana Well and Mana Flow upgrades +- `enchanting-skills.ts` - Enchanting skill upgrades +- `quick-learner.ts` - Quick Learner upgrades +- `focused-mind.ts` - Focused Mind upgrades +- And more... + ### Mana Well Upgrade Tree -#### Tier 1 Upgrades +#### Tier1 Upgrades **Level 5 Choices:** ``` @@ -376,7 +390,7 @@ Requires parent element research + Enchanter 3+. - Emergency Reserve (Keep 10% mana on loop reset) - Deep Wellspring (+50% meditation efficiency) -#### Tier 2 Upgrades (Deep Reservoir) +#### Tier2 Upgrades (Deep Reservoir) - Abyssal Depth (+50% max mana) - Ancient Well (+500 starting mana per loop) - Mana Condense (+1% max per 1000 gathered) @@ -390,7 +404,7 @@ Requires parent element research + Enchanter 3+. ### Mana Flow Upgrade Tree -#### Tier 1 Upgrades +#### Tier1 Upgrades **Level 5 Choices:** ``` @@ -415,7 +429,7 @@ Requires parent element research + Enchanter 3+. ### Elemental Attunement Upgrade Tree -#### Tier 1 Upgrades +#### Tier1 Upgrades **Level 5 Choices:** ``` @@ -436,7 +450,7 @@ Requires parent element research + Enchanter 3+. ### Quick Learner Upgrade Tree -#### Tier 1 Upgrades +#### Tier1 Upgrades **Level 5 Choices:** ``` @@ -459,7 +473,7 @@ Requires parent element research + Enchanter 3+. ### Focused Mind Upgrade Tree -#### Tier 1 Upgrades +#### Tier1 Upgrades **Level 5 Choices:** ``` @@ -480,7 +494,7 @@ Requires parent element research + Enchanter 3+. ### Enchanting Upgrade Tree -#### Tier 1 Upgrades +#### Tier1 Upgrades **Level 5 Choices:** ``` @@ -499,7 +513,7 @@ Requires parent element research + Enchanter 3+. ### Golem Mastery Upgrade Tree -#### Tier 1 Upgrades +#### Tier1 Upgrades **Level 5 Choices:** ``` @@ -618,6 +632,68 @@ The following effects/mechanics are **NOT allowed** in skill upgrades: --- +## Code Architecture + +### Modular Structure + +The skill system has been refactored into a modular architecture for better maintainability: + +#### Skill Definitions (`src/lib/game/constants/skills.ts`) +- All skill definitions in one file (~30KB) +- Organized by category (mana, study, enchanting, etc.) +- Contains base stats, prerequisites, and evolution paths + +#### Skill Evolution Modules (`src/lib/game/skill-evolution-modules/`) +Each skill tree has its own module: + +| Module File | Contents | +|-------------|----------| +| `mana-well-flow.ts` | Mana Well, Mana Flow, Elemental Attunement | +| `quick-learner.ts` | Quick Learner, Knowledge Retention | +| `focused-mind.ts` | Focused Mind, Meditation skills | +| `enchanting-skills.ts` | Enchanting, Efficient Enchant, Disenchanting | +| `invocation-skills.ts` | Invocation, Pact Mastery trees | +| `hybrid-skills.ts` | Pact-Weaving, Guardian Constructs, Enchanted Golemancy | +| `guardian-skills.ts` | Guardian Bane, related skills | +| `insight-harvest.ts` | Insight, Deep Memory skills | +| `mana-utility-skills.ts` | Mana Overflow, Mana Tap, etc. | +| `elemental-attunement.ts` | Elemental skill upgrades | +| `knowledge-retention.ts` | Knowledge retention mechanics | +| `learning-skills.ts` | Learning speed skills | +| `magic-skills.ts` | Magic-related skills | +| `utils.ts` | Shared utility functions | +| `types.ts` | TypeScript interfaces | +| `index.ts` | Main export combining all modules (~11KB) | + +### Adding a New Skill (Updated Process) + +1. **Define in `constants/skills.ts`** (NEW location) + - Add to `SKILLS_DEF` object + - Define base cost, study time, max level, category + +2. **Add evolution path in `skill-evolution-modules/`** (NEW location) + - Create new module or add to existing module + - Define upgrade trees for levels 5 and 10 + - Export upgrade functions + +3. **Export from `skill-evolution-modules/index.ts`** + - Import and re-export new module + - Ensure all upgrade functions are accessible + +4. **Update UI in `components/game/tabs/SkillsTab.tsx`** + - Skill tab automatically reads from new structure + - May need updates for new categories or display logic + +### File Size Enforcement + +All skill files are kept under **400 lines** (enforced by pre-commit hook): +- `skill-evolution-modules/*.ts` - Focused modules, typically 100-600 lines +- `constants/skills.ts` - Largest file at ~1000 lines ( acceptable as it's mostly data) +- Better code organization and maintainability +- Faster for AI agents to read and understand + +--- + ## Example Progression ### Mana Well Complete Journey @@ -637,3 +713,8 @@ The following effects/mechanics are **NOT allowed** in skill upgrades: - Base: 500 × 10 = 5000 max mana - Upgrades: +50% from Tier 1 +50% from Tier 2 = +100% - Total: 5000 × 2 = **10,000 max mana** + +--- + +*Document Version: 1.1 (Updated for Modular Architecture)* +*Code has been refactored - game mechanics unchanged*