Anexim/Mana-Loop
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update AGENTS.md, GAME_BRIEFING.md, and skills.md after refactoring
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 1m53s
Details

Browse Source
This commit is contained in:
Refactoring Agent
2026-05-02 19:59:33 +02:00
parent d5cbc9faff
commit 40d310b55a
3 changed files with 501 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+290 -188
View File
@@ -32,14 +32,14 @@ git config --global user.email "zhipu@local.local"
1. **Pull the latest changes:** 1. **Pull the latest changes:**
```bash ```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 2. **Do your task** - Make all necessary code changes
3. **Before finishing, commit and push:** 3. **Before finishing, commit and push:**
```bash ```bash
cd /home/z/my-project cd /home/user/repos/Mana-Loop
git add -A git add -A
git commit -m "descriptive message about changes" git commit -m "descriptive message about changes"
git push origin master git push origin master
@@ -59,7 +59,7 @@ git config --global user.email "zhipu@local.local"
- **Framework**: Next.js 16 with App Router - **Framework**: Next.js 16 with App Router
- **Language**: TypeScript 5 - **Language**: TypeScript 5
- **Styling**: Tailwind CSS 4 with shadcn/ui components - **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) - **Database**: Prisma ORM with SQLite (for persistence features)
## Core Game Loop ## Core Game Loop
@@ -75,93 +75,250 @@ git config --global user.email "zhipu@local.local"
``` ```
src/ src/
├── app/ ├── 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 │ ├── 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/ ├── components/
│ ├── ui/ # shadcn/ui components (auto-generated) │ ├── ui/ # shadcn/ui components (auto-generated)
│ └── game/ │ └── game/ # All game components (modular structure)
│ ├── index.ts # Barrel exports │ ├── index.ts # Barrel exports
│ ├── ActionButtons.tsx # Current action display with progress indicator │ ├── GameContext.tsx
│ ├── CalendarDisplay.tsx # Day calendar with incursion indicators │ ├── ActionButtons.tsx
│ ├── CraftingProgress.tsx # Design/preparation/application progress bars │ ├── CalendarDisplay.tsx
│ ├── StudyProgress.tsx # Current study progress with cancel button │ ├── CraftingProgress.tsx
│ ├── ManaDisplay.tsx # Mana/gathering section with progress bar │ ├── ManaDisplay.tsx
│ ├── TimeDisplay.tsx # Day/hour display with pause toggle │ ├── TimeDisplay.tsx
│ └── tabs/ # Tab-specific components (Task 2: all tabs refactored) │ ├── tabs/ # Tab-specific components
│ ├── index.ts # Tab component exports │ │ ├── index.ts
│ ├── CraftingTab.tsx # Enchantment crafting UI (~164 lines) │ │ ├── AchievementsTab.tsx
│ ├── LabTab.tsx # Skill upgrade and lab features │ │ ├── AttunementsTab.tsx
│ ├── SpellsTab.tsx # Spell management and equipment spells │ │ ├── CraftingTab.tsx
│ ├── SpireTab.tsx # Combat with Spire Mode (~354 lines, Task 2 overhaul) │ │ ├── DebugTab.tsx
│ ├── StatsTab.tsx # Player statistics (~251 lines, Task 2: elements locked) │ │ ├── EquipmentTab.tsx
│ ├── SkillsTab.tsx # Skill tree display (~371 lines, Task 2: Ascension deleted) │ │ ├── GolemancyTab.tsx
│ ├── EquipmentTab.tsx # Gear management (~435 lines) │ │ ├── LabTab.tsx
│ ├── DebugTab.tsx # Debug tools (~34 lines, Task 2: added Pact buttons) │ │ ├── LootTab.tsx
│ └── LootTab.tsx # Loot display (~48 lines, Task 2: Transference removed) │ │ ├── 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/ └── lib/
├── game/ ├── game/
│ ├── store.ts # Zustand store (~2812 lines, main state + tick logic) │ ├── stores/ # Modular Zustand stores (NEW)
│ ├── crafting-slice.ts # Equipment/enchantment logic (~1100 lines, from store.ts) │ │ ├── index.ts # Combined store exports
│ ├── computed-stats.ts # Computed stats functions (~12 lines, simplified) │ │ ├── gameStore.ts # Main store (~11KB, core state + tick)
│ ├── navigation-slice.ts # Floor navigation actions (~75 lines) │ │ ├── manaStore.ts # Mana state and actions (~9KB)
│ ├── study-slice.ts # Study system actions (~210 lines) │ │ ├── combatStore.ts # Combat system (~9KB)
│ ├── familiar-slice.ts # Familiar system actions │ │ ├── prestigeStore.ts # Prestige/loop system (~8KB)
│ ├── effects.ts # Unified effect computation │ │ ├── skillStore.ts # Skill state and actions (~11KB)
│ ├── upgrade-effects.ts # Skill upgrade effect definitions │ │ ├── uiStore.ts # UI state (~2KB)
│ ├── constants.ts # Game definitions (spells, skills, etc.) │ │ ├── gameLoopActions.ts # Game loop logic
│ ├── skill-evolution.ts # Skill tier progression paths (~3400 lines) │ │ ├── gameActions.ts # Generic game actions
│ ├── types.ts # TypeScript interfaces │ │ └── gameHooks.ts # Store hooks
│ ├── formatting.ts # Display formatters │ ├── store-modules/ # Legacy store utilities
│ ├── utils.ts # Utility functions │ ├── crafting-actions/ # Modular crafting system (NEW)
│ └── data/ │ │ ├── index.ts
│ ├── equipment.ts # Equipment type definitions │ │ ├── application-actions.ts
│ └── enchantment-effects.ts # Enchantment effect catalog │ │ ├── design-actions.ts
└── utils.ts # General utilities (cn function) │ │ ├── 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.* *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 ## 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: #### Store Modules (`src/lib/game/stores/`)
- **ActionButtons Rework**: Removed manual selection, auto-transition to Meditate after actions - **gameStore.ts**: Core state, tick logic, and main actions (~11KB)
- **SpireTab Overhaul**: Added "Climb the Spire" button, implemented Spire Mode with exit condition - **manaStore.ts**: Mana gathering, elements, conversion (~9KB)
- **Equipment System**: Added support for 2-Handed Weapons, Staves now block offhand slot - **combatStore.ts**: Combat system, spells, floor progression (~9KB)
- **Research Locking**: Prevent switching topics while study in progress - **prestigeStore.ts**: Prestige/loop system, insight, upgrades (~8KB)
- **DebugTab Update**: Added Invoker Debugging Buttons for Pacts - **skillStore.ts**: Skill state, studying, evolution (~11KB)
- **Combat UI Fix**: Fixed Casting Bar progress animation - **uiStore.ts**: UI state, modals, debug settings (~2KB)
- **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
**Context File Approach for Sub-Agents:** #### Legacy Store Files (Being Migrated)
During Task 2, context files were created in `docs/` to guide sub-agents: - **store.ts**: Reduced from ~2812 lines to ~14KB (core logic moved to stores/)
- `update_agents_context.md` - Context for updating AGENTS.md - **crafting-slice.ts**: Reduced, being replaced by crafting-actions/
- `update_game_briefing_context.md` - Context for updating GAME_BRIEFING.md
- `update_skills_context.md` - Context for updating skills.md
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 The crafting system has been split into focused action modules:
- **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**
#### 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: Extracted utility functions for stat calculations:
- `computeMaxMana()`, `computeRegen()`, `computeEffectiveRegen()` - `computeMaxMana()`, `computeRegen()`, `computeEffectiveRegen()`
- `calcDamage()`, `calcInsight()`, `getElementalBonus()` - `calcDamage()`, `calcInsight()`, `getElementalBonus()`
@@ -175,17 +332,17 @@ interface GameState {
hour: number; hour: number;
paused: boolean; paused: boolean;
// Mana // Mana (now in manaStore.ts)
rawMana: number; rawMana: number;
elements: Record<string, ElementState>; elements: Record<string, ElementState>;
// Combat // Combat (now in combatStore.ts)
currentFloor: number; currentFloor: number;
floorHP: number; floorHP: number;
activeSpell: string; activeSpell: string;
castProgress: number; castProgress: number;
// Progression // Progression (now in skillStore.ts)
skills: Record<string, number>; skills: Record<string, number>;
spells: Record<string, SpellState>; spells: Record<string, SpellState>;
skillUpgrades: Record<string, string[]>; skillUpgrades: Record<string, string[]>;
@@ -196,14 +353,14 @@ interface GameState {
equippedInstances: Record<string, string | null>; equippedInstances: Record<string, string | null>;
enchantmentDesigns: EnchantmentDesign[]; enchantmentDesigns: EnchantmentDesign[];
// Prestige // Prestige (now in prestigeStore.ts)
insight: number; insight: number;
prestigeUpgrades: Record<string, number>; prestigeUpgrades: Record<string, number>;
signedPacts: number[]; signedPacts: number[];
} }
``` ```
### 2. Effect System (`effects.ts`) ### Effect System (`effects.ts`)
**CRITICAL**: All stat modifications flow through the unified effect system. **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` 2. Add mapping in `computeEquipmentEffects()` in `effects.ts`
3. Apply in the relevant game logic (tick, damage calc, etc.) 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 ## Important Patterns
### Adding a New Effect ### Adding a New Effect
1. **Define in `enchantment-effects.ts`**: 1. **Define in `enchantment-effects.ts`** (now in `data/enchantment-effects.ts`):
```typescript ```typescript
my_new_effect: { my_new_effect: {
id: 'my_new_effect', id: 'my_new_effect',
@@ -294,17 +420,19 @@ damage *= effects.myNewStatMultiplier;
### Adding a New Skill ### Adding a New Skill
1. **Define in `constants.ts` SKILLS_DEF** 1. **Define in `constants/skills.ts`** (NEW location)
2. **Add evolution path in `skill-evolution.ts`** 2. **Add evolution path in `skill-evolution-modules/`** (NEW location)
3. **Add prerequisite checks in `store.ts`** - Create new module or add to existing module
4. **Update UI in `page.tsx`** 3. **Export from `skill-evolution-modules/index.ts`**
4. **Update UI in `components/game/tabs/SkillsTab.tsx`**
### Adding a New Spell ### Adding a New Spell
1. **Define in `constants.ts` SPELLS_DEF** 1. **Define in `constants/spells.ts`** (NEW location)
2. **Add spell enchantment in `enchantment-effects.ts`** 2. **Add to `constants/spells-modules/`** if categorized
3. **Add research skill in `constants.ts`** 3. **Add spell enchantment in `data/enchantment-effects.ts`**
4. **Map research to effect in `EFFECT_RESEARCH_MAPPING`** 4. **Add research skill in `constants/skills.ts`**
5. **Map research to effect in `EFFECT_RESEARCH_MAPPING`**
## Git Hooks (Husky) ## Git Hooks (Husky)
@@ -333,97 +461,71 @@ Runs after merging branches:
2. **Direct stat modification**: Never modify stats directly; use effect system 2. **Direct stat modification**: Never modify stats directly; use effect system
3. **Missing tier multiplier**: Use `getTierMultiplier(skillId)` for tiered skills 3. **Missing tier multiplier**: Use `getTierMultiplier(skillId)` for tiered skills
4. **Ignoring special effects**: Check `hasSpecial(effects, SPECIAL_EFFECTS.X)` for special abilities 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 ## Testing Guidelines
- Run `bun run lint` after changes - Run `npm run lint` after changes
- Check dev server logs at `/home/z/my-project/dev.log` - Run `npm run test` to execute unit tests
- Check dev server logs
- Test with fresh game state (clear localStorage) - 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`): | Directory | Purpose | Line Count Target |
```typescript |-----------|---------|-------------------|
// Define the actions interface | `stores/` | Zustand store modules | < 400 lines each |
export interface MyFeatureActions { | `crafting-actions/` | Crafting system actions | < 400 lines each |
doSomething: (param: string) => void; | `skill-evolution-modules/` | Skill trees by category | < 400 lines each |
undoSomething: () => void; | `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 ### Creating a New Module
export function createMyFeatureSlice(
set: StoreApi<GameStore>['setState'],
get: StoreApi<GameStore>['getState']
): MyFeatureActions {
return {
doSomething: (param: string) => {
set((state) => {
// Update state
});
},
undoSomething: () => {
set((state) => {
// Update state
});
},
};
}
```
2. **Add to main store** (`store.ts`): 1. **Identify the domain**: Which system does it belong to?
```typescript 2. **Create focused file**: Keep under 400 lines
import { createMyFeatureSlice, MyFeatureActions } from './my-feature-slice'; 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<GameStore>()(
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 ## File Size Guidelines
### Current File Sizes (After Task 2) ### Current File Sizes (After Modular Refactoring)
| File | Lines | Size (bytes) | Notes | | File | Lines | Size (bytes) | Notes |
|------|-------|--------------|-------| |------|-------|--------------|-------|
| `store.ts` | ~2812 | ~103KB | Core state + tick logic, crafting-slice extracted | | `stores/gameStore.ts` | ~300 | ~11KB | Core state + tick logic |
| `page.tsx` | ~548 | ~22KB | Main UI (heavily reduced through component extraction) | | `stores/manaStore.ts` | ~250 | ~9KB | Mana system |
| `crafting-slice.ts` | ~1100 | ~35KB | Equipment/enchantment logic (extracted from store.ts) | | `stores/combatStore.ts` | ~250 | ~9KB | Combat system |
| `skill-evolution.ts` | ~3400 | ~120KB | Skill tier progression paths | | `stores/prestigeStore.ts` | ~200 | ~8KB | Prestige system |
| `study-slice.ts` | ~210 | ~8KB | Study system actions | | `stores/skillStore.ts` | ~300 | ~11KB | Skill system |
| `navigation-slice.ts` | ~75 | ~3KB | Navigation actions | | `stores/uiStore.ts` | ~50 | ~2KB | UI state |
| `computed-stats.ts` | ~12 | ~1KB | Extracted utility functions (some moved to slices) | | `crafting-actions/*.ts` | ~50-150 | ~1-3KB each | Modular crafting |
| `components/game/tabs/*.tsx` | ~3000 | ~95KB | Tab-specific components (SpireTab, CraftingTab, etc.) | | `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 ### Guidelines
- Keep `page.tsx` under 600 lines by extracting to components (ActionButtons, ManaDisplay, tabs, etc.) - **400 lines maximum** per file (enforced by pre-commit hook)
- Keep `store.ts` under 3000 lines by extracting to slices (navigation, study, crafting, familiar) - Extract to modules when approaching 300 lines
- Extract computed stats and utility functions to appropriate slices or utils when >100 lines
- Use barrel exports (`index.ts`) for clean imports - Use barrel exports (`index.ts`) for clean imports
- Follow the slice pattern for store organization (see below) - Keep related functionality together in modules
- **After Task 2**: `page.tsx` reduced from ~2554 to ~548 lines (78% reduction) - **Modular architecture** is now the standard - all new code should follow this pattern
- **After Task 2**: `store.ts` increased due to crafting-slice integration, but better organized
### Automated File Size Check ### 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. 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.
docs/GAME_BRIEFING.md
+110 -46
View File
@@ -1,8 +1,8 @@
# Mana-Loop: Comprehensive Game Briefing Document # Mana-Loop: Comprehensive Game Briefing Document
**Document Version:** 1.1 **Document Version:** 1.2
**Generated:** Game Systems Analysis **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) 13. [Achievement System](#achievement-system)
14. [Formulas & Calculations](#formulas--calculations) 14. [Formulas & Calculations](#formulas--calculations)
15. [System Interactions](#system-interactions) 15. [System Interactions](#system-interactions)
16. [Code Architecture](#code-architecture)
--- ---
@@ -37,6 +38,8 @@
- Time pressure through incursion mechanic - Time pressure through incursion mechanic
- Guardian pacts provide permanent multipliers - 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 ## Core Game Loop
@@ -86,8 +89,8 @@
- **Spire Mode integration**: Action buttons are hidden when in Spire Mode (climbing simplified UI) - **Spire Mode integration**: Action buttons are hidden when in Spire Mode (climbing simplified UI)
**Implementation:** **Implementation:**
- `currentAction` state tracks the active action - `currentAction` state tracks the active action (now in `stores/gameStore.ts`)
- Crafting slice sets `currentAction: 'meditate'` when actions complete - Crafting actions set `currentAction: 'meditate'` when actions complete (in `crafting-actions/`)
- `ACTION_CONFIG` maps actions to display configs (label, icon, color) - `ACTION_CONFIG` maps actions to display configs (label, icon, color)
--- ---
@@ -212,7 +215,7 @@ element = FLOOR_ELEM_CYCLE[(floor - 1) % 7]
**Floor HP Formula:** **Floor HP Formula:**
``` ```
normalFloorHP = floor(100 + floor × 50 + floor^1.7) 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 **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 - Exit condition: Automatically exits when player chooses to stop climbing
**Implementation:** **Implementation:**
- `spireMode` boolean state in game store - `spireMode` boolean state in `stores/gameStore.ts`
- `enterSpireMode()` and `exitSpireMode()` actions - `enterSpireMode()` and `exitSpireMode()` actions in `stores/combatStore.ts`
- `simpleMode` prop passed to SpireTab for simplified rendering - `simpleMode` prop passed to SpireTab for simplified rendering
- UI conditionally renders based on `store.spireMode` - 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 | | **Unlock** | Starting attunement |
**Capabilities:** **Capabilities:**
- Enchanting equipment - Enchanting equipment (see `crafting-actions/`)
- Disenchanting for mana recovery - Disenchanting for mana recovery
- Access to enchanting skill tree (see `skill-evolution-modules/enchanting-skills.ts`)
**Skill Categories Unlocked:** **Skill Categories Unlocked:**
- `enchant` - Enchanting efficiency - `enchant` - Enchanting efficiency
@@ -449,9 +453,9 @@ Attunements are class-like specializations that grant unique capabilities and sk
- Form pacts with guardians - Form pacts with guardians
- Access guardian powers - Access guardian powers
- Elemental mastery through pacts - 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 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:** **Skill Categories Unlocked:**
- `invocation` - ✅ Implemented (T1-T5 skill tree) - `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 | | **Unlock** | Prove crafting worth |
**Capabilities:** **Capabilities:**
- Golem crafting - Golem crafting (see `data/golems/`)
- Gear crafting - Gear crafting (see `data/equipment/`)
- Earth shaping - Earth shaping
**Skill Categories Unlocked:** **Skill Categories Unlocked:**
@@ -481,7 +485,7 @@ Attunements are class-like specializations that grant unique capabilities and sk
### Attunement Leveling ### Attunement Leveling
**XP Formula:** **XP Formula:**
``` ```javascript
Level 2: 1,000 XP Level 2: 1,000 XP
Level 3: 2,500 XP Level 3: 2,500 XP
Level 4: 5,000 XP Level 4: 5,000 XP
@@ -491,7 +495,7 @@ Max Level: 10
``` ```
**Level Scaling:** **Level Scaling:**
``` ```javascript
regenMultiplier = 1.5^(level - 1) regenMultiplier = 1.5^(level - 1)
conversionRate = baseRate × 1.5^(level - 1) conversionRate = baseRate × 1.5^(level - 1)
``` ```
@@ -505,19 +509,19 @@ conversionRate = baseRate × 1.5^(level - 1)
### Skill Categories ### Skill Categories
| Category | Attunement | Description | | Category | Attunement | Description | Status |
|----------|------------|-------------| |----------|------------|-------------|---------|
| `mana` | Core | Max mana, regen, element cap | | `mana` | Core | Max mana, regen, element cap | ✅ Implemented |
| `study` | Core | Study speed, cost reduction | | `study` | Core | Study speed, cost reduction | ✅ Implemented |
| `research` | Core | Click bonuses, advanced meditation | | `research` | Core | Click bonuses, advanced meditation | ✅ Implemented |
| `ascension` | Core | Insight, guardian damage | | `ascension` | Core | Insight, guardian damage | ✅ Implemented |
| `enchant` | Enchanter | Enchanting efficiency | | `enchant` | Enchanter | Enchanting efficiency | ✅ Implemented (T1-T5) |
| `effectResearch` | Enchanter | Unlock enchantment effects | | `effectResearch` | Enchanter | Unlock enchantment effects | ✅ Implemented (max:1) |
| `invocation` | Invoker | ✅ Implemented (T1-T5 skill tree) | | `invocation` | Invoker | Pact-based abilities | ✅ Implemented (T1-T5) |
| `pact` | Invoker | ✅ Implemented (T1-T5 skill tree) | | `pact` | Invoker | Guardian pact bonuses | ✅ Implemented (T1-T5) |
| `fabrication` | Fabricator | Crafting speed | | `fabrication` | Fabricator | Crafting and construction | ✅ Implemented (T1-T5) |
| `golemancy` | Fabricator | Golem control | | `golemancy` | Fabricator | Golem summoning and control | ✅ Implemented (T1-T5) |
| `craft` | Legacy | Basic crafting | | `craft` | Legacy | Basic crafting | ✅ Implemented |
### Core Skills ### Core Skills
@@ -525,11 +529,11 @@ conversionRate = baseRate × 1.5^(level - 1)
|-------|-----|--------|------------| |-------|-----|--------|------------|
| Mana Well | 10 | +100 max mana/level | 4h | | Mana Well | 10 | +100 max mana/level | 4h |
| Mana Flow | 10 | +1 regen/level | 5h | | 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 | | Mana Overflow | 5 | +25% click mana/level | 6h |
| Quick Learner | 10 | +10% study speed/level | 4h |
| Focused Mind | 10 | -5% study cost/level | 5h | **Prerequisites:**
| Meditation Focus | 1 | 2.5x regen after 4h | 6h | - Mana Overflow: Mana Well 3
### Skill Tier Evolution ### Skill Tier Evolution
@@ -570,8 +574,13 @@ Tier 5: Mythic (multiplier ×10,000)
| Efficient Enchant | 5 | Enchanter 2, Enchanting 3 | -5% capacity cost/level | | Efficient Enchant | 5 | Enchanter 2, Enchanting 3 | -5% capacity cost/level |
| Disenchanting | 3 | Enchanter 1, Enchanting 2 | +20% mana recovery/level | | Disenchanting | 3 | Enchanter 1, Enchanting 2 | +20% mana recovery/level |
| Enchant Speed | 5 | Enchanter 1, Enchanting 2 | -10% time/level | | Enchant Speed | 5 | Enchanter 1, Enchanting 2 | -10% time/level |
| Essence Refining | 5 | Enchanter 2, Enchanting 4 | +10% effect power/level | | Essence Refining | 1 | Enchanter 2, Enchanting 4 | +10% effect power |
| Effect Research (all) | 1 | Enchanter 1+ | Unlock enchantment effects (max:1, no evolution) |
**Prerequisites:**
- Efficient Enchant: Enchanting 3
- Disenchanting: Enchanting 2
- Enchant Speed: Enchanting 2
- Essence Refining: Enchanting 4
### Golemancy Skills ### Golemancy Skills
@@ -581,7 +590,7 @@ Tier 5: Mythic (multiplier ×10,000)
| Golem Efficiency | 5 | Fabricator 2 | +5% attack speed/level | | Golem Efficiency | 5 | Fabricator 2 | +5% attack speed/level |
| Golem Longevity | 3 | Fabricator 3 | +1 floor duration/level | | Golem Longevity | 3 | Fabricator 3 | +1 floor duration/level |
| Golem Siphon | 3 | Fabricator 3 | -10% maintenance/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 |
--- ---
@@ -592,6 +601,7 @@ Hybrid Skills are advanced skills that require two attunements and combine their
#### Pact-Weaving (Invoker + Enchanter) #### Pact-Weaving (Invoker + Enchanter)
**Requirement:** Invoker 3 + Enchanter 3 **Requirement:** Invoker 3 + Enchanter 3
**Location:** `skill-evolution-modules/hybrid-skills.ts`
**Paths:** **Paths:**
- **Path A: The Weaver** - Enhanced enchantment power through pact bonuses - **Path A: The Weaver** - Enhanced enchantment power through pact bonuses
@@ -617,6 +627,7 @@ Hybrid Skills are advanced skills that require two attunements and combine their
#### Guardian Constructs (Fabricator + Invoker) #### Guardian Constructs (Fabricator + Invoker)
**Requirement:** Fabricator 3 + Invoker 3 **Requirement:** Fabricator 3 + Invoker 3
**Location:** `skill-evolution-modules/hybrid-skills.ts`
**Paths:** **Paths:**
- **Path A: The Architect** - Durable constructs with enhanced defenses - **Path A: The Architect** - Durable constructs with enhanced defenses
@@ -647,6 +658,7 @@ Hybrid Skills are advanced skills that require two attunements and combine their
#### Enchanted Golemancy (Fabricator + Enchanter) #### Enchanted Golemancy (Fabricator + Enchanter)
**Requirement:** Fabricator 3 + Enchanter 3 **Requirement:** Fabricator 3 + Enchanter 3
**Location:** `skill-evolution-modules/hybrid-skills.ts`
**Paths:** **Paths:**
- **Path A: The Battle-Smith** - Combat-focused enchanted golems - **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 - The UI displays a "2-Handed" badge on applicable items and shows "Blocked by 2-handed weapon" for blocked slots
**Implementation:** **Implementation:**
- Equipment types have a `twoHanded: true` property - Equipment types have a `twoHanded: true` property (see `data/equipment/`)
- `equipItem()` validates 2-handed weapon constraints - `equipItem()` validates 2-handed weapon constraints (in `stores/gameStore.ts`)
- `isSlotBlocked()` function checks if offhand is blocked by main hand 2H weapon - `isSlotBlocked()` function checks if offhand is blocked by main hand 2H weapon
### Equipment Categories ### Equipment Categories
@@ -720,7 +732,7 @@ accessory2 - Rings, Amulets
```typescript ```typescript
interface EquipmentInstance { interface EquipmentInstance {
instanceId: string; // Unique ID instanceId: string; // Unique ID
typeId: string; // Reference to EquipmentType typeId: string; // Reference to EquipmentType (in data/equipment/)
name: string; name: string;
enchantments: AppliedEnchantment[]; enchantments: AppliedEnchantment[];
usedCapacity: number; // Current capacity used usedCapacity: number; // Current capacity used
@@ -734,15 +746,11 @@ interface EquipmentInstance {
#### Stage 1: Design #### Stage 1: Design
- Create enchantment 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) - **Limited to owned gear types** (cannot design for equipment you don't have)
- Calculate capacity cost - Calculate capacity cost
- Time: Base 1h + 0.5h per effect stack - Time: Base 1h + 0.5h per effect stack
- **Implementation:** `crafting-actions/design-actions.ts`
**Capacity Cost Formula:**
```
totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonus))
```
#### Stage 2: Prepare #### Stage 2: Prepare
- Prepare equipment for enchanting - Prepare equipment for enchanting
@@ -750,6 +758,7 @@ totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonu
- Mana cost: capacity × 10 - Mana cost: capacity × 10
- Time: 2h + 1h per 50 capacity - Time: 2h + 1h per 50 capacity
- **Auto-transitions to Meditate** when complete - **Auto-transitions to Meditate** when complete
- **Implementation:** `crafting-actions/preparation-actions.ts`
#### Stage 3: Apply #### Stage 3: Apply
- Apply enchantment design - Apply enchantment design
@@ -757,6 +766,7 @@ totalCost = Σ(effect.baseCost × (1 + 0.2 × stackIndex) × (1 - efficiencyBonu
- Time: 2h + 1h per effect stack - Time: 2h + 1h per effect stack
- Grants Enchanter XP: 1 XP per 10 capacity - Grants Enchanter XP: 1 XP per 10 capacity
- **Auto-transitions to Meditate** when complete - **Auto-transitions to Meditate** when complete
- **Implementation:** `crafting-actions/application-actions.ts`
### Enchantment Effect Categories ### Enchantment Effect Categories
@@ -929,7 +939,7 @@ finalInsight = floor(baseInsight × (1 + insightAmpLevel × 0.25) × skillBonus)
```javascript ```javascript
function calcDamage(state, spellId, floorElement) { function calcDamage(state, spellId, floorElement) {
const spell = SPELLS_DEF[spellId]; const spell = SPELLS_DEF[spellId]; // Now in constants/spells.ts
// Base damage // Base damage
let damage = spell.dmg + (state.skills.combatTrain || 0) * 5; let damage = spell.dmg + (state.skills.combatTrain || 0) * 5;
@@ -946,7 +956,7 @@ function calcDamage(state, spellId, floorElement) {
} }
// Pact multiplier // 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 // Elemental effectiveness
damage *= getElementalBonus(spell.elem, floorElement); 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 ## Appendix: Known Issues
### Task 2 Updates (Completed) ### 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 5. **Show Component Names** - Fixed debug option to properly display component names in UI
6. **DebugTab** - Added Invoker Debugging Buttons for Pacts (`PactDebug` component) 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 ### Missing Implementations
1. **Field Repair** - Skill exists, no repair system 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* *End of Game Briefing Document*
docs/skills.md
+94 -13
View File
@@ -8,6 +8,7 @@
5. [Upgrade Trees](#upgrade-trees) 5. [Upgrade Trees](#upgrade-trees)
6. [Tier System](#tier-system) 6. [Tier System](#tier-system)
7. [Banned Content](#banned-content) 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 | | Study | 📚 | Learning speed and efficiency |
| Research | 🔮 | Permanent bonuses | | Research | 🔮 | Permanent bonuses |
### Attunement Categories ### Attunement Categories
| Category | Icon | Attunement | Description | Status | | Category | Icon | Attunement | Description | Status |
|----------|------|------------|-------------|-------| |----------|------|------------|-------------|---------|
| Enchanting | ✨ | Enchanter | Enchantment design and efficiency | ✅ Implemented (T1-T5) | | Enchanting | ✨ | Enchanter | Enchantment design and efficiency | ✅ Implemented (T1-T5) |
| Effect Research | 🔬 | Enchanter | Unlock spell enchantments | ✅ Implemented (max:1) | | Effect Research | 🔬 | Enchanter | Unlock spell enchantments | ✅ Implemented (max:1) |
| Invocation | 💜 | Invoker | Pact-based abilities | ✅ Implemented (T1-T5) | | 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. 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) ### Pact-Weaving (Invoker + Enchanter)
**Requirement:** Invoker 3 + Enchanter 3 **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:** **Paths:**
- **Path A: The Weaver** - Enhanced enchantment power through pact bonuses - **Path A: The Weaver** - Enhanced enchantment power through pact bonuses
@@ -196,6 +199,7 @@ Hybrid Skills require two attunements and combine their powers into advanced abi
**Requirement:** Fabricator 3 + Invoker 3 **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:** **Paths:**
- **Path A: The Architect** - Durable constructs with enhanced defenses - **Path A: The Architect** - Durable constructs with enhanced defenses
@@ -238,6 +242,7 @@ Hybrid Skills require two attunements and combine their powers into advanced abi
**Requirement:** Fabricator 3 + Enchanter 3 **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:** **Paths:**
- **Path A: The Battle-Smith** - Combat-focused enchanted golems - **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. 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 | | Skill | Unlocks | Study Time |
|-------|---------|------------| |-------|---------|------------|
| Mana Spell Research | Mana Strike enchantment | 4h | | 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 | | Dark Spell Research | Shadow Bolt, Dark Pulse | 8h |
| Death Research | Drain enchantment | 8h | | Death Research | Drain enchantment | 8h |
#### Tier 2 Research (Advanced Spells) #### Tier2 Research (Advanced Spells)
Requires Enchanter 3+ and parent element research. Requires Enchanter 3+ and parent element research.
| Skill | Unlocks | Study Time | | Skill | Unlocks | Study Time |
@@ -304,7 +311,7 @@ Requires Enchanter 3+ and parent element research.
| Advanced Light Research | Solar Flare, Divine Smite | 14h | | Advanced Light Research | Solar Flare, Divine Smite | 14h |
| Advanced Dark Research | Void Rift, Shadow Storm | 14h | | Advanced Dark Research | Void Rift, Shadow Storm | 14h |
#### Tier 3 Research (Master Spells) #### Tier3 Research (Master Spells)
Requires Enchanter 5+ and advanced research. Requires Enchanter 5+ and advanced research.
| Skill | Unlocks | Study Time | | Skill | Unlocks | Study Time |
@@ -352,9 +359,16 @@ Requires parent element research + Enchanter 3+.
## Upgrade Trees ## 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 ### Mana Well Upgrade Tree
#### Tier 1 Upgrades #### Tier1 Upgrades
**Level 5 Choices:** **Level 5 Choices:**
``` ```
@@ -376,7 +390,7 @@ Requires parent element research + Enchanter 3+.
- Emergency Reserve (Keep 10% mana on loop reset) - Emergency Reserve (Keep 10% mana on loop reset)
- Deep Wellspring (+50% meditation efficiency) - Deep Wellspring (+50% meditation efficiency)
#### Tier 2 Upgrades (Deep Reservoir) #### Tier2 Upgrades (Deep Reservoir)
- Abyssal Depth (+50% max mana) - Abyssal Depth (+50% max mana)
- Ancient Well (+500 starting mana per loop) - Ancient Well (+500 starting mana per loop)
- Mana Condense (+1% max per 1000 gathered) - Mana Condense (+1% max per 1000 gathered)
@@ -390,7 +404,7 @@ Requires parent element research + Enchanter 3+.
### Mana Flow Upgrade Tree ### Mana Flow Upgrade Tree
#### Tier 1 Upgrades #### Tier1 Upgrades
**Level 5 Choices:** **Level 5 Choices:**
``` ```
@@ -415,7 +429,7 @@ Requires parent element research + Enchanter 3+.
### Elemental Attunement Upgrade Tree ### Elemental Attunement Upgrade Tree
#### Tier 1 Upgrades #### Tier1 Upgrades
**Level 5 Choices:** **Level 5 Choices:**
``` ```
@@ -436,7 +450,7 @@ Requires parent element research + Enchanter 3+.
### Quick Learner Upgrade Tree ### Quick Learner Upgrade Tree
#### Tier 1 Upgrades #### Tier1 Upgrades
**Level 5 Choices:** **Level 5 Choices:**
``` ```
@@ -459,7 +473,7 @@ Requires parent element research + Enchanter 3+.
### Focused Mind Upgrade Tree ### Focused Mind Upgrade Tree
#### Tier 1 Upgrades #### Tier1 Upgrades
**Level 5 Choices:** **Level 5 Choices:**
``` ```
@@ -480,7 +494,7 @@ Requires parent element research + Enchanter 3+.
### Enchanting Upgrade Tree ### Enchanting Upgrade Tree
#### Tier 1 Upgrades #### Tier1 Upgrades
**Level 5 Choices:** **Level 5 Choices:**
``` ```
@@ -499,7 +513,7 @@ Requires parent element research + Enchanter 3+.
### Golem Mastery Upgrade Tree ### Golem Mastery Upgrade Tree
#### Tier 1 Upgrades #### Tier1 Upgrades
**Level 5 Choices:** **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 ## Example Progression
### Mana Well Complete Journey ### Mana Well Complete Journey
@@ -637,3 +713,8 @@ The following effects/mechanics are **NOT allowed** in skill upgrades:
- Base: 500 × 10 = 5000 max mana - Base: 500 × 10 = 5000 max mana
- Upgrades: +50% from Tier 1 +50% from Tier 2 = +100% - Upgrades: +50% from Tier 1 +50% from Tier 2 = +100%
- Total: 5000 × 2 = **10,000 max mana** - Total: 5000 × 2 = **10,000 max mana**
---
*Document Version: 1.1 (Updated for Modular Architecture)*
*Code has been refactored - game mechanics unchanged*