oecs-sharp/docs/testing-games.md

# Testing games

1. Games are DLLs. Use a standalone test project to test a game.
2. Create baseline game snapshots in textual format. Save to files.
3. Create baseline logs via the R3 observable API. Save to files.
4. Read the snapshot/logs manually to identify issues.
5. Make sure serialization roundtrip works.

## Play tests

The goal of playtests is to execute a game with AI players and potentially
random seeds. Then the log/snapshots are read by the LLM agent to spot issues.

There is no failure in play tests; all tests pass but the agent should read the
log for reference.

AI players are not LLMs here; they are typically common game AI implementations.

Create static functions that analyze the game state and return a command. Each
such function is an agent. Each AI player routes its decisions to a random
agent in a pool of weighted agents.

Agents to consider:
- **Random:** evenly chooses every move randomly.
- **Greedy:** uses a specific way to score actions. Always chooses the one with
  highest score. There can be multiple Greedy agents with different scoring.

For each playtest attempt, generate a full game log, analyze and report what
you find from the log.

### Round Runner

Playtests should run multiple rounds, not just one. The recommended pattern:

```
while chips >= minimum_bet AND chips < 2× starting_chips:
    place bet → deal → agent decides hit/stand → resolve → new round
```

This exercises the full game lifecycle including deck reshuffling, round
transitions, and chip management. Safety cap at ~200 rounds to prevent
infinite loops.

### Play Log Format

Each play log should contain:
- **Header:** agent name, seed, result summary, win/loss/push counts.
- **Round Summaries:** per-round result, chip delta, hit count.
- **Decisions:** per-decision hand total and choice (Hit/Stand).
- **Reactivity:** raw R3 observable log of component/entity changes.
- **Final State:** snapshot of the world after all rounds.

Logs are saved as `.playlog` files alongside test output for manual review.
-												test: add unit tests for Blackjack and TicTacToe

- Add xUnit test projects for both games
- Implement game flow tests for Blackjack
- Implement game flow tests for TicTacToe
- Rename namespaces and projects to follow `Game.*` convention
- Add documentation for testing games

											
										
										
											2026-07-20 16:41:10 +08:00
+								# Testing games
-												docs: update documentation and implementation plan

Update the API surface and implementation plan to reflect architectural
changes, including new iterator overloads, system design refinements,
and the introduction of a source generator.

											
										
										
											2026-07-20 17:44:25 +08:00
+. Games are DLLs. Use a standalone test project to test a game.
-												feat(oecs): improve serialization and add snapshot tests

Enhance the OECS framework to support more robust component
deserialization during world serialization. This includes adding
boxed component support and a runtime fallback for component
discovery.

Additionally, introduces snapshot testing patterns for Blackjack
and TicTacToe to allow for manual verification of world state and
reactivity logs.

											
										
										
											2026-07-20 17:05:17 +08:00
+. Create baseline game snapshots in textual format. Save to files.
-												docs: update documentation and implementation plan

Update the API surface and implementation plan to reflect architectural
changes, including new iterator overloads, system design refinements,
and the introduction of a source generator.

											
										
										
											2026-07-20 17:44:25 +08:00
+. Create baseline logs via the R3 observable API. Save to files.
-												test: add unit tests for Blackjack and TicTacToe

- Add xUnit test projects for both games
- Implement game flow tests for Blackjack
- Implement game flow tests for TicTacToe
- Rename namespaces and projects to follow `Game.*` convention
- Add documentation for testing games

											
										
										
											2026-07-20 16:41:10 +08:00
+. Read the snapshot/logs manually to identify issues.
 . Make sure serialization roundtrip works.
-												feat(oecs): improve serialization and add snapshot tests

Enhance the OECS framework to support more robust component
deserialization during world serialization. This includes adding
boxed component support and a runtime fallback for component
discovery.

Additionally, introduces snapshot testing patterns for Blackjack
and TicTacToe to allow for manual verification of world state and
reactivity logs.

											
										
										
											2026-07-20 17:05:17 +08:00
 								## Play tests
-												docs: update documentation and implementation plan

Update the API surface and implementation plan to reflect architectural
changes, including new iterator overloads, system design refinements,
and the introduction of a source generator.

											
										
										
											2026-07-20 17:44:25 +08:00
