diff --git a/CLAUDE.md b/CLAUDE.md index e8b83dd..b53559c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,18 +5,20 @@ Guidelines for AI coding agents working on this project. ## Quick Reference **Frontend dev server**: `cd frontend && npm run dev` -**Backend dev server**: `cd backend && uvicorn app.main:app --reload` +**Backend dev server**: `cd backend && uv run uvicorn app.main:app --reload` **Run frontend tests**: `cd frontend && npm run test` -**Run backend tests**: `cd backend && python -m pytest` +**Run backend tests**: `cd backend && uv run pytest` **Type check frontend**: `cd frontend && npm run typecheck` **Lint frontend**: `cd frontend && npm run lint` ## Project Overview -Mantimon TCG is a home-rule-modified Pokemon Trading Card Game web application featuring: -- Single-player (AI opponents, puzzle mode) -- Multiplayer (real-time matches) -- Collection system (packs, crafting, deck building) +Mantimon TCG is a home-rule-modified Pokemon Trading Card Game web application inspired by the Gameboy Color game *Pokemon TCG*. The core experience is a **single-player RPG campaign**: + +- **Campaign Mode**: Challenge NPCs at themed clubs, defeat Club Leaders to earn medals, collect all medals to face Grand Masters and become Champion +- **Collection Building**: Win matches to earn booster packs, build your card collection +- **Deck Building**: Construct decks from your collection to take on tougher opponents +- **Multiplayer (Optional)**: PvP matches for competitive play ## Tech Stack diff --git a/PROJECT_PLAN.md b/PROJECT_PLAN.md index e6728cf..1381c0b 100644 --- a/PROJECT_PLAN.md +++ b/PROJECT_PLAN.md @@ -1,6 +1,6 @@ # Mantimon TCG - Project Plan -A home-rule-modified Pokemon Trading Card Game implementation as a web application with single-player and multiplayer gameplay. +A home-rule-modified Pokemon Trading Card Game implementation as a web application, inspired by the Gameboy Color game *Pokemon Trading Card Game*. Players progress through a single-player RPG campaign, building their collection and challenging NPCs to become the champion, with optional multiplayer battles. ## Project Overview @@ -12,16 +12,70 @@ A home-rule-modified Pokemon Trading Card Game implementation as a web applicati | **Target Audience** | 10-100 concurrent users | | **Timeline** | Hobby project, no deadline | | **Card Acquisition** | Packs (gacha) + direct crafting | -| **AI Opponents** | Multiple difficulty tiers (Easy/Medium/Hard) | +| **AI Opponents** | NPC duelists with personalities and themed decks | | **Rule Basis** | Custom hybrid (modified energy, deck building, win conditions) | +| **Inspiration** | Pokemon TCG (Gameboy Color, 1998) | + +## Core Gameplay Loop + +The primary gameplay experience is a **single-player RPG campaign** inspired by the GBC Pokemon TCG game: + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ CAMPAIGN PROGRESSION │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ [Start] ──► Challenge NPCs ──► Win Matches ──► Earn Rewards │ +│ │ │ │ +│ ▼ ▼ │ +│ Build Collection ◄────────────── Open Packs │ +│ │ │ +│ ▼ │ +│ Improve Decks ──► Challenge Stronger NPCs │ +│ │ │ +│ ▼ │ +│ Defeat Club Leaders ──► Earn Medals │ +│ │ │ +│ ▼ │ +│ Challenge Grand Masters ──► Become Champion │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Campaign Structure + +| Element | Description | +|---------|-------------| +| **Clubs** | Themed locations (Fire Club, Water Club, etc.) with multiple NPCs | +| **Club Members** | Regular NPCs with themed decks, varying difficulty | +| **Club Leaders** | Boss battles that award medals upon defeat | +| **Grand Masters** | End-game opponents, must collect all medals to challenge | +| **Champion** | Final boss, winning grants champion title | + +### Progression Systems + +| System | Description | +|--------|-------------| +| **Medals** | Earned by defeating Club Leaders, required to face Grand Masters | +| **Packs** | Earned from victories, contain new cards for collection | +| **Deck Building** | Improve decks as collection grows | +| **NPC Difficulty** | Scales based on story progression | + +### Multiplayer (Secondary) + +While the campaign is the core experience, players can also: +- Challenge other players to PvP matches +- Trade cards (if implemented) +- Compare collections and rankings ## Goals -1. **Faithful TCG Experience**: Card-based gameplay with strategic depth -2. **Visual Polish**: Animated card interactions, shuffle effects, pack opening experience -3. **Flexible Rules Engine**: Support home-rule modifications without code changes -4. **Single & Multiplayer**: AI opponents, puzzles, and online PvP +1. **Engaging Campaign**: RPG-style progression with memorable NPC opponents +2. **Faithful TCG Experience**: Card-based gameplay with strategic depth +3. **Visual Polish**: Animated card interactions, shuffle effects, pack opening experience +4. **Flexible Rules Engine**: Support home-rule modifications without code changes 5. **Collection System**: Pack opening, crafting, deck building +6. **Optional Multiplayer**: PvP for players who want competitive play --- @@ -34,12 +88,12 @@ A home-rule-modified Pokemon Trading Card Game implementation as a web applicati | Pages (Vue/DOM-based) | Game View (Phaser Canvas) | | +----------------------------+ | +----------------------------+ | | | - Login/Register | | | - Card rendering | | -| | - Collection browser | | | - Hand management | | -| | - Deck builder | | | - Board zones (bench/active)| | -| | - Pack opening (Phaser) | | | - Drag-and-drop play | | -| | - Lobby/matchmaking | | | - Attack animations | | -| | - Profile/stats | | | - Shuffle/draw animations | | -| | - Puzzle select | | | - Damage counters | | +| | - World Map / Club Select | | | - Hand management | | +| | - NPC Dialog / Challenge | | | - Board zones (bench/active)| | +| | - Collection browser | | | - Drag-and-drop play | | +| | - Deck builder | | | - Attack animations | | +| | - Pack opening (Phaser) | | | - Shuffle/draw animations | | +| | - Profile/stats/medals | | | - Damage counters | | | +----------------------------+ | +----------------------------+ | +----------------------------------------------------------------------+ | Pinia State Management | @@ -77,7 +131,8 @@ A home-rule-modified Pokemon Trading Card Game implementation as a web applicati | - Collections | - Matchmaking queue | | - Decks | | | - Match history | | -| - Puzzle definitions | | +| - Campaign progress | | +| - NPC/Club definitions | | +----------------------------------------------------------------------+ ``` @@ -150,48 +205,66 @@ A home-rule-modified Pokemon Trading Card Game implementation as a web applicati --- -### Phase 5: AI Opponents +### Phase 5: Campaign Mode (Core Experience) -**Goal**: Single-player viability. +**Goal**: Implement the RPG-style single-player campaign. | Task | Description | |------|-------------| -| AI framework | Pluggable AI strategy interface | -| Easy AI | Random legal moves | -| Medium AI | Heuristic-based (prioritize knockouts, energy efficiency) | -| Hard AI | Minimax or MCTS with pruning | -| AI deck selection | Pre-built decks per difficulty | +| Club/NPC data model | Define clubs, NPCs, their decks, dialog, rewards | +| World map UI | Navigate between clubs, see available NPCs | +| NPC challenge flow | Dialog → deck select → match → rewards | +| Campaign progress tracking | Track defeated NPCs, earned medals, unlocks | +| Club Leaders | Boss NPCs with medals as rewards | +| Grand Masters | End-game opponents, require all medals | +| AI framework | NPC-specific AI behaviors and difficulty | -**Milestone**: Players can practice against AI at selectable difficulty +**Milestone**: Player can progress through clubs, defeat leaders, earn medals --- -### Phase 6: Puzzle Mode +### Phase 6: AI Opponents -**Goal**: Challenge scenarios. +**Goal**: Make NPC battles engaging and varied. + +| Task | Description | +|------|-------------| +| AI strategy interface | Pluggable AI behavior per NPC | +| Personality-based AI | NPCs have playstyle quirks (aggressive, defensive, etc.) | +| Difficulty scaling | NPCs get smarter as campaign progresses | +| Themed decks | Each NPC has a coherent deck strategy | +| Boss AI | Club Leaders and Grand Masters use advanced tactics | + +**Milestone**: NPCs feel distinct and appropriately challenging + +--- + +### Phase 7: Puzzle Mode (Optional) + +**Goal**: Challenge scenarios for variety. | Task | Description | |------|-------------| | Puzzle data model | Fixed board state, win condition, move limit | | Puzzle loader | Set up exact game state | | Puzzle validation | Check if solution is correct | -| Puzzle editor (optional) | Create puzzles in-app | | Puzzle progression | Unlock sequences, categories | **Milestone**: Players can solve puzzles like "Win this turn" --- -### Phase 7: Polish & Extended Features +### Phase 8: Polish & Extended Features | Task | Description | |------|-------------| | Match history | Review past games | -| Player stats | Win rate, favorite decks, etc. | -| Seasonal rewards | Ranked ladders, reward tracks | +| Player stats | Win rate, favorite decks, medals earned | +| Champion title | Special recognition for completing campaign | | Card effects system | Support complex abilities (abilities, trainers, etc.) | | Sound effects | Audio feedback for actions | | Mobile optimization | Touch controls, responsive layout | +| PvP matchmaking | Optional multiplayer for competitive players | --- diff --git a/docs/GAME_RULES.md b/docs/GAME_RULES.md index 83826fc..fb0f049 100644 --- a/docs/GAME_RULES.md +++ b/docs/GAME_RULES.md @@ -1,19 +1,80 @@ # Mantimon TCG - Game Rules -This document defines the home-rule modifications for Mantimon TCG, based on a custom hybrid of Pokemon TCG eras. +This document defines the home-rule modifications for Mantimon TCG, based on a custom hybrid of Pokemon TCG eras. The game features an RPG-style campaign inspired by the Gameboy Color *Pokemon Trading Card Game*. > **Note**: This is a template. Sections marked with `[TBD]` need to be filled in with your specific rule choices. ## Table of Contents -1. [Base Ruleset](#base-ruleset) -2. [Energy System Modifications](#energy-system-modifications) -3. [Deck Building Rules](#deck-building-rules) -4. [Win Conditions](#win-conditions) -5. [Turn Structure](#turn-structure) -6. [Card Types](#card-types) -7. [Status Conditions](#status-conditions) -8. [Glossary](#glossary) +1. [Campaign Structure](#campaign-structure) +2. [Base Ruleset](#base-ruleset) +3. [Energy System Modifications](#energy-system-modifications) +4. [Deck Building Rules](#deck-building-rules) +5. [Win Conditions](#win-conditions) +6. [Turn Structure](#turn-structure) +7. [Card Types](#card-types) +8. [Status Conditions](#status-conditions) +9. [Glossary](#glossary) + +--- + +## Campaign Structure + +The core gameplay loop is a single-player campaign where you challenge NPCs, build your collection, and progress toward becoming the champion. + +### Inspiration + +The campaign is inspired by **Pokemon Trading Card Game** for Gameboy Color (1998): +- Visit themed "Clubs" (Fire Club, Water Club, etc.) +- Challenge club members to earn booster packs +- Defeat Club Leaders to earn medals +- Collect all medals to challenge the Grand Masters +- Defeat the Grand Masters to become Champion + +### Clubs + +| Club | Theme | Leader | Medal | +|------|-------|--------|-------| +| [TBD] | Fire-type focused | [TBD] | [TBD] Medal | +| [TBD] | Water-type focused | [TBD] | [TBD] Medal | +| [TBD] | Grass-type focused | [TBD] | [TBD] Medal | +| [TBD] | Lightning-type focused | [TBD] | [TBD] Medal | +| [TBD] | Psychic-type focused | [TBD] | [TBD] Medal | +| [TBD] | Fighting-type focused | [TBD] | [TBD] Medal | +| [TBD] | Mixed/balanced | [TBD] | [TBD] Medal | +| [TBD] | Mixed/balanced | [TBD] | [TBD] Medal | + +### NPC Types + +| Type | Description | Rewards | +|------|-------------|---------| +| **Club Member** | Regular NPCs in each club | 1-2 booster packs | +| **Club Leader** | Boss of each club, must defeat to earn medal | Medal + 2-4 booster packs | +| **Grand Master** | Elite opponents, require all medals to challenge | Special rewards | +| **Champion** | Final opponent | Champion title | + +### Progression + +1. **New Player**: Start with a starter deck, can challenge any club +2. **Club Progression**: Defeat club members to practice, then challenge the leader +3. **Medal Collection**: Earn medals by defeating Club Leaders +4. **Grand Masters**: Once all medals collected, Grand Masters become available +5. **Champion**: Defeat all Grand Masters to face the Champion + +### Match Rewards + +| Outcome | Reward | +|---------|--------| +| Victory vs Club Member | 1-2 booster packs (based on NPC difficulty) | +| Victory vs Club Leader | Medal + 2-4 booster packs | +| Victory vs Grand Master | [TBD] special reward | +| Defeat | No reward, can retry immediately | + +### Rematch Rules + +- Club Members can be rechallenged anytime for pack rewards +- Club Leaders can be rechallenged after defeat (for packs, medal already earned) +- Grand Masters and Champion can be rechallenged for bragging rights ---