GameEngines

This contains a game engine of a boardgame eerily similar to Carcassonne.

An LLM did the heavy lifting:

• I asked it to read the online rulebook and generate a digial version of the box, including analysing an image of the tiles and creating data structures to represent them.
• 10 personas were created with different difficulty levels and playing styles.
• The game engine is in python and can be run from command-line or there is a /game-player skill to run it via AI, if you're flush with tokens
• Each turn is logged and there is a brief post game analysis too
• I didn't personally read/write a single line of python. It's all vibing

What is lacking:

• No UI, its all text based
• Bot players decision making is poor (especiall for what should be advanced difficulties)
• No human player option

---

Example Turn Entries

Turn	Actor	Drawn Tile ID	Tile Description	Tile Orientation	Placed Coordinate	Meeple Placed?	Meeple Feature	Meeple Element / Segment	Completed Features Scored	Scores After
0	setup	tile-T25-01	Starting tile	0	(0,0)	no	N/A	N/A	none	black 0; yellow 0; red 0
1	black (Nora Field)	tile-T02-01	Monastery + road	90	(1,0)	yes	road R1	R1 on tile-T02-01	none	black 0; yellow 0; red 0
2	yellow (Alice Stone)	tile-T06-01	3-edge city + road	270	(-1,0)	yes	city C1	C1 on tile-T06-01	completed road from road (tile-T02-01, tile-T06-01, tile-T25-01); tiles=3; shields=0; open_edges=0; black scored 3	black 3; yellow 0; red 0
3	red (Theo Ashford)	tile-T16-01	Single city edge	180	(0,1)	yes	city C1	C1 on tile-T16-01	completed city from city (tile-T16-01, tile-T25-01); tiles=2; shields=0; open_edges=0; red scored 4	black 3; yellow 0; red 4

Example Post Game Summary

Pos	Player	Score	Roads	Cities	Monasteries	Fields	Incomplete
1	Nora Field (black)	23	3	6	0	0	14
2	Theo Ashford (red)	18	3	4	0	0	11
3	Alice Stone (yellow)	17	2	0	0	0	15

Prerequisites

• Python 3.10+
• No external packages required — the engine is dependency-free

Repository layout

/Carcassonne/
  carcassonne_engine.py   # engine, CLI, and all game logic
  personas.json           # 10 AI player profiles (difficulty, strategy, weights)
  rules-for-player.md     # human-readable rules reference

Games/Carcassonne/
  001/                    # played session
    game-state.json       # canonical game state (read/written by engine)
    game-log.md           # append-only Markdown audit log
  002/
    ...

---

Playing via AI

The /game-player skill sets up and plays games using the same Python functions as the CLI. Ask AI:

/game-player Start a new Carcassonne game with Nora, Alice, and Theo

or to continue an existing session:

/game-player Play the next 3 turns of Carcassonne game 002`

---

Playing via Command-line

All commands are run from the repository root.

1. Start a new game

python3 Carcassonne/carcassonne_engine.py new-game PLAYERS

PLAYERS is a comma-separated list of personas in turn order. Any of these forms work:

# Short numbers
python3 Carcassonne/carcassonne_engine.py new-game 1,3,10

# Full IDs
python3 Carcassonne/carcassonne_engine.py new-game persona-001,persona-003,persona-010

# Names (case-insensitive)
python3 Carcassonne/carcassonne_engine.py new-game "Nora Field,Alice Stone,Theo Ashford"

Optional flags:

• --seed 42 — reproducible random seed (default: auto-detected session index)
• --colors blue,red,black — explicit colors in turn order (default: auto-shuffled)
• --games-dir PATH — override the Games/Carcassonne/ directory

The command creates Games/Carcassonne/NNN/ (next available index) containing game-state.json and turn-log.md, and prints a summary.

2. Play turns

One turn:

python3 Carcassonne/carcassonne_engine.py play-turn

Multiple turns:

python3 Carcassonne/carcassonne_engine.py play-turn 5

Each turn: draws the next tile, chooses the best legal placement and optional meeple/farmer using the active persona's heuristics, updates game-state.json, and appends a row to turn-log.md.

Optional flags:

• --session PATH — explicit game-state.json path (default: latest session)
• --log PATH — explicit turn-log.md path (default: turn-log.md next to the session file)
• --current-state-out PATH — also regenerate a current-state.md human-readable snapshot

3. Play a full game to completion

python3 Carcassonne/carcassonne_engine.py auto-play --apply-final-score

Plays all remaining turns, then applies final scoring (incomplete features + field/farmer scoring). Prints a JSON summary with scores when done.

Optional flags: --session, --log, --turns N (cap), --current-state-out

4. Check scores

python3 Carcassonne/carcassonne_engine.py score

Prints current scores plus projected final scores (including incomplete features and fields).

5. View current state

python3 Carcassonne/carcassonne_engine.py state

Prints a human-readable Markdown table of the board, players, draw source, meeples, and feature networks.

---

All CLI commands

Command	Description
new-game PLAYERS	Create a new session (auto-detects next index)
play-turn [N]	Play N turns using persona heuristics (default: 1)
auto-play	Play until tiles exhausted
state	Print human-readable current state
score	Print current and projected final scores
legal-turn STATE	List all legal turn options for the active player
select-action STATE	Show which action the engine would choose next
apply-final-score STATE --out STATE	Apply end-game scoring and mark complete
remaining STATE	Tile deck report (remaining counts and order)
placements STATE TILE_ID	Valid placements for a specific tile
meeples STATE TILE_ID	Legal meeple/farmer placements on a placed tile
networks STATE	Analyze all road/city/monastery feature networks
write-current-state STATE --out PATH	Regenerate current-state.md on demand
write-log-header --out PATH	Write a fresh turn-log skeleton
init-session --engine-dir --session-dir --players --seed	Low-level session init with explicit JSON player data

All state/score/play-turn/auto-play commands auto-detect the latest session if --session is omitted.

---

Personas

Ten AI player personas are defined in Carcassonne/personas.json:

#	Name	Difficulty	Style
1	Nora Field	novice	Short roads, tiny cities, conservative
2	Ben Marsh	novice	Finish-soonest, monasteries
3	Alice Stone	easy	Quick roads, two-tile cities
4	Owen Reed	easy	Medium city + road points
5	Mira Vale	medium	Tempo cycling, feature contesting
6	Caleb Wren	medium	Large cities, late entry sharing
7	Priya Holt	hard	Efficient completion cycles, blocking
8	Marcus Quinn	hard	Big city pressure, tactical sharing
9	Evelyn Cross	advanced	Tempo + invasion + farm control
10	Theo Ashford	advanced	Denial-heavy control

To add or edit personas, modify Carcassonne/personas.json — no code changes needed.