+								The goal of playtests is to execute a game with AI players and potentially
 								random seeds. Then the log/snapshots are read by the LLM agent to spot issues.
-												test: add play tests for Blackjack and TicTacToe

Implement play tests for Blackjack and TicTacToe that simulate games
using various AI agents (Basic Strategy, Random, Greedy) and record
the results, decisions, and reactivity into playlogs for debugging
and LLM analysis. Update documentation to reflect the purpose of
these tests.

											
										
										
											2026-07-20 17:22:07 +08:00
-												docs: update documentation and implementation plan

Update the API surface and implementation plan to reflect architectural
changes, including new iterator overloads, system design refinements,
and the introduction of a source generator.

											
										
										
											2026-07-20 17:44:25 +08:00
+								There is no failure in play tests; all tests pass but the agent should read the
 								log for reference.
-												feat(oecs): improve serialization and add snapshot tests

Enhance the OECS framework to support more robust component
deserialization during world serialization. This includes adding
boxed component support and a runtime fallback for component
discovery.

Additionally, introduces snapshot testing patterns for Blackjack
and TicTacToe to allow for manual verification of world state and
reactivity logs.

											
										
										
											2026-07-20 17:05:17 +08:00
 								AI players are not LLMs here; they are typically common game AI implementations.
-												docs: update documentation and implementation plan

Update the API surface and implementation plan to reflect architectural
changes, including new iterator overloads, system design refinements,
and the introduction of a source generator.

											
										
										
											2026-07-20 17:44:25 +08:00
+								Create static functions that analyze the game state and return a command. Each
 								such function is an agent. Each AI player routes its decisions to a random
 								agent in a pool of weighted agents.
-												feat(oecs): improve serialization and add snapshot tests

Enhance the OECS framework to support more robust component
deserialization during world serialization. This includes adding
boxed component support and a runtime fallback for component
discovery.

Additionally, introduces snapshot testing patterns for Blackjack
and TicTacToe to allow for manual verification of world state and
reactivity logs.

											
										
										
											2026-07-20 17:05:17 +08:00
 								Agents to consider:
-												docs: update documentation and implementation plan

Update the API surface and implementation plan to reflect architectural
changes, including new iterator overloads, system design refinements,
and the introduction of a source generator.

											
										
										
											2026-07-20 17:44:25 +08:00
+								- **Random:** evenly chooses every move randomly.
 								- **Greedy:** uses a specific way to score actions. Always chooses the one with
 								  highest score. There can be multiple Greedy agents with different scoring.
-												test: add play tests for Blackjack and TicTacToe

Implement play tests for Blackjack and TicTacToe that simulate games
using various AI agents (Basic Strategy, Random, Greedy) and record
the results, decisions, and reactivity into playlogs for debugging
and LLM analysis. Update documentation to reflect the purpose of
these tests.

											
										
										
											2026-07-20 17:22:07 +08:00
-												docs: update documentation and implementation plan

Update the API surface and implementation plan to reflect architectural
changes, including new iterator overloads, system design refinements,
and the introduction of a source generator.

											
										
										
											2026-07-20 17:44:25 +08:00
+								For each playtest attempt, generate a full game log, analyze and report what
 								you find from the log.
 								### Round Runner
 								Playtests should run multiple rounds, not just one. The recommended pattern:
 								```
 								while chips >= minimum_bet AND chips < 2× starting_chips:
 								    place bet → deal → agent decides hit/stand → resolve → new round
 								```
 								This exercises the full game lifecycle including deck reshuffling, round
 								transitions, and chip management. Safety cap at ~200 rounds to prevent
 								infinite loops.
 								### Play Log Format
 								Each play log should contain:
 								- **Header:** agent name, seed, result summary, win/loss/push counts.
 								- **Round Summaries:** per-round result, chip delta, hit count.
 								- **Decisions:** per-decision hand total and choice (Hit/Stand).
 								- **Reactivity:** raw R3 observable log of component/entity changes.
 								- **Final State:** snapshot of the world after all rounds.
 								Logs are saved as `.playlog` files alongside test output for manual review.