46e7420395
- Define campaign loop: Clubs → Leaders → Medals → Grand Masters → Champion - Update PROJECT_PLAN with campaign as core experience, multiplayer as optional - Add Campaign Structure section to GAME_RULES with clubs, NPCs, rewards - Reorganize development phases to prioritize campaign mode - Update CLAUDE.md project overview and uv commands
15 KiB
15 KiB
Mantimon TCG - Project Plan
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
| Attribute | Value |
|---|---|
| Project Name | Mantimon TCG (placeholder) |
| Frontend | Vue 3 + Phaser 3 (hybrid architecture) |
| Backend | FastAPI + PostgreSQL + Socket.io |
| Target Audience | 10-100 concurrent users |
| Timeline | Hobby project, no deadline |
| Card Acquisition | Packs (gacha) + direct crafting |
| 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
- Engaging Campaign: RPG-style progression with memorable NPC opponents
- Faithful TCG Experience: Card-based gameplay with strategic depth
- Visual Polish: Animated card interactions, shuffle effects, pack opening experience
- Flexible Rules Engine: Support home-rule modifications without code changes
- Collection System: Pack opening, crafting, deck building
- Optional Multiplayer: PvP for players who want competitive play
High-Level Architecture
+----------------------------------------------------------------------+
| Vue 3 / Nuxt App |
+----------------------------------------------------------------------+
| Pages (Vue/DOM-based) | Game View (Phaser Canvas) |
| +----------------------------+ | +----------------------------+ |
| | - Login/Register | | | - Card rendering | |
| | - 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 |
| - auth store, collection store, deck store, game store |
+----------------------------------------------------------------------+
| Socket.io Client + REST API |
+----------------------------------------------------------------------+
|
WebSocket + HTTP
|
+----------------------------------------------------------------------+
| FastAPI Backend |
+----------------------------------------------------------------------+
| REST Endpoints | WebSocket Handlers |
| - /auth/* | - game:action (play card, attack, etc) |
| - /cards/* (card data) | - game:state (sync) |
| - /collection/* | - matchmaking:* |
| - /decks/* | - lobby:* |
| - /packs/* (open packs) | |
| - /puzzles/* | |
+----------------------------------------------------------------------+
| Core Game Engine |
| +----------------------------------------------------------------+ |
| | - Turn state machine (Draw -> Main -> Attack -> End) | |
| | - Card effect resolver | |
| | - Rule validator (home rules configuration) | |
| | - Win condition checker | |
| | - AI decision engine (Easy/Medium/Hard) | |
| | - Puzzle scenario loader | |
| +----------------------------------------------------------------+ |
+----------------------------------------------------------------------+
| PostgreSQL | Redis |
| - Users/auth | - Active game state |
| - Card definitions | - Session cache |
| - Collections | - Matchmaking queue |
| - Decks | |
| - Match history | |
| - Campaign progress | |
| - NPC/Club definitions | |
+----------------------------------------------------------------------+
Development Phases
Phase 1: Foundation (Core Gameplay)
Goal: Get a single match working end-to-end.
| Task | Description |
|---|---|
| Card data model | Define schema for cards (attacks, HP, type, energy costs, effects) |
| Game state model | Zones: deck, hand, active, bench, prizes, discard |
| Turn state machine | Draw -> Attach energy -> Play cards -> Attack -> End |
| Basic rule engine | Energy attachment, retreat, attack resolution, knockouts |
| Phaser game scene | Render board, cards in hand, drag-to-play |
| Local 2-player | Hot-seat mode for testing |
Milestone: Two humans can play a basic match with a small card set (10-20 cards)
Phase 2: Multiplayer Infrastructure
Goal: Connect two remote players.
| Task | Description |
|---|---|
| WebSocket game sync | Server-authoritative state, hidden info filtering |
| Matchmaking (basic) | Queue system, pair two players |
| Turn timer | Optional time limits per turn |
| Reconnection | Rejoin in-progress games |
| Lobby UI | See available matches, challenge friends |
Milestone: Two players can match online and complete a game
Phase 3: Collection & Deck Building
Goal: Enable the constructed format.
| Task | Description |
|---|---|
| User collection model | Track which cards each user owns (with quantities) |
| Deck builder UI | Vue-based, filter/search, drag to deck |
| Deck validation | Enforce home rules (card limits, restrictions) |
| Starter collection | New accounts get basic cards |
| Card browser | View all cards in the game |
Milestone: Players can build decks from their collection and use them in matches
Phase 4: Card Acquisition
Goal: Packs and crafting system.
| Task | Description |
|---|---|
| Pack definitions | Which cards in which packs, rarity weights |
| Pack opening (backend) | Secure RNG, award cards |
| Pack opening (UI) | Animated Phaser scene with card reveals |
| Currency system | Earned currency from wins/quests |
| Crafting/dust | Disenchant duplicates, craft specific cards |
Milestone: Players can earn/open packs and craft cards
Phase 5: Campaign Mode (Core Experience)
Goal: Implement the RPG-style single-player campaign.
| Task | Description |
|---|---|
| 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: Player can progress through clubs, defeat leaders, earn medals
Phase 6: AI Opponents
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 progression | Unlock sequences, categories |
Milestone: Players can solve puzzles like "Win this turn"
Phase 8: Polish & Extended Features
| Task | Description |
|---|---|
| Match history | Review past games |
| 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 |
Key Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Vue + Phaser integration | Mount Phaser as Vue component | Keep forms/menus in Vue, canvas gameplay in Phaser |
| Pack opening | Phaser scene | Allows for animated card reveals with pizazz |
| Deck builder | Vue-based | Form-heavy UI, filtering, better accessibility |
| Card effect system | Data-driven with scripted effects | JSON defines cards, effect IDs map to handler functions |
| AI architecture | Strategy pattern per difficulty | Easy to add new AI types, same interface |
| Hidden info | Server never sends opponent's hand/deck | Prevents cheating even if client is compromised |
| State sync | Full state on reconnect, deltas during play | Balance bandwidth vs. complexity |
Complexity Estimates
| Component | Effort | Notes |
|---|---|---|
| Phaser game scene | High | Most time-intensive frontend work |
| Card effect system | High | Complex cards need flexible effect resolution |
| AI (Hard difficulty) | High | MCTS/minimax is non-trivial |
| Turn state machine | Medium | Similar patterns to other game projects |
| Collection/decks | Medium | CRUD with validation |
| Pack opening animation | Medium | Fun Phaser work, moderate complexity |
| Puzzles | Low-Medium | Subset of game engine, fixed states |
Directory Structure
mantimon-tcg/
├── PROJECT_PLAN.md # This file
├── CLAUDE.md # AI agent guidelines
├── docs/
│ ├── ARCHITECTURE.md # Technical deep-dive
│ └── GAME_RULES.md # Home rule documentation
├── frontend/ # Vue 3 + Phaser 3 application
│ ├── src/
│ │ ├── components/ # Vue components
│ │ ├── pages/ # Route pages
│ │ ├── stores/ # Pinia stores
│ │ ├── game/ # Phaser scenes and game objects
│ │ ├── composables/ # Vue composables (useWebSocket, etc.)
│ │ └── assets/ # Images, sounds
│ └── package.json
├── backend/ # FastAPI application
│ ├── app/
│ │ ├── api/ # REST endpoints
│ │ ├── core/ # Game engine
│ │ ├── models/ # Pydantic + SQLAlchemy models
│ │ ├── services/ # Business logic
│ │ └── websocket/ # Socket.io handlers
│ └── pyproject.toml
└── shared/ # Shared types/schemas (if needed)
Open Questions / Future Decisions
- Authentication method (Discord OAuth like baseball app? Email/password? Both?)
- Card art storage (local assets vs. CDN vs. external URLs?)
- Mobile app (PWA sufficient? Or native wrapper later?)
- Monetization (if any - cosmetics, premium packs, etc.)
- Tournament/event system for organized play