ProLibertateGames/docs/RULES-catan-ck.md

# Katan: Cities & Knights — implemented rules

This is the second rule set of Katan (see [RULES-catan.md](RULES-catan.md) for the
base game). It is chosen on the setup screen — **Rules: Base game / Cities &
Knights** — and stored as `CatanOptions.ruleSet` (`CatanRuleSet.CITIES_AND_KNIGHTS`).
A table plays one or the other; the choice reaches guests with the rest of the
options.

The expansion is a whole rule set rather than a toggle, because it replaces rules
(no development cards, no Largest Army, a different seven) as well as adding them.
Everything it needs lives behind `CatanState.ck`, which is `null` in the base game,
so a base game's state and rules are untouched. The code is:

| File | Holds |
| --- | --- |
| `CatanCkModel.kt` | the data: commodities, improvement tracks, progress cards, knights, the chore queue, every new move |
| `CatanCk.kt` | the rules: legal moves, applying them, the roll, the barbarians, scoring |
| `CatanCkAi.kt` | the computer opponent for this rule set |
| `CatanRules.kt` | the single entry point; calls into `CatanCk` whenever `state.ck != null` |

Behaviour is pinned by `CatanCkRulesTest` (each rule on a crafted position) and
`CatanCkSelfPlayTest` (whole games, engine against engine). Three or four players,
as in the base game.

## Verification

The rules were checked against the in-game almanac of Catan Universe (rules text
only: costs, card wordings, the barbarian and improvement rules). Where the almanac
is silent or ambiguous the reading chosen is listed under *Choices made here* below.

## What changes from the base game

| | Base game | Cities & Knights |
| --- | --- | --- |
| Points to win | 10 | **13** (setup offers 8 / 10 / 13 / 15) |
| Development cards | 25-card deck | **none** — knights and progress cards replace them |
| Largest Army | 5 *(see RULES-catan.md)* | **none** |
| Longest Road | 5 *(see RULES-catan.md)* | **2** |
| Second setup piece | settlement | **city** (resources only, no commodities) |
| Dice | two | **two number dice + the event die** |
| A seven | discard half over 7; robber moves | discard half over **7 + 2 per wall**; the robber **only moves after the first barbarian attack** |
| Cities | 2 of a resource | forest: 1 lumber + **1 paper**; pasture: 1 wool + **1 cloth**; mountains: 1 ore + **1 coin**; hills / fields: 2 of the resource |

## The dice

The yellow die and the red die are added for production, as in the base game. The
**event die** has three ships and one gate each of yellow (trade), blue (politics)
and green (science). It is resolved **before** production:

- **Ship** — the barbarians come one step nearer (they start 7 steps out).
- **Gate** — every player with at least one level of improvement in that colour,
  **in turn order from the roller**, whose **red die is no higher than their level**
  in that track, draws a progress card of that colour.

`RollDice(forced, event)` stages both for tests, like the base game's forced roll.
An **Alchemist** played before the roll sets the two number dice (the event die is
still rolled).

## Commodities

Three commodities — **cloth, coin, paper** — join the five resources. The bank holds
12 of each (19 of each resource). Hands, discards, thefts and trades all treat them as
cards; progress cards are not cards for any of these purposes.

When the bank cannot meet the demand for a card type: with **one** seat owed it,
that seat takes what is left; with **two or more** owed, nobody receives it.

## The barbarians

The strip shows how many steps away the ship is. On the seventh ship it **lands**:

- Barbarian strength is the **number of cities on the board** (a metropolis is a city).
- Catan's strength is the sum of the strengths of every **active** knight (basic 1,
  strong 2, mighty 3).
- If Catan's strength is **at least** the barbarians', Catan holds: the player with
  the strictly highest contribution takes a **Defender of Catan** card (one point);
  if several tie for highest, **each draws a progress card from a deck of their
  choice** instead.
- Otherwise Catan falls: among the players who own a city that is not a metropolis,
  those who contributed **least** each lose one city, **to their own choice**. A lost
  city becomes a settlement (or, if the seat has no settlement piece left, is removed),
  and its wall goes. **A metropolis can never be pillaged.**
- Either way every knight stands down, the ship returns to seven steps, and the
  **robber wakes** — until now it has not been on the board.

## Knights

Each seat has **two knights of each strength** (six in all).

| Action | Cost | Rule |
| --- | --- | --- |
| Hire | 1 ore + 1 wool | a **basic** knight on an empty crossing at the end of one of your roads; only if one of your two basic knights is free |
| Activate | 1 grain | a sleeping knight wakes; only active knights count against the barbarians |
| Promote | 1 ore + 1 wool | one level, once per knight per turn; a **mighty** knight needs **level three of politics** (the fortress); the next level's pieces must be free |
| Move | — | an active knight moves along **its own roads** to an empty crossing, or onto a **strictly weaker** foreign knight, driving it off; it then rests |
| Chase the robber | — | an active knight on a crossing of the robber's hex sends the robber off (only once the robber is awake); it then rests, and the robber move follows |

- **A knight cannot act on the turn it woke.** It can be woken again after it acts.
- A driven-off knight is moved by **its owner** along its own roads to any empty
  crossing it can reach; if there is none, it is lost.
- A knight is a wall, like an opposing building: roads cannot be laid past an enemy
  knight, a settlement cannot be built on a knight, and the knight cuts **Longest Road**.
- Knights can act (wake, move, chase) **before the roll** as well as after.

## City walls

2 brick, on a city without a wall, **three per player**. Each wall raises the hand
limit on a seven by two (so a seven discards when you hold more than `7 + 2 × walls`).

