Initial project setup: documentation and structure
- Add PROJECT_PLAN.md with 7-phase development roadmap - Add CLAUDE.md with AI agent coding guidelines - Add docs/ARCHITECTURE.md with technical deep-dive - Add docs/GAME_RULES.md template for home rule definitions - Create directory structure for frontend, backend, shared
This commit is contained in:
Cal Corum
commit
f473f94bce
309
CLAUDE.md
Normal file
309
CLAUDE.md
Normal file
@ -0,0 +1,309 @@
|
||||
# CLAUDE.md - Mantimon TCG
|
||||
|
||||
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`
|
||||
**Run frontend tests**: `cd frontend && npm run test`
|
||||
**Run backend tests**: `cd backend && python -m 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)
|
||||
|
||||
## Tech Stack
|
||||
|
||||
### Frontend
|
||||
| Technology | Purpose |
|
||||
|------------|---------|
|
||||
| Vue 3 | UI framework (Composition API + `<script setup>`) |
|
||||
| Phaser 3 | Game canvas (matches, pack opening) |
|
||||
| TypeScript | Type safety |
|
||||
| Pinia | State management |
|
||||
| Tailwind CSS | Styling |
|
||||
| Socket.io-client | Real-time communication |
|
||||
| Vite | Build tool |
|
||||
|
||||
### Backend
|
||||
| Technology | Purpose |
|
||||
|------------|---------|
|
||||
| FastAPI | REST API framework |
|
||||
| Python 3.11+ | Backend language |
|
||||
| SQLAlchemy 2.0 | ORM (async) |
|
||||
| PostgreSQL | Database |
|
||||
| Redis | Caching, session storage |
|
||||
| python-socketio | WebSocket server |
|
||||
| Pydantic v2 | Validation |
|
||||
| Alembic | Database migrations |
|
||||
|
||||
## Code Style
|
||||
|
||||
### General
|
||||
- Line length: 100 characters max
|
||||
- Indentation: 2 spaces (frontend), 4 spaces (backend)
|
||||
- Trailing commas in multi-line structures
|
||||
- Explicit over implicit
|
||||
|
||||
### TypeScript/Vue
|
||||
|
||||
```typescript
|
||||
// Imports: stdlib, third-party, local (separated by blank lines)
|
||||
import { ref, computed } from 'vue'
|
||||
|
||||
import { useGameStore } from '@/stores/game'
|
||||
import type { Card, GameState } from '@/types'
|
||||
|
||||
// Always use type imports for types
|
||||
import type { Player } from '@/types/player'
|
||||
|
||||
// Prefer const over let
|
||||
const cards = ref<Card[]>([])
|
||||
|
||||
// Use descriptive names
|
||||
const isPlayerTurn = computed(() => gameStore.currentPlayer === playerId)
|
||||
|
||||
// Component naming: PascalCase
|
||||
// File naming: PascalCase for components, camelCase for utilities
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
# Imports: stdlib, third-party, local (separated by blank lines)
|
||||
from typing import Optional
|
||||
|
||||
from fastapi import APIRouter, Depends
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.models import Card, Player
|
||||
from app.services.game_service import GameService
|
||||
|
||||
# Type hints required for all function signatures
|
||||
async def get_card(card_id: int, db: AsyncSession = Depends(get_db)) -> Card:
|
||||
...
|
||||
|
||||
# Use Pydantic models for request/response
|
||||
class PlayCardRequest(BaseModel):
|
||||
card_id: int
|
||||
target_id: Optional[int] = None
|
||||
|
||||
# Async by default for I/O operations
|
||||
async def resolve_attack(attacker: Card, defender: Card) -> AttackResult:
|
||||
...
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
| Type | Convention | Example |
|
||||
|------|------------|---------|
|
||||
| Vue components | PascalCase | `CardHand.vue`, `GameBoard.vue` |
|
||||
| Phaser scenes | PascalCase | `MatchScene.ts`, `PackOpeningScene.ts` |
|
||||
| TypeScript files | camelCase | `useWebSocket.ts`, `cardUtils.ts` |
|
||||
| Python modules | snake_case | `game_engine.py`, `card_service.py` |
|
||||
| Database tables | snake_case | `user_collections`, `match_history` |
|
||||
| Constants | UPPER_SNAKE_CASE | `MAX_HAND_SIZE`, `PRIZE_COUNT` |
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Frontend: Vue + Phaser Integration
|
||||
|
||||
Phaser is mounted as a Vue component. Communication happens via:
|
||||
|
||||
```typescript
|
||||
// In Vue component
|
||||
const phaserGame = ref<Phaser.Game | null>(null)
|
||||
|
||||
// Emit events to Phaser
|
||||
phaserGame.value?.events.emit('card:play', { cardId, targetId })
|
||||
|
||||
// Listen to events from Phaser
|
||||
phaserGame.value?.events.on('animation:complete', handleAnimationComplete)
|
||||
```
|
||||
|
||||
### Frontend: State Management
|
||||
|
||||
```typescript
|
||||
// Use Pinia stores for global state
|
||||
// stores/game.ts
|
||||
export const useGameStore = defineStore('game', () => {
|
||||
const gameState = ref<GameState | null>(null)
|
||||
const myHand = computed(() => gameState.value?.myHand ?? [])
|
||||
|
||||
function setGameState(state: GameState) {
|
||||
gameState.value = state
|
||||
}
|
||||
|
||||
return { gameState, myHand, setGameState }
|
||||
})
|
||||
```
|
||||
|
||||
### Backend: Service Layer
|
||||
|
||||
Never bypass services for business logic:
|
||||
|
||||
```python
|
||||
# CORRECT
|
||||
card = await card_service.get_card(card_id)
|
||||
result = await game_service.play_card(game_id, player_id, card_id)
|
||||
|
||||
# WRONG - direct DB access in endpoint
|
||||
card = await db.execute(select(Card).where(Card.id == card_id))
|
||||
```
|
||||
|
||||
### Backend: WebSocket Events
|
||||
|
||||
```python
|
||||
# All game actions go through WebSocket for real-time sync
|
||||
@sio.on('game:action')
|
||||
async def handle_game_action(sid, data):
|
||||
action_type = data['type']
|
||||
|
||||
# Validate action is legal
|
||||
validation = await game_engine.validate_action(game_id, player_id, data)
|
||||
if not validation.valid:
|
||||
await sio.emit('game:error', {'message': validation.reason}, to=sid)
|
||||
return
|
||||
|
||||
# Execute and broadcast
|
||||
new_state = await game_engine.execute_action(game_id, data)
|
||||
await broadcast_game_state(game_id, new_state)
|
||||
```
|
||||
|
||||
## Game Engine Patterns
|
||||
|
||||
### Card Effect System
|
||||
|
||||
Cards are data-driven. Effects reference handler functions:
|
||||
|
||||
```python
|
||||
# Card definition (JSON/DB)
|
||||
{
|
||||
"id": "pikachu_base_001",
|
||||
"name": "Pikachu",
|
||||
"hp": 60,
|
||||
"type": "lightning",
|
||||
"attacks": [
|
||||
{
|
||||
"name": "Thunder Shock",
|
||||
"cost": ["lightning"],
|
||||
"damage": 20,
|
||||
"effect": "may_paralyze", # References effect handler
|
||||
"effect_params": {"chance": 0.5}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
# Effect handler (Python)
|
||||
@effect_handler("may_paralyze")
|
||||
async def handle_may_paralyze(context: EffectContext, params: dict) -> None:
|
||||
if random.random() < params["chance"]:
|
||||
context.defender.add_status("paralyzed")
|
||||
```
|
||||
|
||||
### Turn State Machine
|
||||
|
||||
```python
|
||||
class TurnPhase(Enum):
|
||||
DRAW = "draw"
|
||||
MAIN = "main"
|
||||
ATTACK = "attack"
|
||||
END = "end"
|
||||
|
||||
# Transitions are explicit
|
||||
VALID_TRANSITIONS = {
|
||||
TurnPhase.DRAW: [TurnPhase.MAIN],
|
||||
TurnPhase.MAIN: [TurnPhase.ATTACK, TurnPhase.END], # Can skip attack
|
||||
TurnPhase.ATTACK: [TurnPhase.END],
|
||||
TurnPhase.END: [TurnPhase.DRAW], # Next player's turn
|
||||
}
|
||||
```
|
||||
|
||||
### Hidden Information
|
||||
|
||||
**Critical**: Server never sends hidden information to clients.
|
||||
|
||||
```python
|
||||
def get_visible_state(game: Game, player_id: str) -> VisibleGameState:
|
||||
return VisibleGameState(
|
||||
my_hand=game.players[player_id].hand, # Full hand
|
||||
my_prizes=game.players[player_id].prizes, # Can see own prizes
|
||||
my_deck_count=len(game.players[player_id].deck), # Only count
|
||||
|
||||
opponent_hand_count=len(opponent.hand), # ONLY count
|
||||
opponent_prizes_count=len(opponent.prizes), # ONLY count
|
||||
opponent_deck_count=len(opponent.deck), # ONLY count
|
||||
|
||||
battlefield=game.battlefield, # Public
|
||||
discard_piles=game.discard_piles, # Public
|
||||
)
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Frontend (Vitest)
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, vi } from 'vitest'
|
||||
import { mount } from '@vue/test-utils'
|
||||
import CardHand from '@/components/CardHand.vue'
|
||||
|
||||
describe('CardHand', () => {
|
||||
it('renders cards in hand', () => {
|
||||
const wrapper = mount(CardHand, {
|
||||
props: {
|
||||
cards: [{ id: '1', name: 'Pikachu' }]
|
||||
}
|
||||
})
|
||||
expect(wrapper.text()).toContain('Pikachu')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Backend (pytest)
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from app.core.game_engine import GameEngine
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_draw_card():
|
||||
"""
|
||||
Test that drawing a card moves it from deck to hand.
|
||||
|
||||
Verifies the fundamental draw mechanic works correctly
|
||||
and updates both zones appropriately.
|
||||
"""
|
||||
engine = GameEngine()
|
||||
game = await engine.create_game(player_ids=["p1", "p2"])
|
||||
|
||||
initial_deck_size = len(game.players["p1"].deck)
|
||||
initial_hand_size = len(game.players["p1"].hand)
|
||||
|
||||
await engine.draw_card(game, "p1")
|
||||
|
||||
assert len(game.players["p1"].deck) == initial_deck_size - 1
|
||||
assert len(game.players["p1"].hand) == initial_hand_size + 1
|
||||
```
|
||||
|
||||
## Directory-Specific Guidelines
|
||||
|
||||
See additional CLAUDE.md files in subdirectories:
|
||||
- `frontend/CLAUDE.md` - Vue/Phaser specifics
|
||||
- `backend/CLAUDE.md` - FastAPI/game engine specifics
|
||||
- `backend/app/core/CLAUDE.md` - Game engine architecture
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **Git**: Never commit directly to `main`. Create feature branches.
|
||||
2. **Hidden Info**: Never send deck contents, opponent hand, or unrevealed prizes to client.
|
||||
3. **Validation**: Always validate actions server-side. Never trust client.
|
||||
4. **Tests**: Include docstrings explaining "what" and "why" for each test.
|
||||
5. **Commits**: Do not commit without user approval.
|
||||
6. **Phaser in Vue**: Keep Phaser scenes focused on rendering. Game logic lives in backend.
|
||||
263
PROJECT_PLAN.md
Normal file
263
PROJECT_PLAN.md
Normal file
@ -0,0 +1,263 @@
|
||||
# Mantimon TCG - Project Plan
|
||||
|
||||
A home-rule-modified Pokemon Trading Card Game implementation as a web application with single-player and multiplayer gameplay.
|
||||
|
||||
## 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** | Multiple difficulty tiers (Easy/Medium/Hard) |
|
||||
| **Rule Basis** | Custom hybrid (modified energy, deck building, win conditions) |
|
||||
|
||||
## 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
|
||||
5. **Collection System**: Pack opening, crafting, deck building
|
||||
|
||||
---
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| Vue 3 / Nuxt App |
|
||||
+----------------------------------------------------------------------+
|
||||
| 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 | |
|
||||
| +----------------------------+ | +----------------------------+ |
|
||||
+----------------------------------------------------------------------+
|
||||
| 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 | |
|
||||
| - Puzzle 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: AI Opponents
|
||||
|
||||
**Goal**: Single-player viability.
|
||||
|
||||
| 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 |
|
||||
|
||||
**Milestone**: Players can practice against AI at selectable difficulty
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Puzzle Mode
|
||||
|
||||
**Goal**: Challenge scenarios.
|
||||
|
||||
| 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
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
| Match history | Review past games |
|
||||
| Player stats | Win rate, favorite decks, etc. |
|
||||
| Seasonal rewards | Ranked ladders, reward tracks |
|
||||
| Card effects system | Support complex abilities (abilities, trainers, etc.) |
|
||||
| Sound effects | Audio feedback for actions |
|
||||
| Mobile optimization | Touch controls, responsive layout |
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
822
docs/ARCHITECTURE.md
Normal file
822
docs/ARCHITECTURE.md
Normal file
@ -0,0 +1,822 @@
|
||||
# Mantimon TCG - Technical Architecture
|
||||
|
||||
This document provides a detailed technical overview of the Mantimon TCG architecture.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [System Overview](#system-overview)
|
||||
2. [Frontend Architecture](#frontend-architecture)
|
||||
3. [Backend Architecture](#backend-architecture)
|
||||
4. [Database Schema](#database-schema)
|
||||
5. [Real-Time Communication](#real-time-communication)
|
||||
6. [Game Engine](#game-engine)
|
||||
7. [AI System](#ai-system)
|
||||
8. [Security Considerations](#security-considerations)
|
||||
|
||||
---
|
||||
|
||||
## System Overview
|
||||
|
||||
```
|
||||
+------------------+ +------------------+ +------------------+
|
||||
| Browser | | Browser | | Browser |
|
||||
| (Vue + Phaser) | | (Vue + Phaser) | | (Vue + Phaser) |
|
||||
+--------+---------+ +--------+---------+ +--------+---------+
|
||||
| | |
|
||||
+------------------------+------------------------+
|
||||
|
|
||||
WebSocket + HTTP
|
||||
|
|
||||
+-------------+-------------+
|
||||
| |
|
||||
+--------v--------+ +--------v--------+
|
||||
| FastAPI | | FastAPI |
|
||||
| Instance 1 | | Instance 2 |
|
||||
+--------+--------+ +--------+--------+
|
||||
| |
|
||||
+-------------+-------------+
|
||||
|
|
||||
+-------------------+-------------------+
|
||||
| | |
|
||||
+-------v-------+ +-------v-------+ +------v------+
|
||||
| PostgreSQL | | Redis | | S3/CDN |
|
||||
| (persistent) | | (realtime) | | (card art) |
|
||||
+---------------+ +---------------+ +-------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend Architecture
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- **Vue 3** with Composition API and `<script setup>` syntax
|
||||
- **Phaser 3** for canvas-based game rendering
|
||||
- **TypeScript** for type safety
|
||||
- **Pinia** for state management
|
||||
- **Tailwind CSS** for styling
|
||||
- **Vite** for development and building
|
||||
|
||||
### Component Hierarchy
|
||||
|
||||
```
|
||||
App.vue
|
||||
├── layouts/
|
||||
│ ├── DefaultLayout.vue # Nav, footer for non-game pages
|
||||
│ └── GameLayout.vue # Minimal chrome for gameplay
|
||||
├── pages/
|
||||
│ ├── index.vue # Landing/home
|
||||
│ ├── login.vue # Authentication
|
||||
│ ├── collection.vue # Card collection browser
|
||||
│ ├── decks/
|
||||
│ │ ├── index.vue # Deck list
|
||||
│ │ └── [id].vue # Deck builder/editor
|
||||
│ ├── play/
|
||||
│ │ ├── index.vue # Play menu (AI, PvP, Puzzle)
|
||||
│ │ ├── match/[id].vue # Active game (mounts Phaser)
|
||||
│ │ └── puzzle/[id].vue # Puzzle mode
|
||||
│ ├── packs.vue # Pack opening (mounts Phaser)
|
||||
│ └── profile.vue # User stats and settings
|
||||
└── components/
|
||||
├── cards/
|
||||
│ ├── CardDisplay.vue # Single card render (DOM)
|
||||
│ ├── CardGrid.vue # Grid of cards
|
||||
│ └── CardDetail.vue # Full card modal
|
||||
├── decks/
|
||||
│ ├── DeckList.vue # List of user's decks
|
||||
│ └── DeckBuilder.vue # Deck editing UI
|
||||
├── game/
|
||||
│ └── PhaserContainer.vue # Mounts Phaser canvas
|
||||
└── common/
|
||||
├── Modal.vue
|
||||
├── Button.vue
|
||||
└── Loading.vue
|
||||
```
|
||||
|
||||
### Vue + Phaser Integration
|
||||
|
||||
Phaser is mounted within a Vue component and communicates via an event bridge:
|
||||
|
||||
```typescript
|
||||
// components/game/PhaserContainer.vue
|
||||
<script setup lang="ts">
|
||||
import { onMounted, onUnmounted, ref } from 'vue'
|
||||
import Phaser from 'phaser'
|
||||
import { MatchScene } from '@/game/scenes/MatchScene'
|
||||
import { useGameStore } from '@/stores/game'
|
||||
|
||||
const props = defineProps<{
|
||||
gameId: string
|
||||
}>()
|
||||
|
||||
const gameContainer = ref<HTMLDivElement>()
|
||||
const phaserGame = ref<Phaser.Game>()
|
||||
const gameStore = useGameStore()
|
||||
|
||||
onMounted(() => {
|
||||
phaserGame.value = new Phaser.Game({
|
||||
type: Phaser.AUTO,
|
||||
parent: gameContainer.value,
|
||||
width: 1280,
|
||||
height: 720,
|
||||
scene: [MatchScene],
|
||||
backgroundColor: '#1a1a2e',
|
||||
})
|
||||
|
||||
// Pass initial state to Phaser
|
||||
phaserGame.value.registry.set('gameId', props.gameId)
|
||||
|
||||
// Bridge: Vue -> Phaser
|
||||
gameStore.$onAction(({ name, args }) => {
|
||||
if (name === 'setGameState') {
|
||||
phaserGame.value?.events.emit('state:update', args[0])
|
||||
}
|
||||
})
|
||||
|
||||
// Bridge: Phaser -> Vue
|
||||
phaserGame.value.events.on('player:action', (action) => {
|
||||
gameStore.sendAction(action)
|
||||
})
|
||||
})
|
||||
|
||||
onUnmounted(() => {
|
||||
phaserGame.value?.destroy(true)
|
||||
})
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div ref="gameContainer" class="w-full h-full" />
|
||||
</template>
|
||||
```
|
||||
|
||||
### Phaser Scene Structure
|
||||
|
||||
```
|
||||
game/
|
||||
├── scenes/
|
||||
│ ├── MatchScene.ts # Main gameplay
|
||||
│ ├── PackOpeningScene.ts # Animated pack reveals
|
||||
│ └── PuzzleScene.ts # Puzzle mode
|
||||
├── objects/
|
||||
│ ├── Card.ts # Card game object
|
||||
│ ├── Hand.ts # Hand container
|
||||
│ ├── Battlefield.ts # Active/bench zones
|
||||
│ ├── Deck.ts # Deck pile with animations
|
||||
│ └── DamageCounter.ts # Damage display
|
||||
├── animations/
|
||||
│ ├── cardAnimations.ts # Draw, play, flip
|
||||
│ ├── attackAnimations.ts # Attack effects
|
||||
│ └── shuffleAnimations.ts # Deck shuffle
|
||||
└── utils/
|
||||
└── tweenHelpers.ts # Common tween patterns
|
||||
```
|
||||
|
||||
### State Management (Pinia)
|
||||
|
||||
```typescript
|
||||
// stores/game.ts
|
||||
export const useGameStore = defineStore('game', () => {
|
||||
// State
|
||||
const gameState = ref<GameState | null>(null)
|
||||
const pendingAction = ref<Action | null>(null)
|
||||
const socket = ref<Socket | null>(null)
|
||||
|
||||
// Getters
|
||||
const myHand = computed(() => gameState.value?.myHand ?? [])
|
||||
const isMyTurn = computed(() =>
|
||||
gameState.value?.currentPlayer === gameState.value?.myPlayerId
|
||||
)
|
||||
const canPlayCard = computed(() =>
|
||||
isMyTurn.value && gameState.value?.phase === 'main'
|
||||
)
|
||||
|
||||
// Actions
|
||||
async function connectToGame(gameId: string) {
|
||||
socket.value = io('/game', { query: { gameId } })
|
||||
|
||||
socket.value.on('game:state', (state) => {
|
||||
gameState.value = state
|
||||
})
|
||||
|
||||
socket.value.on('game:error', (error) => {
|
||||
// Handle error
|
||||
})
|
||||
}
|
||||
|
||||
function sendAction(action: Action) {
|
||||
socket.value?.emit('game:action', action)
|
||||
}
|
||||
|
||||
return {
|
||||
gameState,
|
||||
myHand,
|
||||
isMyTurn,
|
||||
canPlayCard,
|
||||
connectToGame,
|
||||
sendAction,
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Backend Architecture
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- **FastAPI** for REST API and WebSocket handling
|
||||
- **Python 3.11+** with async/await
|
||||
- **SQLAlchemy 2.0** (async) for ORM
|
||||
- **PostgreSQL** for persistent storage
|
||||
- **Redis** for caching and real-time state
|
||||
- **python-socketio** for WebSocket server
|
||||
- **Pydantic v2** for validation
|
||||
|
||||
### Module Structure
|
||||
|
||||
```
|
||||
backend/
|
||||
├── app/
|
||||
│ ├── main.py # FastAPI app, Socket.io setup
|
||||
│ ├── config.py # Settings (pydantic-settings)
|
||||
│ ├── dependencies.py # Dependency injection
|
||||
│ │
|
||||
│ ├── api/ # REST endpoints
|
||||
│ │ ├── auth.py # Login, register, OAuth
|
||||
│ │ ├── cards.py # Card definitions
|
||||
│ │ ├── collection.py # User collection CRUD
|
||||
│ │ ├── decks.py # Deck CRUD
|
||||
│ │ ├── packs.py # Pack opening
|
||||
│ │ ├── matchmaking.py # Queue management
|
||||
│ │ └── puzzles.py # Puzzle definitions
|
||||
│ │
|
||||
│ ├── websocket/ # Real-time handlers
|
||||
│ │ ├── handlers.py # Socket.io event handlers
|
||||
│ │ ├── connection_manager.py
|
||||
│ │ └── events.py # Event type definitions
|
||||
│ │
|
||||
│ ├── core/ # Game engine
|
||||
│ │ ├── game_engine.py # Main orchestrator
|
||||
│ │ ├── turn_manager.py # Turn/phase state machine
|
||||
│ │ ├── card_effects.py # Effect resolution
|
||||
│ │ ├── rules_validator.py # Action legality
|
||||
│ │ ├── win_conditions.py # Win/loss detection
|
||||
│ │ ├── state_manager.py # In-memory game state
|
||||
│ │ └── ai/ # AI opponents
|
||||
│ │ ├── base.py # AI interface
|
||||
│ │ ├── easy.py # Random legal moves
|
||||
│ │ ├── medium.py # Heuristic-based
|
||||
│ │ └── hard.py # MCTS/minimax
|
||||
│ │
|
||||
│ ├── models/ # Data models
|
||||
│ │ ├── database.py # SQLAlchemy models
|
||||
│ │ └── schemas.py # Pydantic schemas
|
||||
│ │
|
||||
│ ├── services/ # Business logic
|
||||
│ │ ├── auth_service.py
|
||||
│ │ ├── card_service.py
|
||||
│ │ ├── collection_service.py
|
||||
│ │ ├── deck_service.py
|
||||
│ │ ├── pack_service.py
|
||||
│ │ ├── game_service.py
|
||||
│ │ └── puzzle_service.py
|
||||
│ │
|
||||
│ └── database/ # DB utilities
|
||||
│ ├── session.py # Async session factory
|
||||
│ └── migrations/ # Alembic migrations
|
||||
│
|
||||
├── tests/
|
||||
│ ├── test_game_engine.py
|
||||
│ ├── test_card_effects.py
|
||||
│ ├── test_ai.py
|
||||
│ └── conftest.py
|
||||
│
|
||||
├── pyproject.toml
|
||||
└── alembic.ini
|
||||
```
|
||||
|
||||
### Request Flow
|
||||
|
||||
```
|
||||
HTTP Request
|
||||
│
|
||||
v
|
||||
FastAPI Router ─────────────────────────────┐
|
||||
│ │
|
||||
v v
|
||||
Dependency Injection WebSocket Connection
|
||||
(auth, db session) │
|
||||
│ v
|
||||
v Socket.io Handler
|
||||
Service Layer │
|
||||
│ v
|
||||
v Game Engine
|
||||
Repository/ORM (in-memory state)
|
||||
│ │
|
||||
v v
|
||||
PostgreSQL Redis
|
||||
(state cache)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Entity Relationship Diagram
|
||||
|
||||
```
|
||||
+---------------+ +------------------+ +---------------+
|
||||
| users | | collections | | cards |
|
||||
+---------------+ +------------------+ +---------------+
|
||||
| id (PK) |<──────| user_id (FK) | | id (PK) |
|
||||
| username | | card_id (FK) |───────| name |
|
||||
| email | | quantity | | set_id |
|
||||
| password_hash | +------------------+ | hp |
|
||||
| currency | | type |
|
||||
| created_at | | attacks (JSON)|
|
||||
+---------------+ | abilities |
|
||||
│ | rarity |
|
||||
│ +---------------+
|
||||
│
|
||||
│ +------------------+
|
||||
│ | decks |
|
||||
│ +------------------+
|
||||
└────────>| id (PK) |
|
||||
| user_id (FK) |
|
||||
| name |
|
||||
| cards (JSON) |
|
||||
| is_valid |
|
||||
| created_at |
|
||||
+------------------+
|
||||
|
||||
+------------------+ +------------------+
|
||||
| matches | | match_players |
|
||||
+------------------+ +------------------+
|
||||
| id (PK) |<──────| match_id (FK) |
|
||||
| status | | user_id (FK) |
|
||||
| winner_id (FK) | | deck_id (FK) |
|
||||
| started_at | | result |
|
||||
| ended_at | +------------------+
|
||||
| game_log (JSON) |
|
||||
+------------------+
|
||||
|
||||
+------------------+ +------------------+
|
||||
| packs | | pack_contents |
|
||||
+------------------+ +------------------+
|
||||
| id (PK) |<──────| pack_id (FK) |
|
||||
| name | | card_id (FK) |
|
||||
| cost | | rarity |
|
||||
| set_id | | weight |
|
||||
+------------------+ +------------------+
|
||||
|
||||
+------------------+
|
||||
| puzzles |
|
||||
+------------------+
|
||||
| id (PK) |
|
||||
| name |
|
||||
| description |
|
||||
| difficulty |
|
||||
| initial_state |
|
||||
| solution |
|
||||
| hints (JSON) |
|
||||
+------------------+
|
||||
```
|
||||
|
||||
### Key Models
|
||||
|
||||
```python
|
||||
# models/database.py
|
||||
from sqlalchemy import Column, Integer, String, JSON, ForeignKey, DateTime
|
||||
from sqlalchemy.orm import relationship
|
||||
from app.database.session import Base
|
||||
|
||||
class User(Base):
|
||||
__tablename__ = "users"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
username = Column(String(50), unique=True, nullable=False)
|
||||
email = Column(String(255), unique=True, nullable=False)
|
||||
password_hash = Column(String(255), nullable=False)
|
||||
currency = Column(Integer, default=0)
|
||||
created_at = Column(DateTime, server_default=func.now())
|
||||
|
||||
collections = relationship("Collection", back_populates="user")
|
||||
decks = relationship("Deck", back_populates="user")
|
||||
|
||||
|
||||
class Card(Base):
|
||||
__tablename__ = "cards"
|
||||
|
||||
id = Column(String(50), primary_key=True) # e.g., "pikachu_base_001"
|
||||
name = Column(String(100), nullable=False)
|
||||
set_id = Column(String(50), nullable=False)
|
||||
card_type = Column(String(20), nullable=False) # pokemon, trainer, energy
|
||||
hp = Column(Integer, nullable=True) # Only for Pokemon
|
||||
pokemon_type = Column(String(20), nullable=True) # fire, water, etc.
|
||||
attacks = Column(JSON, default=[])
|
||||
abilities = Column(JSON, default=[])
|
||||
weakness = Column(JSON, nullable=True)
|
||||
resistance = Column(JSON, nullable=True)
|
||||
retreat_cost = Column(Integer, default=0)
|
||||
rarity = Column(String(20), nullable=False)
|
||||
image_url = Column(String(500), nullable=True)
|
||||
|
||||
|
||||
class Deck(Base):
|
||||
__tablename__ = "decks"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
|
||||
name = Column(String(100), nullable=False)
|
||||
cards = Column(JSON, nullable=False) # [{"card_id": "...", "quantity": 2}, ...]
|
||||
is_valid = Column(Boolean, default=False)
|
||||
created_at = Column(DateTime, server_default=func.now())
|
||||
updated_at = Column(DateTime, onupdate=func.now())
|
||||
|
||||
user = relationship("User", back_populates="decks")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real-Time Communication
|
||||
|
||||
### Socket.io Events
|
||||
|
||||
#### Client -> Server
|
||||
|
||||
| Event | Payload | Description |
|
||||
|-------|---------|-------------|
|
||||
| `game:action` | `{ type, ...params }` | Player performs action |
|
||||
| `game:resign` | `{}` | Player resigns match |
|
||||
| `matchmaking:join` | `{ deckId }` | Join matchmaking queue |
|
||||
| `matchmaking:leave` | `{}` | Leave queue |
|
||||
|
||||
#### Server -> Client
|
||||
|
||||
| Event | Payload | Description |
|
||||
|-------|---------|-------------|
|
||||
| `game:state` | `VisibleGameState` | Full state update |
|
||||
| `game:action_result` | `{ success, error? }` | Action confirmation |
|
||||
| `game:ended` | `{ winner, reason }` | Match concluded |
|
||||
| `matchmaking:found` | `{ gameId, opponent }` | Match found |
|
||||
|
||||
### Action Types
|
||||
|
||||
```python
|
||||
class ActionType(str, Enum):
|
||||
PLAY_POKEMON = "play_pokemon" # Play basic Pokemon to bench
|
||||
EVOLVE = "evolve" # Evolve a Pokemon
|
||||
ATTACH_ENERGY = "attach_energy" # Attach energy card
|
||||
PLAY_TRAINER = "play_trainer" # Play trainer card
|
||||
USE_ABILITY = "use_ability" # Activate Pokemon ability
|
||||
ATTACK = "attack" # Declare attack
|
||||
RETREAT = "retreat" # Retreat active Pokemon
|
||||
PASS = "pass" # End turn / pass priority
|
||||
```
|
||||
|
||||
### State Synchronization
|
||||
|
||||
```python
|
||||
# websocket/handlers.py
|
||||
@sio.on('game:action')
|
||||
async def handle_action(sid, data: dict):
|
||||
session = await get_session(sid)
|
||||
game_id = session['game_id']
|
||||
player_id = session['player_id']
|
||||
|
||||
game = await state_manager.get_game(game_id)
|
||||
|
||||
# Validate
|
||||
result = await game_engine.validate_action(game, player_id, data)
|
||||
if not result.valid:
|
||||
await sio.emit('game:action_result', {
|
||||
'success': False,
|
||||
'error': result.reason
|
||||
}, to=sid)
|
||||
return
|
||||
|
||||
# Execute
|
||||
new_state = await game_engine.execute_action(game, player_id, data)
|
||||
await state_manager.save_game(game_id, new_state)
|
||||
|
||||
# Broadcast filtered state to each player
|
||||
for pid, psid in game.player_sockets.items():
|
||||
visible_state = game_engine.get_visible_state(new_state, pid)
|
||||
await sio.emit('game:state', visible_state, to=psid)
|
||||
|
||||
# Check win conditions
|
||||
winner = game_engine.check_win_condition(new_state)
|
||||
if winner:
|
||||
await handle_game_end(game_id, winner)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Game Engine
|
||||
|
||||
### Turn Structure
|
||||
|
||||
```
|
||||
GAME START
|
||||
│
|
||||
v
|
||||
┌─────────────────────────────────┐
|
||||
│ SETUP PHASE │
|
||||
│ - Draw 7 cards each │
|
||||
│ - Place active + bench │
|
||||
│ - Set aside 6 prize cards │
|
||||
│ - Flip coin for first turn │
|
||||
└─────────────────────────────────┘
|
||||
│
|
||||
v
|
||||
┌─────────────────────────────────┐
|
||||
│ TURN START │◄──────────────────┐
|
||||
│ - Draw 1 card │ │
|
||||
└─────────────────────────────────┘ │
|
||||
│ │
|
||||
v │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ MAIN PHASE (any order) │ │
|
||||
│ - Attach 1 energy (once) │ │
|
||||
│ - Play basic Pokemon to bench │ │
|
||||
│ - Evolve Pokemon │ │
|
||||
│ - Play trainer cards │ │
|
||||
│ - Use abilities │ │
|
||||
│ - Retreat active (once) │ │
|
||||
└─────────────────────────────────┘ │
|
||||
│ │
|
||||
v │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ ATTACK PHASE (optional) │ │
|
||||
│ - Declare attack │ │
|
||||
│ - Resolve damage + effects │ │
|
||||
│ - Check knockouts │ │
|
||||
│ - Take prize cards │ │
|
||||
└─────────────────────────────────┘ │
|
||||
│ │
|
||||
v │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ END PHASE │ │
|
||||
│ - Apply end-of-turn effects │ │
|
||||
│ - Switch to opponent │───────────────────┘
|
||||
└─────────────────────────────────┘
|
||||
│
|
||||
v
|
||||
┌─────────────────────────────────┐
|
||||
│ WIN CONDITION CHECK │
|
||||
│ - All prizes taken? │
|
||||
│ - Opponent has no Pokemon? │
|
||||
│ - Opponent can't draw? │
|
||||
│ - Custom home rules? │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Card Effect System
|
||||
|
||||
Effects are data-driven with pluggable handlers:
|
||||
|
||||
```python
|
||||
# core/card_effects.py
|
||||
from typing import Protocol, Callable, Dict, Any
|
||||
|
||||
class EffectContext:
|
||||
game: GameState
|
||||
source_card: Card
|
||||
source_player: str
|
||||
target_card: Optional[Card]
|
||||
target_player: Optional[str]
|
||||
params: Dict[str, Any]
|
||||
|
||||
EffectHandler = Callable[[EffectContext], Awaitable[None]]
|
||||
|
||||
EFFECT_REGISTRY: Dict[str, EffectHandler] = {}
|
||||
|
||||
def effect_handler(name: str):
|
||||
"""Decorator to register effect handlers."""
|
||||
def decorator(func: EffectHandler):
|
||||
EFFECT_REGISTRY[name] = func
|
||||
return func
|
||||
return decorator
|
||||
|
||||
# Example effects
|
||||
@effect_handler("deal_damage")
|
||||
async def deal_damage(ctx: EffectContext):
|
||||
amount = ctx.params["amount"]
|
||||
ctx.target_card.damage += amount
|
||||
|
||||
@effect_handler("heal")
|
||||
async def heal(ctx: EffectContext):
|
||||
amount = ctx.params["amount"]
|
||||
ctx.target_card.damage = max(0, ctx.target_card.damage - amount)
|
||||
|
||||
@effect_handler("apply_status")
|
||||
async def apply_status(ctx: EffectContext):
|
||||
status = ctx.params["status"] # paralyzed, poisoned, asleep, etc.
|
||||
ctx.target_card.status_conditions.append(status)
|
||||
|
||||
@effect_handler("draw_cards")
|
||||
async def draw_cards(ctx: EffectContext):
|
||||
count = ctx.params["count"]
|
||||
player = ctx.game.players[ctx.source_player]
|
||||
for _ in range(count):
|
||||
if player.deck:
|
||||
player.hand.append(player.deck.pop())
|
||||
|
||||
@effect_handler("coin_flip")
|
||||
async def coin_flip(ctx: EffectContext):
|
||||
"""Flip coin, execute sub-effect on heads."""
|
||||
result = random.choice(["heads", "tails"])
|
||||
if result == "heads" and "on_heads" in ctx.params:
|
||||
sub_effect = ctx.params["on_heads"]
|
||||
await resolve_effect(ctx.game, sub_effect, ctx)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI System
|
||||
|
||||
### Architecture
|
||||
|
||||
```python
|
||||
# core/ai/base.py
|
||||
from abc import ABC, abstractmethod
|
||||
|
||||
class AIPlayer(ABC):
|
||||
"""Base class for AI opponents."""
|
||||
|
||||
@abstractmethod
|
||||
async def choose_action(self, game_state: GameState) -> Action:
|
||||
"""Given the current game state, return the best action."""
|
||||
pass
|
||||
|
||||
def get_legal_actions(self, game_state: GameState) -> List[Action]:
|
||||
"""Returns all legal actions for the AI player."""
|
||||
actions = []
|
||||
player = game_state.players[self.player_id]
|
||||
|
||||
# Can attach energy?
|
||||
if not game_state.energy_attached_this_turn:
|
||||
for card in player.hand:
|
||||
if card.card_type == "energy":
|
||||
for target in self.get_energy_targets(game_state):
|
||||
actions.append(AttachEnergyAction(card.id, target.id))
|
||||
|
||||
# Can play Pokemon?
|
||||
for card in player.hand:
|
||||
if card.card_type == "pokemon" and card.stage == "basic":
|
||||
if len(player.bench) < 5:
|
||||
actions.append(PlayPokemonAction(card.id))
|
||||
|
||||
# ... more action types
|
||||
|
||||
actions.append(PassAction()) # Can always pass
|
||||
return actions
|
||||
```
|
||||
|
||||
### Difficulty Implementations
|
||||
|
||||
```python
|
||||
# core/ai/easy.py
|
||||
class EasyAI(AIPlayer):
|
||||
"""Random legal moves with basic priorities."""
|
||||
|
||||
async def choose_action(self, game_state: GameState) -> Action:
|
||||
actions = self.get_legal_actions(game_state)
|
||||
|
||||
# Slight preference: attack if possible
|
||||
attacks = [a for a in actions if isinstance(a, AttackAction)]
|
||||
if attacks and random.random() > 0.3:
|
||||
return random.choice(attacks)
|
||||
|
||||
return random.choice(actions)
|
||||
|
||||
|
||||
# core/ai/medium.py
|
||||
class MediumAI(AIPlayer):
|
||||
"""Heuristic-based decision making."""
|
||||
|
||||
async def choose_action(self, game_state: GameState) -> Action:
|
||||
actions = self.get_legal_actions(game_state)
|
||||
|
||||
# Score each action
|
||||
scored = [(self.score_action(game_state, a), a) for a in actions]
|
||||
scored.sort(reverse=True, key=lambda x: x[0])
|
||||
|
||||
# Pick top action with some randomness
|
||||
top_actions = [a for s, a in scored[:3]]
|
||||
return random.choice(top_actions)
|
||||
|
||||
def score_action(self, state: GameState, action: Action) -> float:
|
||||
score = 0.0
|
||||
|
||||
if isinstance(action, AttackAction):
|
||||
# Prefer knockouts
|
||||
damage = self.calculate_damage(state, action)
|
||||
target = state.get_defending_pokemon()
|
||||
if damage >= target.hp - target.damage:
|
||||
score += 100 # Knockout!
|
||||
else:
|
||||
score += damage * 0.5
|
||||
|
||||
elif isinstance(action, PlayPokemonAction):
|
||||
# Value bench presence
|
||||
score += 10
|
||||
|
||||
# ... more heuristics
|
||||
|
||||
return score
|
||||
|
||||
|
||||
# core/ai/hard.py
|
||||
class HardAI(AIPlayer):
|
||||
"""Monte Carlo Tree Search for strong play."""
|
||||
|
||||
def __init__(self, player_id: str, simulations: int = 1000):
|
||||
super().__init__(player_id)
|
||||
self.simulations = simulations
|
||||
|
||||
async def choose_action(self, game_state: GameState) -> Action:
|
||||
root = MCTSNode(game_state, None, self.player_id)
|
||||
|
||||
for _ in range(self.simulations):
|
||||
node = self.select(root)
|
||||
node = self.expand(node)
|
||||
result = self.simulate(node)
|
||||
self.backpropagate(node, result)
|
||||
|
||||
# Return most visited child's action
|
||||
best_child = max(root.children, key=lambda c: c.visits)
|
||||
return best_child.action
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Hidden Information
|
||||
|
||||
**Never expose to clients:**
|
||||
- Deck order (either player)
|
||||
- Opponent's hand contents
|
||||
- Unrevealed prize cards
|
||||
- RNG seeds or future random results
|
||||
|
||||
```python
|
||||
def get_visible_state(game: GameState, player_id: str) -> VisibleGameState:
|
||||
"""Filter game state to only what player can see."""
|
||||
opponent_id = get_opponent(game, player_id)
|
||||
|
||||
return VisibleGameState(
|
||||
# My full information
|
||||
my_hand=[card.to_dict() for card in game.players[player_id].hand],
|
||||
my_deck_count=len(game.players[player_id].deck),
|
||||
my_prizes=[
|
||||
card.to_dict() if card.revealed else {"hidden": True}
|
||||
for card in game.players[player_id].prizes
|
||||
],
|
||||
|
||||
# Opponent's hidden information
|
||||
opponent_hand_count=len(game.players[opponent_id].hand),
|
||||
opponent_deck_count=len(game.players[opponent_id].deck),
|
||||
opponent_prizes_remaining=len([
|
||||
p for p in game.players[opponent_id].prizes if not p.taken
|
||||
]),
|
||||
|
||||
# Public information
|
||||
battlefield=game.battlefield.to_dict(),
|
||||
discard_piles={
|
||||
pid: [card.to_dict() for card in player.discard]
|
||||
for pid, player in game.players.items()
|
||||
},
|
||||
current_turn=game.current_turn,
|
||||
phase=game.phase,
|
||||
)
|
||||
```
|
||||
|
||||
### Server Authority
|
||||
|
||||
- All game logic runs server-side
|
||||
- Client sends intentions, server validates and executes
|
||||
- Never trust client-provided game state
|
||||
- RNG uses `secrets` module for unpredictability
|
||||
|
||||
### Input Validation
|
||||
|
||||
```python
|
||||
async def validate_action(game: GameState, player_id: str, action: dict) -> ValidationResult:
|
||||
# Is it this player's turn?
|
||||
if game.current_turn != player_id:
|
||||
return ValidationResult(False, "Not your turn")
|
||||
|
||||
# Is this action type valid for current phase?
|
||||
action_type = action.get("type")
|
||||
if action_type not in VALID_ACTIONS_BY_PHASE[game.phase]:
|
||||
return ValidationResult(False, f"Cannot {action_type} during {game.phase}")
|
||||
|
||||
# Validate specific action requirements
|
||||
validator = ACTION_VALIDATORS.get(action_type)
|
||||
if validator:
|
||||
return await validator(game, player_id, action)
|
||||
|
||||
return ValidationResult(False, "Unknown action type")
|
||||
```
|
||||
324
docs/GAME_RULES.md
Normal file
324
docs/GAME_RULES.md
Normal file
@ -0,0 +1,324 @@
|
||||
# Mantimon TCG - Game Rules
|
||||
|
||||
This document defines the home-rule modifications for Mantimon TCG, based on a custom hybrid of Pokemon TCG eras.
|
||||
|
||||
> **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)
|
||||
|
||||
---
|
||||
|
||||
## Base Ruleset
|
||||
|
||||
Mantimon TCG uses a **custom hybrid** ruleset, cherry-picking mechanics from multiple Pokemon TCG eras.
|
||||
|
||||
### Era Influences
|
||||
|
||||
| Mechanic | Era Source | Notes |
|
||||
|----------|------------|-------|
|
||||
| Basic turn structure | Classic (Base-Neo) | [TBD] |
|
||||
| Pokemon stages | [TBD] | Basic, Stage 1, Stage 2, and/or EX/V variants? |
|
||||
| Trainer card types | [TBD] | Item/Supporter/Stadium split, or classic Trainer? |
|
||||
| Energy types | [TBD] | How many types? Special energy? |
|
||||
|
||||
### What's NOT Included
|
||||
|
||||
List of official mechanics that are explicitly excluded:
|
||||
|
||||
- [TBD] - e.g., "No VMAX or Gigantamax mechanics"
|
||||
- [TBD]
|
||||
- [TBD]
|
||||
|
||||
---
|
||||
|
||||
## Energy System Modifications
|
||||
|
||||
> **Home Rule Focus Area**: Energy attachment rules
|
||||
|
||||
### Standard Rule (for reference)
|
||||
|
||||
In standard Pokemon TCG, you may attach **one energy card** per turn from your hand to one of your Pokemon.
|
||||
|
||||
### Modified Rule
|
||||
|
||||
[TBD] - Describe your energy system changes here. Examples of possible modifications:
|
||||
|
||||
- [ ] **Multiple attachments**: Attach up to X energy per turn
|
||||
- [ ] **Type-free energy**: All basic energy counts as colorless
|
||||
- [ ] **Energy acceleration**: Specific cards/abilities that attach extra energy
|
||||
- [ ] **Energy generation**: Start of turn gain energy tokens instead of cards
|
||||
- [ ] **Shared energy pool**: Energy attached to a Pokemon can be used by bench
|
||||
- [ ] **No energy cards**: Attacks cost action points instead
|
||||
|
||||
### Energy Types in Use
|
||||
|
||||
| Type | Symbol | Description |
|
||||
|------|--------|-------------|
|
||||
| [TBD] | | |
|
||||
| [TBD] | | |
|
||||
| Colorless | | Any energy satisfies colorless requirements |
|
||||
|
||||
### Special Energy
|
||||
|
||||
| Name | Effect |
|
||||
|------|--------|
|
||||
| [TBD] | |
|
||||
| [TBD] | |
|
||||
|
||||
---
|
||||
|
||||
## Deck Building Rules
|
||||
|
||||
> **Home Rule Focus Area**: Card limits and restrictions
|
||||
|
||||
### Deck Size
|
||||
|
||||
| Rule | Value |
|
||||
|------|-------|
|
||||
| Minimum deck size | [TBD] cards |
|
||||
| Maximum deck size | [TBD] cards |
|
||||
| Exact size required? | [TBD] Yes/No |
|
||||
|
||||
### Card Limits
|
||||
|
||||
| Card Type | Max Copies | Notes |
|
||||
|-----------|------------|-------|
|
||||
| Pokemon (same name) | [TBD] | |
|
||||
| Trainer cards (same name) | [TBD] | |
|
||||
| Energy cards (basic, same type) | [TBD] | |
|
||||
| Energy cards (special, same name) | [TBD] | |
|
||||
|
||||
### Required Cards
|
||||
|
||||
| Requirement | Value |
|
||||
|-------------|-------|
|
||||
| Minimum Basic Pokemon | [TBD] |
|
||||
| Minimum Energy cards | [TBD] |
|
||||
| Other requirements | [TBD] |
|
||||
|
||||
### Banned/Restricted Cards
|
||||
|
||||
| Card Name | Status | Reason |
|
||||
|-----------|--------|--------|
|
||||
| [TBD] | Banned | |
|
||||
| [TBD] | Limited to 1 | |
|
||||
|
||||
### Format Rotations
|
||||
|
||||
[TBD] - Which card sets are legal? Do sets rotate out?
|
||||
|
||||
| Set Name | Set Code | Status |
|
||||
|----------|----------|--------|
|
||||
| [TBD] | | Legal |
|
||||
| [TBD] | | Banned |
|
||||
|
||||
---
|
||||
|
||||
## Win Conditions
|
||||
|
||||
> **Home Rule Focus Area**: Victory conditions
|
||||
|
||||
### Standard Win Conditions (for reference)
|
||||
|
||||
1. Take all 6 prize cards
|
||||
2. Knock out opponent's last Pokemon in play
|
||||
3. Opponent cannot draw at start of turn
|
||||
|
||||
### Modified Win Conditions
|
||||
|
||||
[TBD] - Describe your win condition changes. Examples:
|
||||
|
||||
- [ ] **Prize count change**: Take [X] prizes instead of 6
|
||||
- [ ] **Alternative victory**: Win by [condition]
|
||||
- [ ] **Removed condition**: [Which standard condition is removed?]
|
||||
- [ ] **Sudden death**: [Special rules for tiebreakers]
|
||||
|
||||
### Prize Card Rules
|
||||
|
||||
| Rule | Value |
|
||||
|------|-------|
|
||||
| Number of prizes | [TBD] |
|
||||
| Prizes taken per knockout | [TBD] - (Standard: 1 for basic, 2 for EX/V) |
|
||||
| Prize card selection | [TBD] - Random or chosen? |
|
||||
|
||||
---
|
||||
|
||||
## Turn Structure
|
||||
|
||||
### Turn Overview
|
||||
|
||||
```
|
||||
1. DRAW PHASE
|
||||
- Draw 1 card from deck
|
||||
|
||||
2. MAIN PHASE (any order, as many times as allowed)
|
||||
- Attach energy (once per turn) [TBD if modified]
|
||||
- Play Basic Pokemon to bench
|
||||
- Evolve Pokemon
|
||||
- Play Trainer cards
|
||||
- Use Abilities
|
||||
- Retreat Active Pokemon (once per turn)
|
||||
|
||||
3. ATTACK PHASE
|
||||
- Declare attack (ends turn)
|
||||
- OR pass without attacking
|
||||
|
||||
4. END PHASE
|
||||
- Apply end-of-turn effects
|
||||
- Check for knockouts
|
||||
- Take prize cards if applicable
|
||||
```
|
||||
|
||||
### Turn Modifications
|
||||
|
||||
[TBD] - Any changes to the turn structure?
|
||||
|
||||
| Modification | Description |
|
||||
|--------------|-------------|
|
||||
| [TBD] | |
|
||||
|
||||
### First Turn Rules
|
||||
|
||||
| Rule | Value |
|
||||
|------|-------|
|
||||
| First player draws on turn 1? | [TBD] Yes/No |
|
||||
| First player can attack turn 1? | [TBD] Yes/No |
|
||||
| First player can play Supporters turn 1? | [TBD] Yes/No |
|
||||
|
||||
---
|
||||
|
||||
## Card Types
|
||||
|
||||
### Pokemon Cards
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| Basic Pokemon | Can be played directly from hand to bench |
|
||||
| Stage 1 | Evolves from a Basic Pokemon |
|
||||
| Stage 2 | Evolves from a Stage 1 Pokemon |
|
||||
| [TBD] | [Any special Pokemon types like EX, V, etc.?] |
|
||||
|
||||
### Evolution Rules
|
||||
|
||||
| Rule | Value |
|
||||
|------|-------|
|
||||
| Can evolve same turn played? | No (unless card effect allows) |
|
||||
| Can evolve same turn as previous evolution? | [TBD] |
|
||||
| Evolution on first turn of game? | [TBD] |
|
||||
|
||||
### Trainer Cards
|
||||
|
||||
[TBD] - Which trainer card subtypes are in use?
|
||||
|
||||
| Type | Rules |
|
||||
|------|-------|
|
||||
| Item | [TBD] - Unlimited per turn? |
|
||||
| Supporter | [TBD] - One per turn? |
|
||||
| Stadium | [TBD] - Stays in play? |
|
||||
| Tool | [TBD] - Attach to Pokemon? |
|
||||
|
||||
### Energy Cards
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| Basic Energy | Provides 1 energy of its type |
|
||||
| Special Energy | [TBD] - Custom effects? |
|
||||
|
||||
---
|
||||
|
||||
## Status Conditions
|
||||
|
||||
### Active Status Conditions
|
||||
|
||||
| Condition | Effect | Removal |
|
||||
|-----------|--------|---------|
|
||||
| Poisoned | [TBD] damage between turns | [TBD] |
|
||||
| Burned | [TBD] damage + flip to continue | [TBD] |
|
||||
| Asleep | Cannot attack or retreat, flip to wake | [TBD] |
|
||||
| Paralyzed | Cannot attack or retreat for 1 turn | End of next turn |
|
||||
| Confused | Flip to attack, damage self on tails | [TBD] |
|
||||
|
||||
### Condition Stacking
|
||||
|
||||
[TBD] - Can multiple conditions be active? Which override others?
|
||||
|
||||
---
|
||||
|
||||
## Glossary
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| Active Pokemon | The Pokemon currently in the battle position |
|
||||
| Bench | Area for up to 5 Pokemon not currently active |
|
||||
| Discard Pile | Where knocked out Pokemon and used cards go |
|
||||
| Prize Cards | Cards set aside at game start, taken on knockouts |
|
||||
| Retreat | Switching active Pokemon with a benched Pokemon |
|
||||
| [TBD] | [Add game-specific terms] |
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
Track rule changes over time:
|
||||
|
||||
| Date | Change | Reason |
|
||||
|------|--------|--------|
|
||||
| [Date] | Initial rules document created | Project start |
|
||||
| | | |
|
||||
|
||||
---
|
||||
|
||||
## Notes for Implementation
|
||||
|
||||
This section is for developer reference when implementing rules in code.
|
||||
|
||||
### Rule Configuration Schema
|
||||
|
||||
Rules should be configurable via a JSON/YAML file for easy iteration:
|
||||
|
||||
```json
|
||||
{
|
||||
"deck": {
|
||||
"min_size": 60,
|
||||
"max_size": 60,
|
||||
"max_copies_per_card": 4,
|
||||
"min_basic_pokemon": 1
|
||||
},
|
||||
"prizes": {
|
||||
"count": 6,
|
||||
"per_knockout_basic": 1,
|
||||
"per_knockout_ex": 2
|
||||
},
|
||||
"energy": {
|
||||
"attachments_per_turn": 1
|
||||
},
|
||||
"first_turn": {
|
||||
"can_draw": true,
|
||||
"can_attack": false,
|
||||
"can_play_supporter": false
|
||||
},
|
||||
"win_conditions": {
|
||||
"all_prizes_taken": true,
|
||||
"no_pokemon_in_play": true,
|
||||
"cannot_draw": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Validation Hooks
|
||||
|
||||
When implementing rules engine, create validation hooks for:
|
||||
|
||||
- `validate_deck(deck) -> ValidationResult`
|
||||
- `validate_action(game_state, action) -> ValidationResult`
|
||||
- `check_win_conditions(game_state) -> Optional[WinResult]`
|
||||
- `calculate_prizes_for_knockout(pokemon) -> int`
|
||||
Loading…
Reference in New Issue
Block a user