5c75b935f0
Add comprehensive project documentation and Docker infrastructure for Paper Dynasty Real-Time Game Engine - a web-based multiplayer baseball simulation platform replacing the legacy Google Sheets system. Documentation Added: - Complete PRD (Product Requirements Document) - Project README with dual development workflows - Implementation guide with 5-phase roadmap - Architecture docs (backend, frontend, database, WebSocket) - CLAUDE.md context files for each major directory Infrastructure Added: - Root docker-compose.yml for full stack orchestration - Dockerfiles for backend and both frontends (multi-stage builds) - .dockerignore files for optimal build context - .env.example with all required configuration - Updated .gitignore for Python, Node, Nuxt, and Docker Project Structure: - backend/ - FastAPI + Socket.io game engine (Python 3.11+) - frontend-sba/ - SBA League Nuxt 3 frontend - frontend-pd/ - PD League Nuxt 3 frontend - .claude/implementation/ - Detailed implementation guides Supports two development workflows: 1. Local dev (recommended): Services run natively with hot-reload 2. Full Docker: One-command stack orchestration for testing/demos Next: Phase 1 implementation (backend/frontend foundations)
173 lines
5.2 KiB
Markdown
173 lines
5.2 KiB
Markdown
# Phase 2: Game Engine Core
|
|
|
|
**Duration**: Weeks 4-6
|
|
**Status**: Not Started
|
|
**Prerequisites**: Phase 1 Complete
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Build the core game simulation engine with in-memory state management, play resolution logic, and database persistence. Implement the polymorphic player model system and league configuration framework.
|
|
|
|
## Key Objectives
|
|
|
|
By end of Phase 2, you should have:
|
|
- ✅ In-memory game state management working
|
|
- ✅ Play resolution engine with dice rolls
|
|
- ✅ League configuration system (SBA and PD configs)
|
|
- ✅ Polymorphic player models (BasePlayer, SbaPlayer, PdPlayer)
|
|
- ✅ Database persistence layer with async operations
|
|
- ✅ State recovery mechanism from database
|
|
- ✅ Basic game flow (start → plays → end)
|
|
|
|
## Major Components to Implement
|
|
|
|
### 1. Game Engine (`backend/app/core/game_engine.py`)
|
|
- Game session initialization
|
|
- Turn management (defensive → stolen base → offensive → resolution)
|
|
- Action processing and validation
|
|
- State update coordination
|
|
- Event emission to WebSocket clients
|
|
|
|
### 2. State Manager (`backend/app/core/state_manager.py`)
|
|
- In-memory game state dictionary
|
|
- State CRUD operations
|
|
- State lifecycle management
|
|
- Cache eviction for idle games
|
|
- State recovery from database
|
|
|
|
### 3. Play Resolver (`backend/app/core/play_resolver.py`)
|
|
- Cryptographic dice rolling
|
|
- Result chart lookup (league-specific)
|
|
- Play outcome determination
|
|
- Runner advancement logic
|
|
- Score calculation
|
|
|
|
### 4. Dice System (`backend/app/core/dice.py`)
|
|
- Secure random number generation
|
|
- Roll logging and verification
|
|
- Distribution testing
|
|
|
|
### 5. Polymorphic Player Models (`backend/app/models/player_models.py`)
|
|
- BasePlayer abstract class
|
|
- SbaPlayer implementation
|
|
- PdPlayer implementation
|
|
- Lineup factory method
|
|
- Type guards for league-specific logic
|
|
|
|
### 6. League Configuration (`backend/app/config/`)
|
|
- BaseGameConfig class
|
|
- SbaConfig and PdConfig subclasses
|
|
- Result charts (d20 tables) for each league
|
|
- Config loader and versioning
|
|
- Config validation
|
|
|
|
### 7. Database Operations (`backend/app/database/operations.py`)
|
|
- Async play persistence
|
|
- Game metadata updates
|
|
- Lineup operations
|
|
- State snapshot management
|
|
- Bulk recovery queries
|
|
|
|
### 8. API Client (`backend/app/data/api_client.py`)
|
|
- HTTP client for league REST APIs
|
|
- Team data fetching
|
|
- Roster data fetching
|
|
- Player/card data fetching
|
|
- Error handling and retries
|
|
- Response caching (optional)
|
|
|
|
## Implementation Order
|
|
|
|
1. **Week 4**: State Manager + Database Operations
|
|
- In-memory state structure
|
|
- Basic CRUD operations
|
|
- Database persistence layer
|
|
- State recovery mechanism
|
|
|
|
2. **Week 5**: Game Engine + Play Resolver
|
|
- Game initialization flow
|
|
- Turn management
|
|
- Dice rolling system
|
|
- Basic play resolution (simplified charts)
|
|
|
|
3. **Week 6**: League Configs + Player Models
|
|
- Polymorphic player architecture
|
|
- League configuration system
|
|
- Complete result charts
|
|
- API client integration
|
|
- End-to-end testing
|
|
|
|
## Testing Strategy
|
|
|
|
### Unit Tests
|
|
- State manager operations
|
|
- Dice roll distribution
|
|
- Play resolver outcomes
|
|
- Player model instantiation
|
|
- Config loading
|
|
|
|
### Integration Tests
|
|
- Full game flow from start to end
|
|
- State recovery from database
|
|
- Multi-turn sequences
|
|
- API client with mocked responses
|
|
|
|
### E2E Tests
|
|
- Play a complete 9-inning game
|
|
- Verify database persistence
|
|
- Test state recovery mid-game
|
|
|
|
## Key Files to Create
|
|
|
|
```
|
|
backend/app/
|
|
├── core/
|
|
│ ├── game_engine.py # Main game logic
|
|
│ ├── state_manager.py # In-memory state
|
|
│ ├── play_resolver.py # Play outcomes
|
|
│ ├── dice.py # Random generation
|
|
│ └── validators.py # Rule validation
|
|
├── config/
|
|
│ ├── base_config.py # Base configuration
|
|
│ ├── league_configs.py # SBA/PD configs
|
|
│ ├── result_charts.py # d20 tables
|
|
│ └── loader.py # Config utilities
|
|
├── models/
|
|
│ ├── player_models.py # Polymorphic players
|
|
│ └── game_models.py # Pydantic game models
|
|
└── data/
|
|
└── api_client.py # League API client
|
|
```
|
|
|
|
## Reference Documents
|
|
|
|
- [Backend Architecture](./backend-architecture.md) - Complete backend structure
|
|
- [Database Design](./database-design.md) - Schema and queries
|
|
- [WebSocket Protocol](./websocket-protocol.md) - Event specifications
|
|
- [PRD Lines 378-551](../prd-web-scorecard-1.1.md) - Polymorphic player architecture
|
|
- [PRD Lines 780-846](../prd-web-scorecard-1.1.md) - League configuration system
|
|
|
|
## Deliverable
|
|
|
|
A working game backend that can:
|
|
- Initialize a game with teams from league APIs
|
|
- Process a complete at-bat (decisions → dice roll → outcome)
|
|
- Update game state in memory and persist to database
|
|
- Recover game state after backend restart
|
|
- Handle basic substitutions
|
|
|
|
## Notes
|
|
|
|
- Focus on getting one at-bat working perfectly before expanding
|
|
- Test dice roll distribution extensively
|
|
- Validate all state transitions
|
|
- Use simplified result charts initially, expand in Phase 3
|
|
- Don't implement UI yet - test via WebSocket events or Python scripts
|
|
|
|
---
|
|
|
|
**Status**: Placeholder - to be expanded during implementation
|
|
**Next Phase**: [03-gameplay-features.md](./03-gameplay-features.md)
|