CLAUDE: Update documentation for GameState refactoring and X-Check testing
Updated CLAUDE.md files to document recent changes including the GameState
refactoring and new X-Check testing capabilities in the terminal client.
Changes to app/models/CLAUDE.md:
- Updated GameState field documentation
- Replaced current_batter_lineup_id references with current_batter
- Documented LineupPlayerState requirement for current players
- Added comprehensive usage examples
- Added "Recent Updates" section documenting GameState refactoring
- Before/after code examples showing migration path
- Explanation of why the change was made
- Migration notes for developers
- List of all affected files (7 files updated)
Changes to terminal_client/CLAUDE.md:
- Added "2025-11-04: X-Check Testing & GameState Refactoring" section
- New feature: resolve_with x-check <position> command
- Complete X-Check resolution with defense tables and error charts
- Shows all resolution steps with audit trail
- Works with actual player ratings from PD API
- Documented 8 X-Check commands now in help system
- roll_jump / test_jump, roll_fielding / test_fielding
- test_location, rollback, force_wild_pitch, force_passed_ball
- Bug fixes documented
- GameState structure updates (display.py, repl.py)
- Game recovery fix (state_manager.py)
- DO3 advancement fix (play_resolver.py)
- Complete testing workflow examples
- List of 7 files updated
- Test coverage status (all passing)
- Updated footer: Last Updated 2025-11-04
These documentation updates provide clear migration guides for the GameState
refactoring and comprehensive examples for the new X-Check testing features.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
76e01420a3
commit
c7b376df4f
@ -60,7 +60,7 @@ Complete in-memory representation of an active game. The heart of the game engin
|
||||
- **Game State**: `status`, `inning`, `half`, `outs`, `home_score`, `away_score`
|
||||
- **Runners**: `on_first`, `on_second`, `on_third` (direct LineupPlayerState references)
|
||||
- **Batting Order**: `away_team_batter_idx` (0-8), `home_team_batter_idx` (0-8)
|
||||
- **Play Snapshot**: `current_batter_lineup_id`, `current_pitcher_lineup_id`, `current_catcher_lineup_id`, `current_on_base_code`
|
||||
- **Current Players**: `current_batter` (LineupPlayerState, required), `current_pitcher` (Optional[LineupPlayerState]), `current_catcher` (Optional[LineupPlayerState]), `current_on_base_code`
|
||||
- **Decision Tracking**: `pending_decision`, `decisions_this_play`, `pending_defensive_decision`, `pending_offensive_decision`, `decision_phase`
|
||||
- **Manual Mode**: `pending_manual_roll` (AbRoll stored when dice rolled in manual mode)
|
||||
- **Play History**: `play_count`, `last_play_result`
|
||||
@ -75,22 +75,35 @@ Complete in-memory representation of an active game. The heart of the game engin
|
||||
```python
|
||||
from app.models import GameState, LineupPlayerState
|
||||
|
||||
# Create current batter (required field)
|
||||
current_batter = LineupPlayerState(
|
||||
lineup_id=10,
|
||||
card_id=100,
|
||||
position="CF",
|
||||
batting_order=1
|
||||
)
|
||||
|
||||
# Create game state
|
||||
state = GameState(
|
||||
game_id=uuid4(),
|
||||
league_id="sba",
|
||||
home_team_id=1,
|
||||
away_team_id=2,
|
||||
current_batter_lineup_id=10
|
||||
current_batter=current_batter # Required LineupPlayerState object
|
||||
)
|
||||
|
||||
# Add runner
|
||||
runner = LineupPlayerState(lineup_id=5, card_id=123, position="CF", batting_order=2)
|
||||
runner = LineupPlayerState(lineup_id=5, card_id=123, position="SS", batting_order=2)
|
||||
state.add_runner(runner, base=1)
|
||||
|
||||
# Advance runner and score
|
||||
state.advance_runner(from_base=1, to_base=4) # Auto-increments score
|
||||
|
||||
# Access current player info
|
||||
print(f"Current batter: {state.current_batter.lineup_id}")
|
||||
if state.current_pitcher:
|
||||
print(f"Current pitcher: {state.current_pitcher.lineup_id}")
|
||||
|
||||
# Check game over
|
||||
if state.is_game_over():
|
||||
state.status = "completed"
|
||||
@ -1064,6 +1077,62 @@ uv run pytest tests/unit/models/ --cov=app.models --cov-report=html
|
||||
|
||||
---
|
||||
|
||||
## Recent Updates
|
||||
|
||||
### GameState Refactoring (2025-11-04)
|
||||
|
||||
**Changed**: `current_batter`, `current_pitcher`, and `current_catcher` fields
|
||||
|
||||
**Before** (Old Structure):
|
||||
```python
|
||||
state = GameState(
|
||||
game_id=uuid4(),
|
||||
league_id="sba",
|
||||
home_team_id=1,
|
||||
away_team_id=2,
|
||||
current_batter_lineup_id=10 # Integer ID
|
||||
)
|
||||
# Access: state.current_batter_lineup_id
|
||||
```
|
||||
|
||||
**After** (New Structure):
|
||||
```python
|
||||
current_batter = LineupPlayerState(lineup_id=10, card_id=100, position="CF", batting_order=1)
|
||||
|
||||
state = GameState(
|
||||
game_id=uuid4(),
|
||||
league_id="sba",
|
||||
home_team_id=1,
|
||||
away_team_id=2,
|
||||
current_batter=current_batter # LineupPlayerState object (required)
|
||||
)
|
||||
# Access: state.current_batter.lineup_id
|
||||
```
|
||||
|
||||
**Why**:
|
||||
- More type-safe (full player context instead of just ID)
|
||||
- Enables position rating access during X-Check resolution
|
||||
- Matches pattern used for `on_first`, `on_second`, `on_third` runners
|
||||
- Simplifies game engine logic
|
||||
|
||||
**Migration Notes**:
|
||||
- `current_batter` is **required** (not Optional)
|
||||
- `current_pitcher` and `current_catcher` are **Optional[LineupPlayerState]**
|
||||
- All code accessing `state.current_batter_lineup_id` must change to `state.current_batter.lineup_id`
|
||||
- Game recovery creates placeholder `current_batter` from first active batter in lineup
|
||||
- `_prepare_next_play()` sets correct current players after recovery
|
||||
|
||||
**Affected Files**:
|
||||
- ✅ `app/models/game_models.py` - Model definition updated
|
||||
- ✅ `app/core/game_engine.py` - Uses new structure throughout
|
||||
- ✅ `app/core/state_manager.py` - Recovery creates placeholders
|
||||
- ✅ `app/core/runner_advancement.py` - All 17 references updated
|
||||
- ✅ `terminal_client/display.py` - Display updated
|
||||
- ✅ `terminal_client/repl.py` - Commands updated
|
||||
- ✅ All test files - Fixtures updated to create LineupPlayerState objects
|
||||
|
||||
---
|
||||
|
||||
## Design Rationale
|
||||
|
||||
### Why Separate Pydantic and SQLAlchemy Models?
|
||||
|
||||
@ -761,8 +761,90 @@ Automatically managed by:
|
||||
|
||||
---
|
||||
|
||||
### 2025-11-04: X-Check Testing & GameState Refactoring
|
||||
|
||||
**Major Update**: Added complete X-Check defensive play testing capabilities and fixed GameState structure.
|
||||
|
||||
**New Features**:
|
||||
|
||||
1. **X-Check Resolution Testing** - `resolve_with x-check <position>`
|
||||
- Test complete X-Check defensive plays with actual player ratings
|
||||
- Includes defense range tables, error charts, SPD tests, G2#/G3# conversions
|
||||
- Shows full XCheckResult audit trail with all resolution steps
|
||||
|
||||
```bash
|
||||
⚾ > defensive
|
||||
⚾ > offensive
|
||||
⚾ > resolve_with x-check SS # Test X-Check to shortstop
|
||||
⚾ > resolve_with x-check LF # Test X-Check to left field
|
||||
```
|
||||
|
||||
**What It Shows**:
|
||||
- Dice rolls (1d20 range + 3d6 error)
|
||||
- Defender ratings (range/error from PD API or defaults)
|
||||
- Defense table lookup (G1, G2, F3, SI2, DO3, etc.)
|
||||
- SPD test results (if applicable)
|
||||
- G2#/G3# conversion (playing in or holding runners)
|
||||
- Error chart lookup (NO, E1, E2, E3, RP)
|
||||
- Final outcome with error modifiers
|
||||
- Complete runner advancement
|
||||
|
||||
2. **X-Check Help Documentation** (8 commands documented)
|
||||
- `roll_jump` / `test_jump` - Stolen base jump dice testing
|
||||
- `roll_fielding` / `test_fielding` - Fielding dice testing
|
||||
- `test_location` - Hit location distribution testing
|
||||
- `rollback` - Undo plays
|
||||
- `force_wild_pitch` / `force_passed_ball` - Interrupt play testing
|
||||
- All commands now appear in `help` output
|
||||
|
||||
**Bug Fixes**:
|
||||
|
||||
1. **GameState Structure** - Updated for LineupPlayerState refactoring
|
||||
- `display.py`: Now accesses `state.current_batter.lineup_id` instead of `state.current_batter_lineup_id`
|
||||
- `repl.py`: Fixed typos (self.current_game → self.current_game_id)
|
||||
- All 105 terminal client tests passing
|
||||
|
||||
2. **Game Recovery** - Fixed validation error when loading saved games
|
||||
- State manager now creates placeholder `current_batter` during recovery
|
||||
- Placeholder is corrected by `_prepare_next_play()` after recovery
|
||||
|
||||
3. **DO3 Advancement** - Fixed incorrect batter advancement
|
||||
- DO3 now correctly: Batter reaches 2B (it's a double), runners advance 3 bases
|
||||
- Was incorrectly sending batter to 3B
|
||||
|
||||
**Testing Workflow**:
|
||||
```bash
|
||||
# Complete X-Check testing workflow
|
||||
⚾ > new_game
|
||||
⚾ > defensive --infield in # Set defensive positioning
|
||||
⚾ > offensive --approach power # Set offensive approach
|
||||
⚾ > resolve_with x-check 2B # Test X-Check to second base
|
||||
|
||||
# See complete resolution:
|
||||
# - Defense table: d20=15 + range=4 → G2
|
||||
# - Error chart: 3d6=8 vs error=12 → NO
|
||||
# - Final: G2 + NO = groundout to 2B
|
||||
# - Runner advancement based on G2 tables
|
||||
```
|
||||
|
||||
**Files Updated**:
|
||||
- `terminal_client/repl.py` - Added x-check parsing to resolve_with
|
||||
- `terminal_client/commands.py` - Added xcheck_position parameter
|
||||
- `terminal_client/help_text.py` - Documented 8 X-Check commands
|
||||
- `terminal_client/display.py` - Fixed GameState references
|
||||
- `app/core/game_engine.py` - Added xcheck_position support
|
||||
- `app/core/play_resolver.py` - Fixed DO3 batter advancement
|
||||
- `app/core/runner_advancement.py` - Updated all 17 GameState references
|
||||
|
||||
**Test Coverage**:
|
||||
- ✅ All 34 runner_advancement tests passing
|
||||
- ✅ All 105 terminal_client tests passing
|
||||
- ✅ All 26 state_manager tests passing
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-10-26
|
||||
**Author**: Claude
|
||||
**Purpose**: Testing tool for Phase 2 game engine development
|
||||
**Status**: ✅ Complete - Interactive REPL with persistent state working perfectly!
|
||||
**Last Updated**: 2025-10-28
|
||||
**Status**: ✅ Complete - Interactive REPL with persistent state and full X-Check testing!
|
||||
**Last Updated**: 2025-11-04
|
||||
|
||||
Loading…
Reference in New Issue
Block a user