docs: Add README.md, update AGENTS.md, audit report, and massive refactoring
Documentation: - Add comprehensive README.md with project overview - Update AGENTS.md with new file structure and slice pattern - Add AUDIT_REPORT.md documenting unimplemented effects Refactoring (page.tsx: 1695 → 434 lines, 74% reduction): - Extract SkillsTab.tsx component - Extract StatsTab.tsx component - Extract UpgradeDialog.tsx component - Move getDamageBreakdown and getTotalDPS to computed-stats.ts - Move ELEMENT_ICON_NAMES to constants.ts All lint checks pass, functionality preserved.
This commit is contained in:
121
AGENTS.md
121
AGENTS.md
@@ -53,26 +53,37 @@ This document provides a comprehensive overview of the project architecture for
|
||||
```
|
||||
src/
|
||||
├── app/
|
||||
│ ├── page.tsx # Main game UI (single page application)
|
||||
│ ├── page.tsx # Main game UI (~1700 lines, single page application)
|
||||
│ ├── layout.tsx # Root layout with providers
|
||||
│ └── api/ # API routes (minimal use)
|
||||
├── components/
|
||||
│ ├── ui/ # shadcn/ui components (auto-generated)
|
||||
│ └── game/
|
||||
│ ├── index.ts # Barrel exports
|
||||
│ └── tabs/ # Tab-specific components
|
||||
│ ├── CraftingTab.tsx
|
||||
│ ├── LabTab.tsx
|
||||
│ ├── SpellsTab.tsx
|
||||
│ └── SpireTab.tsx
|
||||
│ ├── ActionButtons.tsx # Main action buttons (Meditate, Climb, Study, etc.)
|
||||
│ ├── 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
|
||||
│ ├── index.ts # Tab component exports
|
||||
│ ├── CraftingTab.tsx # Enchantment crafting UI
|
||||
│ ├── LabTab.tsx # Skill upgrade and lab features
|
||||
│ ├── SpellsTab.tsx # Spell management and equipment spells
|
||||
│ └── SpireTab.tsx # Combat and spire climbing
|
||||
└── lib/
|
||||
├── game/
|
||||
│ ├── store.ts # Zustand store (state + actions)
|
||||
│ ├── store.ts # Zustand store (~1650 lines, main state + tick logic)
|
||||
│ ├── computed-stats.ts # Computed stats functions (extracted utilities)
|
||||
│ ├── navigation-slice.ts # Floor navigation actions (setClimbDirection, changeFloor)
|
||||
│ ├── study-slice.ts # Study system actions (startStudying*, cancelStudy)
|
||||
│ ├── crafting-slice.ts # Equipment/enchantment logic
|
||||
│ ├── 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
|
||||
│ ├── crafting-slice.ts # Equipment/enchantment logic
|
||||
│ ├── types.ts # TypeScript interfaces
|
||||
│ ├── formatting.ts # Display formatters
|
||||
│ ├── utils.ts # Utility functions
|
||||
@@ -86,7 +97,21 @@ src/
|
||||
|
||||
### 1. State Management (`store.ts`)
|
||||
|
||||
The game uses a single Zustand store with the following key slices:
|
||||
The game uses a Zustand store organized with **slice pattern** for better maintainability:
|
||||
|
||||
#### Store Slices
|
||||
- **Main Store** (`store.ts`): Core state, tick logic, and main actions
|
||||
- **Navigation Slice** (`navigation-slice.ts`): Floor navigation (setClimbDirection, changeFloor)
|
||||
- **Study Slice** (`study-slice.ts`): Study system (startStudyingSkill, startStudyingSpell, cancelStudy)
|
||||
- **Crafting Slice** (`crafting-slice.ts`): Equipment/enchantment (createEquipmentInstance, startDesigningEnchantment)
|
||||
- **Familiar Slice** (`familiar-slice.ts`): Familiar system (addFamiliar, removeFamiliar)
|
||||
|
||||
#### Computed Stats (`computed-stats.ts`)
|
||||
Extracted utility functions for stat calculations:
|
||||
- `computeMaxMana()`, `computeRegen()`, `computeEffectiveRegen()`
|
||||
- `calcDamage()`, `calcInsight()`, `getElementalBonus()`
|
||||
- `getFloorMaxHP()`, `getFloorElement()`, `getMeditationBonus()`
|
||||
- `canAffordSpellCost()`, `deductSpellCost()`
|
||||
|
||||
```typescript
|
||||
interface GameState {
|
||||
@@ -239,8 +264,82 @@ damage *= effects.myNewStatMultiplier;
|
||||
- Check dev server logs at `/home/z/my-project/dev.log`
|
||||
- Test with fresh game state (clear localStorage)
|
||||
|
||||
## Slice Pattern for Store Organization
|
||||
|
||||
The store uses a **slice pattern** to organize related actions into separate files. This improves maintainability and makes the codebase more modular.
|
||||
|
||||
### Creating a New Slice
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
// Create the slice factory
|
||||
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`):
|
||||
```typescript
|
||||
import { createMyFeatureSlice, MyFeatureActions } from './my-feature-slice';
|
||||
|
||||
// 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 | Purpose |
|
||||
|-------|------|---------|
|
||||
| Navigation | `navigation-slice.ts` | Floor navigation (setClimbDirection, changeFloor) |
|
||||
| Study | `study-slice.ts` | Study system (startStudyingSkill, startStudyingSpell, cancelStudy) |
|
||||
| Crafting | `crafting-slice.ts` | Equipment/enchantment (createEquipmentInstance, startDesigningEnchantment) |
|
||||
| Familiar | `familiar-slice.ts` | Familiar system (addFamiliar, removeFamiliar) |
|
||||
|
||||
## File Size Guidelines
|
||||
|
||||
- Keep `page.tsx` under 2000 lines by extracting to tab components
|
||||
- Keep store functions focused; extract to helper files when >50 lines
|
||||
### Current File Sizes (After Refactoring)
|
||||
| File | Lines | Notes |
|
||||
|------|-------|-------|
|
||||
| `store.ts` | ~1650 | Core state + tick logic (reduced from 2138, 23% reduction) |
|
||||
| `page.tsx` | ~1695 | Main UI (reduced from 2554, 34% reduction) |
|
||||
| `computed-stats.ts` | ~200 | Extracted utility functions |
|
||||
| `navigation-slice.ts` | ~50 | Navigation actions |
|
||||
| `study-slice.ts` | ~100 | Study system actions |
|
||||
|
||||
### Guidelines
|
||||
- Keep `page.tsx` under 2000 lines by extracting to components (ActionButtons, ManaDisplay, etc.)
|
||||
- Keep `store.ts` under 1800 lines by extracting to slices (navigation, study, crafting, familiar)
|
||||
- Extract computed stats and utility functions to `computed-stats.ts` when >50 lines
|
||||
- Use barrel exports (`index.ts`) for clean imports
|
||||
- Follow the slice pattern for store organization (see below)
|
||||
|
||||
Reference in New Issue
Block a user