docs: add spec for SpireTab refresh and casting fixes
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 1m36s
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 1m36s
This commit is contained in:
@@ -0,0 +1,142 @@
|
||||
# SPEC: SpireTab Refresh & Casting Fixes
|
||||
|
||||
## 1. Objective
|
||||
|
||||
Fix multiple issues with the SpireTab and spell casting system:
|
||||
|
||||
1. **Cast bar not updating**: Spell cast progress (`castProgress`) doesn't update visually during combat
|
||||
2. **Casting doesn't cost mana**: Mana costs are not deducted when spells are cast
|
||||
3. **SpireTab full-screen experience**: SpireTab should be a dedicated screen where:
|
||||
- Player cannot study skills (must climb down to exit spire first)
|
||||
- Layout is optimized for combat focus
|
||||
4. **Confusing layout**: Current SpireTab layout is cluttered and needs refresh for better UX
|
||||
|
||||
**Why**:
|
||||
- Casting feels broken when progress bar doesn't update
|
||||
- Players get free spells (no mana cost) which breaks game balance
|
||||
- Spire should feel like a separate "mode" with focused combat
|
||||
- Current layout confuses players about available actions
|
||||
|
||||
## 2. Controls/API
|
||||
|
||||
### Player-Facing Controls
|
||||
- **Climb Up/Down buttons**: Change floors (already exists)
|
||||
- **Spell selection**: Click to set active spell (already exists)
|
||||
- **Enter Spire Mode**: Button to enter dedicated spire screen (already exists)
|
||||
- **Cast progress bar**: Visual indicator of spell casting progress (BROKEN - needs fix)
|
||||
- **Climb Down to Exit**: Only way to leave spire mode (NEW behavior)
|
||||
|
||||
### Modified Game Internals
|
||||
- `combatStore.ts`:
|
||||
- `castProgress`: Should update 0-1 per tick (fix binding)
|
||||
- `processCombatTick()`: Should properly deduct mana costs via `deductSpellCost()`
|
||||
- `SpireTab.tsx`:
|
||||
- Remove study progress components (player can't study in spire)
|
||||
- Remove crafting progress components (irrelevant in spire)
|
||||
- Add "Climb Down" button to exit spire mode
|
||||
- Refresh layout for clarity
|
||||
|
||||
### Public API Changes
|
||||
None (internal bug fixes + UI refresh)
|
||||
|
||||
## 3. Project Layout
|
||||
|
||||
Follow modular architecture rules from AGENTS.md:
|
||||
|
||||
### Files to Modify
|
||||
| File | Purpose | Line Count Check |
|
||||
|------|---------|------------------|
|
||||
| `src/components/game/tabs/SpireTab.tsx` | Main SpireTab component - refresh layout, remove study/crafting | Must stay <400 lines |
|
||||
| `src/components/game/tabs/SpireHeader.tsx` | Spire header - ensure maxFloorReached works | Must stay <400 lines |
|
||||
| `src/components/game/tabs/FloorControls.tsx` | Floor controls - add "Climb Down to Exit" | Must stay <400 lines |
|
||||
| `src/lib/game/stores/combat-actions.ts` | Fix mana deduction in `processCombatTick()` | Must stay <400 lines |
|
||||
| `src/lib/game/stores/combatStore.ts` | Ensure `castProgress` updates correctly | Must stay <400 lines |
|
||||
|
||||
### Files to Create
|
||||
| File | Purpose | Line Count Check |
|
||||
|------|---------|------------------|
|
||||
| None (modifying existing files only) | | |
|
||||
|
||||
### Stores to Use (NO LEGACY STORES!)
|
||||
- ✅ `useCombatStore` from `src/lib/game/stores/combatStore`
|
||||
- ✅ `useManaStore` from `src/lib/game/stores/manaStore`
|
||||
- ✅ `usePrestigeStore` from `src/lib/game/stores/prestigeStore`
|
||||
- ❌ NO `import from '@/lib/game/store'` (legacy!)
|
||||
- ❌ NO `import from '@/lib/game/store-modules/'` (legacy!)
|
||||
|
||||
### Module Ownership
|
||||
- SpireTab UI: `components/game/tabs/`
|
||||
- Combat logic: `stores/combat-actions.ts`
|
||||
- Store state: `stores/combatStore.ts`
|
||||
|
||||
## 4. Code Style
|
||||
|
||||
Follow existing project conventions:
|
||||
- TypeScript strict mode, explicit type annotations
|
||||
- Zustand store patterns: `set()`, `get()` for state updates
|
||||
- Use modular stores ONLY (AGENTS.md rule)
|
||||
- Naming: camelCase for variables/functions, PascalCase for interfaces/types
|
||||
- No `any` types, use defined interfaces from `src/lib/game/types/`
|
||||
- Follow ESLint rules (run `npm run lint` before committing)
|
||||
- Use existing patterns for combat/spell casting
|
||||
|
||||
### Key Patterns
|
||||
- Cast progress: `useCombatStore((s) => s.castProgress)` (0-1 value)
|
||||
- Mana deduction: Use `deductSpellCost()` from `src/lib/game/utils/`
|
||||
- Guard against undefined stores: Optional chaining `state?.castProgress`
|
||||
|
||||
## 5. Testing
|
||||
|
||||
### What to Test
|
||||
1. **Cast bar updates**: `castProgress` changes during combat ticks
|
||||
2. **Mana costs deducted**: Raw mana/elements decrease when spells cast
|
||||
3. **No studying in spire**: Study components not rendered when `simpleMode=true`
|
||||
4. **Climb down to exit**: Button appears in spire mode, clears `spireMode`
|
||||
5. **Layout refresh**: SpireTab renders cleanly without clutter
|
||||
|
||||
### How to Test
|
||||
- Unit tests using Vitest (existing test framework)
|
||||
- Test files in `src/lib/game/stores/__tests__/`
|
||||
- Mock game state to simulate combat ticks
|
||||
- Assert castProgress changes over time
|
||||
- Assert mana decreases after spell cast
|
||||
- Use `useCombatStore.getState()` for assertions
|
||||
|
||||
### Tooling
|
||||
- Vitest (test runner)
|
||||
- Zustand store testing patterns (use `getState()`)
|
||||
- Mock `deductSpellCost()` to verify calls
|
||||
|
||||
## 6. Boundaries (Out-of-Scope Items)
|
||||
|
||||
- No changes to spell definitions or damage calculations
|
||||
- No changes to attunement system (separate from spire)
|
||||
- No changes to prestige/system (unless directly related to spire exit)
|
||||
- No new tabs or major architectural changes
|
||||
- No changes to legacy store (we're avoiding it, not fixing it here)
|
||||
- No changes to other tabs (SkillsTab, CraftingTab, etc.)
|
||||
|
||||
## Acceptance Criteria (Per Requirement)
|
||||
|
||||
| # | Requirement | Acceptance Criterion |
|
||||
|---|-------------|----------------------|
|
||||
| 1 | Cast bar updates during spell casting | `castProgress` in combatStore changes 0→1 over time, and UI reflects this |
|
||||
| 2 | Casting costs mana | `rawMana` or element mana decreases by `spell.cost` when spell completes |
|
||||
| 3 | SpireTab is full-screen combat focus | Study/Crafting components NOT rendered when `simpleMode=true` |
|
||||
| 4 | Player must climb down to exit spire | "Climb Down" button visible in spire mode, clears `spireMode` on click |
|
||||
| 5 | Layout refresh for clarity | SpireTab has clear sections: Floor Info, Combat, Controls (no clutter) |
|
||||
| 6 | Use modular stores only | Zero imports from `store.ts` or `store-modules/` in modified files |
|
||||
| 7 | All files <400 lines | Pre-commit hook passes for all modified files |
|
||||
| 8 | Regression tests added | New test file `spire-tab-refresh.test.ts` passes in `npm run test` |
|
||||
|
||||
## Verification Checklist (Do NOT implement until approved!)
|
||||
|
||||
- ☐ SPEC.md committed to version control (not yet)
|
||||
- ☑ Every feature has explicit acceptance criterion (above)
|
||||
- ☑ Out-of-scope items listed (Boundaries section)
|
||||
- ☐ Human has reviewed and approved (**WAITING FOR THIS**)
|
||||
- ☐ No implementation code exists yet (correct - spec only)
|
||||
|
||||
**I will NOT proceed to PLAN or IMPLEMENT phases until this spec is approved by you (the human).**
|
||||
|
||||
Please review and approve, or request changes.
|
||||
Reference in New Issue
Block a user