devadmin/ProLibertateGames
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Activity

Merge feature/catan-engine into dev

Browse Source 
Brings in the Katan rules engine, board, model and AI (WALA-119), its 51 unit
tests and docs/RULES-catan.md. Only conflict was docs/README.md, which the
GitHub-lineage migration had dropped: kept the engine branch's index and
pointed the CI link (docs/CI.md no longer exists) at the root README.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01JdMNbY5hLR7FjtfEE712xG
This commit is contained in:
Claude
2026-10-14 20:50:28 +00:00
parent 33a253d80c 3a930f5423
commit 653e7a17a3
12 changed files with 3422 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+47
View File
@@ -0,0 +1,47 @@
# docs/
Conventions for this repo's documentation. Seeded at bootstrap (WALA-118).
## Per-game rules: `RULES-<game>.md`
Every game in `GameCatalog` gets one file describing how *this app* implements
it — not a generic rule dump. The rules code
(`app/src/main/java/org/prolibertate/games/game/<game>/`) is the source of
truth; the doc exists so a human or an agent can check intent against
behaviour without reading Kotlin first.
Naming: the catalogue id, lowercase, e.g. `crazy8s` → `RULES-crazy8s.md`.
| Game (catalogue id) | Rules doc |
| --- | --- |
| Backgammon | [RULES-backgammon.md](RULES-backgammon.md) |
| Checkers | [RULES-checkers.md](RULES-checkers.md) |
| Chess | [RULES-chess.md](RULES-chess.md) |
| Crazy 8s | [RULES-crazy8s.md](RULES-crazy8s.md) |
| Cribbage | [RULES-cribbage.md](RULES-cribbage.md) |
| Euchre | [RULES-euchre.md](RULES-euchre.md) |
| FreeCell | — (TODO) |
| Golf | [RULES-golf.md](RULES-golf.md) |
| Hearts | — (TODO) |
| Kaiser | [RULES-kaiser.md](RULES-kaiser.md) |
| Katan (catalogue id `catan`) | [RULES-catan.md](RULES-catan.md) |
| Klondike | — (TODO) |
| Mastermind | [RULES-mastermind.md](RULES-mastermind.md) |
| Morris | [RULES-morris.md](RULES-morris.md) |
| Peg solitaire | — (TODO) |
| Pirates | [RULES-pirates.md](RULES-pirates.md) |
| President | [RULES-president.md](RULES-president.md) |
| Pyramid | — (TODO) |
| Sequence | [RULES-sequence.md](RULES-sequence.md) |
| Spider | — (TODO) |
| Ta Yü | [RULES-tayu.md](RULES-tayu.md) |
| Wizard | [RULES-wizard.md](RULES-wizard.md) |
| Yahtzee | — (TODO) |
## Other docs
- Build, CI, releases and OTA are described in the CI section of the root
[README](../README.md).
- `licenses/` — third-party licences that must travel with the app
(Uncial Antiqua under the SIL OFL; the app itself is GPL-3.0, see `/LICENSE`).
- Repo-level agent notes live in [`CLAUDE.md`](../CLAUDE.md) at the root.
docs/RULES-catan.md
+304
View File
@@ -0,0 +1,304 @@
# Katan — implemented rules
This is the ruleset the engine enforces. Anything marked **toggle** is exposed
in the game setup screen.
Katan is this app's name for the island game the collection is built around.
The catalogue id is `catan` (so this file is `RULES-catan.md` and the code lives
in `game/catan/`), but the printed name is trademarked, so the game is listed
and titled **Katan**. The rules themselves are the base game for three to four
players, as published.
The engine is a pure state machine (`CatanRules`) with no Android types, and its
behaviour is pinned by `CatanBoardTest`, `CatanRulesTest` and `CatanAiTest`.
## Table
- **Players — *toggle*.** Three or four. `CatanOptions.playerCount`; the engine
refuses anything else.
- **Points to win — *toggle*.** Defaults to 10. `CatanOptions.pointsToWin`, at
least 2. A lower target makes a test game short.
The setup screen that exposes these lands with the screen task; the engine reads
them from the table configuration today.
## Board
The island is the standard layout, derived once from axial hex coordinates in
`CatanBoard` and checked at class-init:
- **19 hexes**, the hexes within distance 2 of the centre.
- **54 vertices** and **72 edges**, shared between neighbouring hexes by exact
integer position, not floating point. `HEX_CORNERS`, `EDGE_VERTICES`,
`VERTEX_EDGES`, `VERTEX_HEXES` and `EDGE_HEXES` are the shared graph.
- **30 coastal edges**, one closed ring.
- **9 harbours**, on fixed positions around the coast.
Terrain is dealt from the physical mix and shuffled: **4 forest, 4 pasture,
4 fields, 3 hills, 3 mountains, 1 desert**.
Number tokens are the 18 the game ships, shuffled over the land hexes: four red
tokens (**6, 6, 8, 8**) and fourteen others
(**2, 3, 3, 4, 4, 5, 5, 9, 9, 10, 10, 11, 11, 12**). Seven never appears. The
desert bears no token and the robber starts on it.
### Keeping 6s and 8s apart
The published game asks that the two red numbers not sit on adjacent hexes, and
`generate` guarantees it rather than hoping for it:
1. Shuffle the land and take four hexes; accept the draw if none of the four
touch each other. Retry up to 60 times.
2. If no draw separates them, fall back to four of the six board-corner hexes,
which are pairwise non-adjacent by construction and at most one of which can
be the desert.
`no seed puts two red tokens on adjacent hexes` runs the whole thing over seeds
1..500.
Harbours: the nine **positions** are fixed (the physical frame is not shuffled),
but the nine **types** are shuffled onto them — **five 2:1 resource harbours**
(one per resource) and **four generic 3:1 harbours**. The frame positions are
chosen so no two harbours sit closer than three coastal edges apart.
## Setup
Placement runs in snake order: seats `0, 1, …, n-1` then `n-1, …, 1, 0`, each
placing one settlement and one road. During setup the distance rule still holds
(a settlement may not sit one edge from any other building) but the road need
not connect to anything already placed.
A player's **second** settlement earns one resource card for each adjacent
producing hex, supply permitting — duplicates counted, so a second settlement on
two forests earns two lumber. The first pass earns nothing.
After the last placement, seat 0 leads and the first real turn begins.
## Turn
A turn runs through the phases in `CatanPhase`:
1. **AWAIT_ROLL** — the player on the clock rolls.
2. A seven goes to **DISCARDING** and then **ROBBER**; anything else produces and
goes straight to **PLAYING**.
3. **PLAYING** — build, trade, buy and play development cards, then end the turn.
4. **FREE_ROADS** is a detour inside PLAYING while a Road Building card is being
spent.
### Rolling
The dice are derived from the game seed and a monotonic counter (`rngStep`), not
from a random generator stored in the state: the same seed and the same moves
replay identically. `RollDice(forced = …)` exists so tests can stage a number;
it is deliberately **not** a member of the enumerated move list, so a client
cannot send one over the network — only code holding the state directly can use
it.
### Production
For a non-seven total, each hex whose number matches pays its producing terrain:
a settlement takes **1**, a city takes **2**. The robber's hex pays nothing.
**When the bank cannot meet the demand for a resource, nobody receives that
resource this roll.** This is the official ruling, implemented per-resource:
demand is totalled first and, if it exceeds the bank's supply, every gain of
that resource is dropped.
## The robber
A **seven** sends the robber: first every player holding **more than seven**
resource cards discards half their hand (rounded down, so nine cards means four
gone), in seat order starting from the lowest overfull seat; then the roller
moves the robber and may steal.
The robber **must move to a different hex**. Moving onto a hex lets the roller
steal one card from one opponent who has a building on that hex and at least one
card in hand. The card stolen is chosen at random, derived like the dice. A
hex with no opponent holding cards offers only the move, no steal.
A played Knight enters the same ROBBER phase, so the robber move after a Knight
is the same code path.
## Trading
### Domestic
An offer names **one** addressee and two card multisets: what the offerer gives,
what they want. There are no counter-offers and no open auctions in v1.
An offer is legal only when the offerer's turn is in PLAYING, the addressee is
another seat, both legs are non-empty, the two legs are not the same multiset
(`countOf(give) != countOf(get)` — like-for-like is not a trade), and the
offerer actually holds the cards being offered.
The addressee may **accept** only if they hold what was asked and the offerer
still holds what was promised; otherwise only **decline** is offered. A decline
clears the table and leaves every card where it was.
Offers are free-form intents rather than enumerated moves (the space of card
multisets is combinatorial), so they are validated structurally by
`CatanRules.isLegalMove` and checked by the network driver's gate like any other
move.
### Maritime
Bank trade gives `ratio` of one resource for one of another, where the ratio is
the best the seat can get: **4:1** through the bank, **3:1** through a generic
harbour, **2:1** through a harbour matching the resource being given. A harbour
counts when the seat owns a settlement or city on **either** endpoint vertex of
its edge.
## Building and development cards
| Build | Cost |
| --- | --- |
| Road | 1 lumber + 1 brick |
| Settlement | 1 lumber + 1 brick + 1 wool + 1 grain |
| City | 2 grain + 3 ore |
| Development card | 1 wool + 1 grain + 1 ore |
A settlement goes on an **empty vertex** at least two edges from every standing
building and connected to the seat's own road network. A city upgrades one of
the seat's own settlements. A road goes on an empty edge that connects to the
seat's network (a road or a building at one of its ends).
The development deck is the published 25 cards: **14 Knights, 2 Road Building,
2 Monopoly, 2 Year of Plenty, 5 Victory Point**. Cards are bought blind from the
top of the deck.
Timing rules the engine enforces:
- **One development card per turn.** `devCardPlayedThisTurn` gates every play.
- **A card cannot be played the turn it was bought.** Each card records
`boughtTurn` and is skipped while that equals the current turn.
- **Victory Point cards are never played.** They are counted straight from the
hand by `victoryPoints`, and are only revealed by winning.
- **Knight** → the robber phase, and counts toward Largest Army.
- **Road Building** → two free road placements (FREE_ROADS); the player may
forfeit any that remain.
- **Monopoly** → seizes every card of the named resource from the other seats.
- **Year of Plenty** → takes up to two cards from the bank; taking two of a kind
requires the bank to hold both.
## Scoring and winning
Victory points are:
- **Settlement 1, city 2.**
- **Longest Road 5** — the longest single road of **five or more** segments.
- **Largest Army 5** — first to **three** played knights.
- **Victory Point cards**, one each.
A seat wins on reaching **points to win** (default 10). The win is checked after
every build, when a turn ends, and when a seat's turn arrives — the last covers
points that changed on someone else's turn, such as a broken Longest Road being
re-awarded. A seat already at the target therefore wins at the start of its own
turn rather than having to act.
### Longest Road
The award goes to the longest **simple path** over a seat's own roads. The path
never passes *through* an opponent's building (it may run up to one) and never
revisits a vertex — so a figure of two loops sharing an intersection counts as
one road of five, not two roads, because the intersection is a branch.
Once held, the award is kept until another seat builds a **strictly longer**
road; an equal length leaves it where it is. If the holder's road falls below
five segments the award reopens to the longest road of five or more, lowest seat
first on a tie. A settlement placed across an opponent's road breaks it, and the
award is recomputed for everyone after any settlement.
### Largest Army
First to three knights takes it. It is stolen only by a **strictly larger** army:
a tie leaves the incumbent ahead, exactly as Longest Road does.
## The computer opponent
`CatanAi` plays a legal, mildly strategic game so a solo player can host against
computers, with the lobby filling empty seats.
It reads **only public information** — terrain, numbers, buildings, roads,
resource counts, development-card counts and knights played — plus its own hand.
It never looks into the deck, another seat's development cards, or the seed
beyond the roll the rules derive from it. That is a design constraint, not an
accident: it runs on the host, where the authoritative state is fully visible.
What it does:
- **Setup.** Rates a settlement by the production its three hexes give (weighted
by the token odds and by how much it wants each resource), plus a bonus for
resource variety and for sitting on a harbour, plus a small term for where the
accompanying road points.
- **Main phase**, in priority order: raise a city, build a settlement, play a
knight, play Year of Plenty or Monopoly when it closes a gap, play Road
Building when two segments are useful, buy a development card, build a road
that reaches a spot worth settling, trade at the bank only when the trade
completes a build this turn, make one domestic offer that closes a build, else
end the turn.
- **The robber.** Moves onto the hex where it blocks the most opposing
production (weighted by token odds), preferring to rob whoever is holding the
most cards and the most points.
- **Trades.** Accepts an offer when what arrives is worth more than what leaves
by its own resource valuations; a mild table, not a shark.
- **Discards.** Throws away what it values least (wool, then brick, then lumber,
before grain and ore).
It makes **at most one domestic offer a turn**. A declined offer changes nothing,
so re-offering the same thing would only bounce between two seats forever; the
engine allows more offers, the AI chooses not to.
`CatanAiTest` plays three- and four-seat tables of engines out to a result from
several seeds, refusing any illegal move the AI chooses, and checks the winner
reached the target.
## Provenance and rule choices
The rules are the published base game. Where the published rules leave room, the
engine picks one reading and records it here.
**Followed from the published rules:** the board and its component mix; the
number tokens; 6s and 8s not adjacent; snake-order setup and second-settlement
income; production weighting; the robber on a seven; discard half over seven;
domestic and maritime trade; build costs; the 25-card development deck and its
timing rules; Longest Road and Largest Army worth five; victory at ten.
**Choices made here, and why:**
- **A bank short of a resource pays nobody that roll.** This is the official
ruling, and it is implemented per-resource rather than per-player.
- **Longest Road and Largest Army are kept on a tie**, and stolen only by a
strictly longer road or a strictly larger army. The alternative reading lets a
tie steal the award; "strictly better" is the common tournament reading and
keeps the award from flickering.
- **A ring road counts as a simple path.** No vertex is revisited, so six
segments around one hex are worth five, not six.
- **The win is checked when a seat's turn arrives**, not only on that seat's own
action, so points that move on another player's turn still win.
- **A bought Victory Point card does not win immediately.** It is counted when
the win is next checked (a build or the end of the turn), which is when the
holder would reveal it.
- **Year of Plenty two-of-a-kind needs the bank to hold both cards**, not one.
- **The robber must move.** Some printings allow staying put; this engine always
requires a different hex.
- **Offers are one-to-one, no auctions or counter-offers** in v1.
## Known gaps
- **No domestic auction or counter-offer.** An offer is addressed to a single
seat. Open trading to the whole table, and counter-offers, are the obvious next
step and are not implemented.
- **No player-to-player trade over the wire beyond accept/decline.** The engine
supports it; whether the UI surfaces it is the screen task's concern.
- **No trading away a development card.** Not part of the base game.
- **The setup screen is not part of this task.** `CatanOptions` (players, target
points) is read from the table configuration; the screen that sets it, and the
catalogue descriptor's `available` flag, land with the screen and verification
tasks.
- **The AI does not look ahead.** It scores one move deep with a fixed resource
valuation. It plays legally and plausibly; it is not a strong opponent, and no
strength claim is made.
- **The board is the standard published layout, generated.** Unlike the Sequence
board there is no unverified substitute here — the geometry is the real one —
but the *island* (terrain and token placement) is freshly generated each game,
so it will not match any particular physical set-up. That is the intent.