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
337 lines
15 KiB
Markdown
337 lines
15 KiB
Markdown
# 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
|
|
|
|
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
|
|
|
|
---
|
|
|
|
## 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
|