ProLibertateGames/docs/RULES-catan-ck.md

Katan: Cities & Knights — implemented rules

This is the second rule set of Katan (see 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.