cal/mantimon-tcg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add RPG campaign structure inspired by GBC Pokemon TCG

Browse Source 
- 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
This commit is contained in:
Cal Corum 2026-01-24 18:22:36 -06:00
parent 234e9a95c1
commit 46e7420395
3 changed files with 178 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
CLAUDE.md
View File

@ -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

127
PROJECT_PLAN.md
View File

@ -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 |
---

79
docs/GAME_RULES.md
View File

@ -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
---