Skip to content

Commit a8454bd

Browse files
rgardler-msftrgardler-msft
committed
Merge branch 'wl-CG-0MLX1YHCS0FH8BB1-game-selector-docs' - Game Selector Integration & Docs for Lost Cities
2 parents a659ce7 + 7b473d9 commit a8454bd

File tree

2 files changed

+195
-14
lines changed

2 files changed

+195
-14
lines changed

‎README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,12 @@ tableau-card-engine/
3232
├── example-games/ Standalone example games
3333
│ ├── hello-world/ Minimal Phaser scene (toolchain proof)
3434
│ ├── golf/ 9-Card Golf (human vs. AI)
35-
│ └── beleaguered-castle/ Beleaguered Castle (open solitaire)
35+
│ ├── beleaguered-castle/ Beleaguered Castle (open solitaire)
36+
│ ├── sushi-go/ Sushi Go! (card drafting, human vs. AI)
37+
│ ├── splendor/ Splendor (engine-building, human vs. AI)
38+
│ └── lost-cities/ Lost Cities (2-player expedition lanes, human vs. AI)
3639
├── public/assets/ Static assets (cards, fonts, images)
37-
│ └── cards/ 52 card face SVGs + card back (140x190px)
40+
│ └── cards/ 52 standard card SVGs + card back + game-specific cards (140x190px)
3841
├── tests/ Vitest test files
3942
├── docs/ Developer documentation
4043
│ └── DEVELOPER.md Detailed developer guide
@@ -63,8 +66,11 @@ tableau-card-engine/
6366
| Hello World | `example-games/hello-world/` | Minimal Phaser scene with card sprites -- proves the toolchain works |
6467
| 9-Card Golf | `example-games/golf/` | Single-round 9-Card Golf (human vs. AI) with card flip animations, greedy/random AI strategies, and JSON game transcripts |
6568
| Beleaguered Castle | `example-games/beleaguered-castle/` | Open solitaire with drag-and-drop, click-to-move, undo/redo, auto-move to foundations, auto-complete, win/loss detection, help panel, and JSON game transcripts |
69+
| Sushi Go! | `example-games/sushi-go/` | Card drafting game (human vs. AI). Pick and pass hands over 3 rounds, collect sets of sushi dishes, and score the most points |
70+
| Splendor | `example-games/splendor/` | Engine-building card game (human vs. AI). Collect gem tokens, purchase development cards for bonuses, attract nobles, and reach 15 prestige to win |
71+
| Lost Cities | `example-games/lost-cities/` | Two-player expedition card game (human vs. AI). Bet on up to 5 colored expeditions across a 3-round match with investment multipliers, ascending-play rules, and cumulative scoring |
6672

67-
More games are planned: Sushi Go!, Splendor, Lost Cities, The Mind, and Coloretto.
73+
More games are planned: The Mind and Coloretto.
6874

6975
## Contributing
7076

‎docs/DEVELOPER.md‎

Lines changed: 186 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ After this, every push to `main` will automatically deploy.
113113

114114
1. Check the **Actions** tab in the repository for the latest workflow run
115115
2. Visit `https://thewizardscode.github.io/Tableau-Card-Engine/` to confirm the site loads
116-
3. Verify both games (9-Card Golf, Beleaguered Castle) are playable and card assets load correctly
116+
3. Verify all games (9-Card Golf, Beleaguered Castle, Sushi Go!, Splendor, Lost Cities) are playable and card assets load correctly
117117

118118
## Testing
119119

