diff --git a/README.md b/README.md index d64fb5a..f81fd24 100644 --- a/README.md +++ b/README.md @@ -49,11 +49,20 @@ A dark-fantasy idle RPG built as a Progressive Web App. Clear dungeon gates, fig - **Training Activities** - Physical training, mental training, meditation (fatigue recovery), and work jobs - **Potion System** - HP/MP healing that scales with player level and potion quality +### Meta & Progression Systems +- **Achievement System** - 25+ achievements across 4 categories (combat, progression, collection, exploration) +- **Statistics Dashboard** - Track combat stats, gates cleared, spirits bound, play time, and more +- **Tutorial System** - Guided onboarding for new players so you're not dropped into the abyss blind +- **Settings Panel** - Audio controls, save management, and game options + ### Quality of Life - **PWA** - Install on mobile/desktop, works fully offline +- **Save Export/Import** - Download your save as JSON; restore it anytime +- **Save Corruption Recovery** - Rotating backups so a bad save never ends your run - **Auto-Save** - localStorage persistence with save data integrity - **Responsive UI** - Desktop panel layout + dedicated mobile tab interface -- **Audio & Haptics** - Sound effects and vibration feedback +- **AI-Generated Audio** - Background music via MusicGen and synthesized SFX — no more silence +- **Haptic Feedback** - Vibration on mobile for combat hits and key events - **Lore System** - Unlockable story entries as you progress ## Tech Stack @@ -105,15 +114,26 @@ HunterPath/ │ │ │ ├── HuntersPath.tsx # Main game component (state, combat loop, UI) │ │ │ ├── bosses/ # Animated boss SVG components (E-S rank) │ │ │ ├── mobile/ # Mobile-specific layout and tabs -│ │ │ └── sections/ # Desktop UI panels (Stats, Inventory, Quests, etc.) +│ │ │ └── sections/ # UI panels +│ │ │ ├── Achievements.tsx # Achievement tracker and unlock display +│ │ │ ├── Statistics.tsx # Play stats dashboard +│ │ │ ├── Settings.tsx # Audio, save management, options +│ │ │ ├── Tutorial.tsx # New-player onboarding flow +│ │ │ └── ... # Stats, Inventory, Quests, Shop, Lore, etc. │ │ └── ui/ # shadcn/ui component library │ ├── lib/game/ # Pure game logic (testable, no React) │ │ ├── gameLogic.ts # Player power, spirit upkeep, binding chance │ │ ├── gameUtils.ts # clamp, rand, uid, fmt, pick │ │ ├── gateSystem.ts # Gate generation, bosses, drops, modifiers │ │ ├── spiritSystem.ts # Spirit creation, rarity, abilities -│ │ └── questSystem.ts # Daily quest generation, difficulty scaling +│ │ ├── questSystem.ts # Daily quest generation, difficulty scaling +│ │ ├── achievementSystem.ts # Achievement definitions, unlock conditions +│ │ └── statsTracker.ts # Combat stats, play time, lifetime counters │ └── hooks/ # Custom React hooks +├── scripts/ # Asset generation tooling +│ ├── generate-music-ai.py # MusicGen model — background music tracks +│ ├── generate-music.py # Procedural music fallback +│ └── generate-sfx.py # Synthesized sound effects ├── server/ │ ├── index.ts # Express server setup │ ├── routes.ts # API route registration @@ -128,7 +148,7 @@ HunterPath/ ## Testing -The test suite covers game mechanics, React components, server storage, and schema validation. +215 tests across 13 files cover game mechanics, new systems, React components, server storage, and schema validation. ```bash # Run all tests @@ -146,6 +166,8 @@ npm run test:coverage | Area | Coverage | |------|----------| | **Game logic** (gameLogic, gameUtils, gateSystem, spiritSystem, questSystem) | 97-100% | +| **Achievements** (achievementSystem — unlock conditions, categories) | Full coverage | +| **Statistics** (statsTracker — combat tracking, play time, counters) | Full coverage | | **React components** (ErrorBoundary, Stats, DailyQuest, ActivityLog) | Render + interaction tests | | **Server** (MemStorage CRUD) | Full interface coverage | | **Schema** (Zod validation) | All insert schemas validated | @@ -155,10 +177,12 @@ npm run test:coverage Tests are colocated next to their source files: ``` -gameLogic.ts → gameLogic.test.ts -gateSystem.ts → gateSystem.test.ts -Stats.tsx → Stats.test.tsx -storage.ts → storage.test.ts +gameLogic.ts → gameLogic.test.ts +gateSystem.ts → gateSystem.test.ts +achievementSystem.ts → achievementSystem.test.ts +statsTracker.ts → statsTracker.test.ts +Stats.tsx → Stats.test.tsx +storage.ts → storage.test.ts ``` ## Deployment @@ -178,6 +202,16 @@ npm run build # Upload dist/public/ to any static host ``` +## Generated Assets + +Audio is generated locally rather than sourced from asset packs: + +- **Music** — `scripts/generate-music-ai.py` uses Meta's MusicGen model to produce ambient, combat, victory, and defeat tracks +- **SFX** — `scripts/generate-sfx.py` synthesizes attack, heal, level-up, gate-enter, and other sound effects via numpy/scipy +- **Fallback** — `scripts/generate-music.py` provides procedural music generation when a GPU isn't available + +Run `python scripts/generate-music-ai.py` to regenerate music (requires a CUDA GPU and the `audiocraft` package). + ## Game Mechanics Reference ### Power Formula diff --git a/docs/plans/release-plan.md b/docs/plans/release-plan.md index bfbfceb..25ff116 100644 --- a/docs/plans/release-plan.md +++ b/docs/plans/release-plan.md @@ -2,15 +2,21 @@ ## Current State Assessment -**Status: Playable prototype with solid game mechanics, missing production infrastructure.** +**Status: Path A complete. Free web game with full feature set shipping on GitHub Pages.** ### What Works Well - Core gameplay loop: combat math, spirit binding, daily quests, fatigue, prestige/rebirth -- localStorage save/load with autosave, offline gains, and save migration -- PWA with offline play (minus audio) +- localStorage save/load with autosave, offline gains, save migration, and corruption recovery +- Save export/import (JSON backup/restore) +- Tutorial system for new players +- Achievement system (25+ achievements across 4 categories) +- Statistics dashboard (combat tracking, play time) +- Settings panel (audio controls, save management) +- AI-generated music (MusicGen) and synthesized SFX +- PWA with offline play and audio - Mobile-responsive layout with bottom tab navigation -- 165 passing tests covering core game logic at 97-100% coverage -- GitHub Pages deployment via GitHub Actions +- 215 passing tests across 13 files covering core game logic at 97-100% coverage +- GitHub Pages deployment via GitHub Actions with CI pipeline ### What's Missing @@ -18,17 +24,17 @@ 1. **5,292-line monolith** (`HuntersPath.tsx`) — unsustainable for future development 2. **No server-side persistence** — backend is scaffolding with zero working endpoints 3. **Shallow content** — ~2-4 hours to S-Rank, then prestige loop. Needs 50+ hours -4. **Audio is 16-byte stubs** — procedural fallback generates chip-tune beeps -5. **7 console.log statements** left in production code +4. ~~**Audio is 16-byte stubs** — procedural fallback generates chip-tune beeps~~ Done — AI-generated music + synthesized SFX +5. ~~**7 console.log statements** left in production code~~ Done — cleaned up #### Tier 2: Expected for Public Release -- Settings/options screen (volume, data export, save management) -- Onboarding/tutorial for new players -- Achievement system (schema exists, not implemented) -- Statistics dashboard (playerStats table exists, unused) -- Save import/export (critical for localStorage-only game) +- ~~Settings/options screen (volume, data export, save management)~~ Done +- ~~Onboarding/tutorial for new players~~ Done +- ~~Achievement system (schema exists, not implemented)~~ Done — 25+ achievements across 4 categories +- ~~Statistics dashboard (playerStats table exists, unused)~~ Done +- ~~Save import/export (critical for localStorage-only game)~~ Done - Accessibility (keyboard nav, screen reader labels, colorblind mode) -- Save corruption recovery +- ~~Save corruption recovery~~ Done — rotating backups #### Tier 3: Competitive Differentiation - Deeper prestige layers (2-3 tiers instead of 1) @@ -41,17 +47,19 @@ ## Release Strategy -### Path A: Free Web Game (Target: 2-3 weeks) -Ship on GitHub Pages + itch.io as a free browser game. +### Path A: Free Web Game — COMPLETE +Shipped on GitHub Pages as a free browser game. -1. Clean up console.logs and debug artifacts -2. Add save export/import (JSON download/upload) -3. Add tutorial overlay for first-time players -4. Generate real audio with local AI models (ComfyUI LTX audio VAE) -5. Add settings panel -6. Implement achievements -7. Document that saves are local-only -8. Submit to itch.io, r/incremental_games +1. ~~Clean up console.logs and debug artifacts~~ Done +2. ~~Add save export/import (JSON download/upload)~~ Done +3. ~~Add tutorial overlay for first-time players~~ Done +4. ~~Generate real audio with local AI models (MusicGen + synthesized SFX)~~ Done +5. ~~Add settings panel~~ Done +6. ~~Implement achievements (25+ across 4 categories)~~ Done +7. ~~Implement statistics dashboard~~ Done +8. ~~Add save corruption recovery with rotating backups~~ Done +9. ~~CI pipeline with 215 tests~~ Done +10. Submit to itch.io, r/incremental_games ### Path B: Full Release with Backend (6-8 weeks after Path A) 1. Implement auth (Passport is in package.json) @@ -88,9 +96,9 @@ Ship on GitHub Pages + itch.io as a free browser game. - UI elements as SVGs - All are simple/stylized — consistent art direction -### Current Audio (all 16-byte stubs) -- 15 SFX: attack, block, critical, damage, defeat, binding_*, gate_enter, heal, level_up, rest, rune_use, victory -- 4 music tracks: ambient, combat, defeat, victory +### Audio (generated) +- 15 SFX: attack, block, critical, damage, defeat, binding_*, gate_enter, heal, level_up, rest, rune_use, victory — synthesized via `scripts/generate-sfx.py` +- 4 music tracks: ambient, combat, defeat, victory — generated via MusicGen (`scripts/generate-music-ai.py`) ---