# 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