## City improvements

Three tracks, five levels each, bought with the track's commodity: **trade (cloth,
yellow), politics (coin, blue), science (paper, green)**. Level *n* costs *n* of the
commodity. You must own a city to improve.

| Track | Level 3 gives |
| --- | --- |
| Trade | commodities trade with the bank **2:1** |
| Politics | knights may be promoted to **mighty** |
| Science | the **aqueduct**: when the dice pay you nothing, take any resource |

The level names (Trading Post … Grand Bazaar, Town Hall … Palace, Abbey … University)
are this app's own.

### Metropolises

The first player to reach **level four** in a track takes that track's **metropolis**
(a marker on one of their cities: +2 points; a city carries at most one). Reaching
**level five** takes it from a holder who is still on four. A player with several
cities chooses which; with one it is placed at once; a player with no free city
**waits**, and claims it when a city is built.

## Progress cards

54 cards: 18 in each of three decks. A card played returns to the **bottom** of its
deck. A hand holds **four**; a fifth must be given back at once. They can be played at
any point of your own turn (before or after the roll), except where noted.

**Science (green)** — Alchemist ×2 *(before the roll only)*, Crane ×2, Engineer, Inventor ×2,
Irrigation ×2, Medicine ×2, Mining ×2, Printer, Road Building ×2, Smith ×2.

**Politics (blue)** — Bishop ×2 *(after the first attack)*, Constitution, Deserter ×2,
Diplomat ×2, Intrigue ×2, Saboteur ×2, Spy ×3, Warlord ×2, Wedding ×2.

**Trade (yellow)** — Commercial Harbor ×2, Master Merchant ×2, Merchant ×6,
Merchant Fleet ×2, Resource Monopoly ×4, Trade Monopoly ×2.

**Printer** and **Constitution** are one point each and are **laid face up the moment
they are drawn**; they never sit in a hand.

How each plays is shown on the card in the app (`CatanText.progressHelp`); the engine's
behaviour is in `CatanCk.applyProgress`. Points worth knowing:

- **Saboteur** hits every other player with **as many points as you or more**, who each
  discard half their cards (rounded down). **Wedding** takes two cards (or what they
  have) from each player with **more** points. **Master Merchant** needs a victim with
  more points, and takes two cards you choose.
- **Spy**: you see the target's progress cards and take one; nobody else sees them.
- **Merchant**: placed beside one of your buildings; you trade that hex's resource 2:1
  and hold a victory point until someone else plays a Merchant.
- **Deserter**: the victim removes a knight of *their* choice; you place a free one of the
  same strength (or a basic if yours is not free), awake or asleep as theirs was.
- **Diplomat**: removes a road with a loose end (an end touching no other road, building
  or knight); if it was yours you may rebuild it anywhere for free.
- **Inventor** swaps two tokens, never a 2, 6, 8 or 12.

## The chore queue

Anything that needs an answer from somebody — a discard, a city to lose, a progress card
to hand over, a metropolis site, a knight to place — is queued as a **chore**
(`CatanPhase.CHORE`, `CkState.chores`). The game waits on the seat the first chore names
(not always the player whose turn it is), then resumes where `CkState.back` says. This is
how a seven, a barbarian landing, a wedding or a spy are all one mechanism, and why
the AI and the network driver needed no new concepts.

The two free-form chores — **discarding** and **handing over** cards — are structural
like the base game's trade offers: the engine checks them in `isLegalMove` and the legal
list carries one example, so a seat is never without a move.

## Scoring and winning

Settlement 1, city 2, **metropolis +2**, **Longest Road 2**, **Defender of Catan 1** each,
**Printer / Constitution 1** each, **the Merchant 1**. Nothing is hidden. Win at 13 (default),
checked after every move and when a turn arrives.

## Choices made here, and why

- **The red die must be no higher than the improvement level** to draw a progress card
  (level 1 draws on a 1, level 5 on 1–5). The almanac says the red die must match a
  number on one of your improvements and that the number rises with the level; this is
  the reading that makes both true.
- **One resource is offered to every player for a Commercial Harbor.** The printed card
  lets you offer a different one to each.
- **The merchant cannot go on the desert**, which produces nothing to trade.
- **Improvements need a city** to be built.
- **A 3:1 harbour trades commodities too**; a 2:1 harbour trades only its own resource.
- **A knight that cannot find a refuge is lost**, as the almanac says of an intrigue.
- **A claim on a metropolis with no city to carry it waits** and is made when a city is
  built.
- **Domestic trade** may include commodities; the one-offer-at-a-time rules of the base
  game apply.
- **No Seafarers, no 5–6 player extension**, no scenario or variant of any kind.

## The computer opponent

`CatanCkAi` plays a safe, unambitious game: it settles and raises cities as the base AI
does, spends commodities on improvements as soon as it can (leaning to politics), hires
and wakes knights as the barbarians draw near, chases the robber off hexes it needs, plays
the progress cards whose value is obvious, and answers every chore with the card it values
least. It never plans a knight's route, never plays an Alchemist, Inventor, Diplomat,
Deserter or Intrigue, and makes no domestic offers (though it answers them). Every engine
game in `CatanCkSelfPlayTest` ends in a win at thirteen points.

## Known gaps

- The screen is built and its logic is tested, but **not yet verified on two real
  devices**; the catalogue entry stays a dev-channel preview.
- No animation for the event die, the barbarian landing or a knight's move.
- The Commercial Harbor offers a single resource type (see above).
- The AI is not a strong opponent and makes no claim to be.