@@ -215,26 +215,61 @@ example-games/
215215
│ ├── GameTranscript.ts Transcript recording (TranscriptRecorder)
216216
│ └── scenes/
217217
│ └── GolfScene.ts Phaser scene (full visual interface)
218-
└── beleaguered-castle/
219-
├── main.ts Game entry point
220-
├── createBeleagueredCastleGame.ts Factory function (used by main.ts)
221-
├── BeleagueredCastleState.ts State types, move types, constants
222-
├── BeleagueredCastleRules.ts Pure game logic (deal, moves, win/loss)
223-
├── GameTranscript.ts Transcript recording (BCTranscriptRecorder)
224-
├── help-content.json Help panel content (rules, controls, tips)
218+
├── beleaguered-castle/
219+
│ ├── main.ts Game entry point
220+
│ ├── createBeleagueredCastleGame.ts Factory function (used by main.ts)
221+
│ ├── BeleagueredCastleState.ts State types, move types, constants
222+
│ ├── BeleagueredCastleRules.ts Pure game logic (deal, moves, win/loss)
223+
│ ├── GameTranscript.ts Transcript recording (BCTranscriptRecorder)
224+
│ ├── help-content.json Help panel content (rules, controls, tips)
225+
│ └── scenes/
226+
│ └── BeleagueredCastleScene.ts Phaser scene (full visual interface)
227+
├── sushi-go/
228+
│ ├── main.ts Game entry point
229+
│ ├── createSushiGoGame.ts Factory function (used by main.ts and tests)
230+
│ ├── SushiGoCards.ts Card types, deck creation, card-back texture generation
231+
│ ├── SushiGoGame.ts Game orchestration (drafting rounds, scoring)
232+
│ ├── SushiGoScoring.ts Set-collection scoring rules (Maki, Tempura, etc.)
233+
│ ├── AiStrategy.ts AI strategies (RandomStrategy, GreedyStrategy)
234+
│ ├── help-content.json Help panel content
235+
│ └── scenes/
236+
│ └── SushiGoScene.ts Phaser scene (drafting UI, card picking)
237+
├── splendor/
238+
│ ├── main.ts Game entry point
239+
│ ├── createSplendorGame.ts Factory function (used by main.ts and tests)
240+
│ ├── SplendorCards.ts Development cards, nobles, gem types, tier data
241+
│ ├── SplendorGame.ts Game orchestration (token collection, purchases, nobles)
242+
│ ├── AiStrategy.ts AI strategies (RandomStrategy, GreedyStrategy)
243+
│ ├── help-content.json Help panel content
244+
│ └── scenes/
245+
│ └── SplendorScene.ts Phaser scene (gem tokens, card market, purchases)
246+
└── lost-cities/
247+
├── LostCitiesCards.ts Card types, deck factory, 5 expedition colors, card helpers
248+
├── LostCitiesRules.ts Two-phase turn model, ascending-play validation, legality checks
249+
├── LostCitiesScoring.ts Expedition scoring (-20 base, investments, 8-card bonus)
250+
├── LostCitiesGame.ts Match manager (3-round session, executeAction, state queries)
251+
├── AiStrategy.ts AI strategies (RandomStrategy, GreedyStrategy)
252+
├── GameTranscript.ts Transcript recording (LCTranscriptRecorder)
253+
├── help-content.json Help panel content (rules, scoring, controls)
225254
└── scenes/
226-
└── BeleagueredCastleScene.ts Phaser scene (full visual interface)
255+
├── LostCitiesMockScene.ts Static layout mockup (development aid)
256+
└── LostCitiesScene.ts Phaser scene (interactive play with animations)
227257
228258
public/assets/
229-
├── cards/ 52 card face SVGs + card_back.svg (140x190px, CC0)
259+
├── cards/ 52 standard card SVGs + card_back.svg (140x190px, CC0)
260+
│ └── lost-cities/ 60 Lost Cities expedition card SVGs + lc-back.svg (140x190px)
230261
└── CREDITS.md Asset attribution
231262
232263
tests/
233264
├── smoke.test.ts Toolchain smoke test
234265
├── card-system/ Card, Deck, Pile unit tests
235266
├── core-engine/ GameState, TurnSequencer, UndoRedoManager unit tests
236267
├── golf/ Golf game unit + integration + browser tests
237-
└── beleaguered-castle/ Beleaguered Castle unit + integration tests
268+
├── beleaguered-castle/ Beleaguered Castle unit + integration tests
269+
├── sushi-go/ Sushi Go! cards, scoring, game, AI tests
270+
├── splendor/ Splendor cards, game, AI tests
271+
├── lost-cities/ Lost Cities cards, scoring, rules, game, AI, transcript tests
272+
└── replay/ Replay CLI validation tests
238273
```
239274

240275
Each `src/` module has a barrel file (`index.ts`) that serves as its public API. Import engine modules using path aliases (see below).
@@ -363,6 +398,146 @@ Tests are in `tests/beleaguered-castle/`:
363398
| `BeleagueredCastleRules.test.ts` | Deal correctness, move legality, foundation builds, win/loss detection, undo, auto-move heuristics, auto-complete (70 tests) |
364399
| `Integration.test.ts` | Full greedy game play across seeds, game invariants, undo/redo across moves, transcript recording and validation, auto-complete verification, snapshot utilities (30 tests) |
365400

401+
## Sushi Go!
402+
403+
Sushi Go! is a card drafting game demonstrating:
404+
405+
- **Card drafting**: Pick one card from a hand, pass the rest, repeat until hands are exhausted
406+
- **Custom card types**: Non-standard cards representing sushi dishes (Tempura, Sashimi, Maki Rolls, Nigiri, Wasabi, Dumplings, Pudding, Chopsticks)
407+
- **Multi-round match**: 3-round game with inter-round scoring and Pudding scored only at game end
408+
- **Set-collection scoring**: Different scoring functions per card type
409+
- **AI strategies**: Random (valid picks) and Greedy (highest-value pick)
410+
411+
### Running Sushi Go!
412+
413+
```bash
414+
npm run dev
415+
```
416+
417+
Open `http://localhost:3000` and click the **Sushi Go!** card on the game selector page.
418+
419+
### Sushi Go! game files
420+
421+
| File | Purpose |
422+
|------|---------|
423+
| `example-games/sushi-go/main.ts` | Phaser game config entry point |
424+
| `example-games/sushi-go/createSushiGoGame.ts` | Factory function for tests |
425+
| `example-games/sushi-go/SushiGoCards.ts` | Card types, deck creation, procedural card-back textures |
426+
| `example-games/sushi-go/SushiGoGame.ts` | Game orchestration (drafting rounds, hand passing, scoring) |
427+
| `example-games/sushi-go/SushiGoScoring.ts` | Set-collection scoring rules per card type |
428+
| `example-games/sushi-go/AiStrategy.ts` | AI strategies (RandomStrategy, GreedyStrategy) |
429+
| `example-games/sushi-go/help-content.json` | Help panel content |
430+
| `example-games/sushi-go/scenes/SushiGoScene.ts` | Phaser scene (drafting interface) |
431+
432+
### Sushi Go! tests
433+
434+
Tests are in `tests/sushi-go/`:
435+
436+
| File | Tests |
437+
|------|-------|
438+
| `SushiGoCards.test.ts` | Card types, deck creation, card counts (19 tests) |
439+
| `SushiGoScoring.test.ts` | All card type scoring rules (56 tests) |
440+
| `SushiGoGame.test.ts` | Game setup, drafting, round progression (21 tests) |
441+
| `AiStrategy.test.ts` | Random and Greedy strategy validation (15 tests) |
442+
443+
## Splendor
444+
445+
Splendor is an engine-building card game demonstrating:
446+
447+
- **Resource management**: Collect gem tokens to purchase development cards
448+
- **Custom card types**: Development cards with costs, gem bonuses, and prestige points across 3 tiers
449+
- **Noble attraction**: Automatically attract noble tiles when development card bonuses meet thresholds
450+
- **Multi-action turns**: Take gems, reserve cards, or purchase developments
451+
- **AI strategies**: Random (valid actions) and Greedy (prioritizes purchases and high-value cards)
452+
453+
### Running Splendor
454+
455+
```bash
456+
npm run dev
457+
```
458+
459+
Open `http://localhost:3000` and click the **Splendor** card on the game selector page.
460+
461+
### Splendor game files
462+
463+
| File | Purpose |
464+
|------|---------|
465+
| `example-games/splendor/main.ts` | Phaser game config entry point |
466+
| `example-games/splendor/createSplendorGame.ts` | Factory function for tests |
467+
| `example-games/splendor/SplendorCards.ts` | Development cards, nobles, gem types, tier data |
468+
| `example-games/splendor/SplendorGame.ts` | Game orchestration (token collection, purchases, nobles, win detection) |
469+
| `example-games/splendor/AiStrategy.ts` | AI strategies (RandomStrategy, GreedyStrategy) |
470+
| `example-games/splendor/help-content.json` | Help panel content |
471+
| `example-games/splendor/scenes/SplendorScene.ts` | Phaser scene (gem market, card tiers, token UI) |
472+
473+
### Splendor tests
474+
475+
Tests are in `tests/splendor/`:
476+
477+
| File | Tests |
478+
|------|-------|
479+
| `SplendorCards.test.ts` | Card data, noble data, gem types (50 tests) |
480+
| `SplendorGame.test.ts` | Game setup, turn execution, win detection, noble attraction (55 tests) |
481+
| `AiStrategy.test.ts` | Random and Greedy strategy validation (14 tests) |
482+
483+
## Lost Cities
484+
485+
Lost Cities is a two-player expedition card game demonstrating:
486+
487+
- **Custom card types**: 60 cards across 5 expedition colors (yellow, blue, white, green, red) with investment cards and ranks 2-10
488+
- **Custom SVG assets**: 61 procedurally generated SVG card images (60 cards + card back) at 140x190px
489+
- **Two-phase turn model**: Each turn consists of a play/discard phase followed by a draw phase
490+
- **Ascending-play rules**: Cards must be played in ascending order on expedition lanes; investment cards must be played before any numbered cards
491+
- **Multi-round match**: 3-round match with cumulative scoring across rounds
492+
- **Investment multipliers**: 1/2/3 investment cards multiply expedition score by x2/x3/x4
493+
- **AI strategies**: Random (valid moves) and Greedy (discard-aware, avoids giving opponent useful cards)
494+
- **Transcript recording**: Multi-round JSON transcripts capturing all actions and board states
495+
496+
### Running Lost Cities
497+
498+
```bash
499+
npm run dev
500+
```
501+
502+
Open `http://localhost:3000` and click the **Lost Cities** card on the game selector page. Select a card from your hand, then click an expedition lane to play or a discard pile to discard. Draw from the draw pile or a discard pile to complete your turn. The AI opponent plays automatically between your turns.
503+
504+
### Lost Cities game files
505+
506+
| File | Purpose |
507+
|------|---------|
508+
| `example-games/lost-cities/LostCitiesCards.ts` | Card types, deck factory, expedition colors, card helpers |
509+
| `example-games/lost-cities/LostCitiesRules.ts` | Two-phase turn model, ascending-play validation, legality checks |
510+
| `example-games/lost-cities/LostCitiesScoring.ts` | Expedition scoring (-20 base, card values, investment multiplier, 8-card bonus) |
511+
| `example-games/lost-cities/LostCitiesGame.ts` | Match manager (3-round session, executeAction, visible state, match lifecycle) |
512+
| `example-games/lost-cities/AiStrategy.ts` | AI strategies (RandomStrategy, GreedyStrategy, LostCitiesAiPlayer wrapper) |
513+
| `example-games/lost-cities/GameTranscript.ts` | Transcript recording (LCTranscriptRecorder, multi-round structure) |
514+
| `example-games/lost-cities/help-content.json` | Help panel content (8 sections: overview, scoring, controls, strategy tips) |
515+
| `example-games/lost-cities/scenes/LostCitiesScene.ts` | Phaser scene (interactive play with two-phase turns, animations, overlays) |
516+
| `example-games/lost-cities/scenes/LostCitiesMockScene.ts` | Static layout mockup (development aid) |
517+
518+
### Lost Cities card assets
519+
520+
The 61 SVG card images are generated by `scripts/generate-lost-cities-cards.ts`:
521+
522+
```bash
523+
npx tsx scripts/generate-lost-cities-cards.ts
524+
```
525+
526+
Assets are output to `public/assets/cards/lost-cities/` and documented in `public/assets/CREDITS.md`.
527+
528+
### Lost Cities tests
529+
530+
Tests are in `tests/lost-cities/`:
531+
532+
| File | Tests |
533+
|------|-------|
534+
| `lost-cities-cards.test.ts` | Card types, deck factory, helpers, uniqueness (44 tests) |
535+
| `lost-cities-scoring.test.ts` | Expedition scoring, round scoring, match scoring (26 tests) |
536+
| `lost-cities-rules.test.ts` | Turn phases, legality checks, legal action enumeration (32 tests) |
537+
| `lost-cities-game.test.ts` | Session setup, executeAction, round/match lifecycle (40 tests) |
538+
| `lost-cities-ai.test.ts` | Random and Greedy strategies, AI player wrapper (22 tests) |
539+
| `lost-cities-transcript.test.ts` | Transcript recording, full AI-vs-AI match validation (21 tests) |
540+
366541
## Managing Assets
367542

368543
- All assets go in `public/assets/` and are served by Vite at the `/assets/` URL path

0 commit comments

Comments
 (0)