From 3c0469fc81668f51f1f51ca30dfe6c027e675812 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 17:18:59 +0000 Subject: [PATCH] Seafarers: interaction tests, rules and UI docs --- CLAUDE.md | 9 +- .../catan/CatanSeafarersInteractionTest.kt | 149 ++++++++++++++++++ docs/RULES-catan-seafarers.md | 71 +++++++++ docs/UI-catan.md | 16 ++ 4 files changed, 243 insertions(+), 2 deletions(-) create mode 100644 app/src/test/java/org/prolibertate/games/ui/game/catan/CatanSeafarersInteractionTest.kt create mode 100644 docs/RULES-catan-seafarers.md diff --git a/CLAUDE.md b/CLAUDE.md index 03f9ff4..9c8512d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,9 +52,14 @@ integration: ## Katan The island game is catalogue id `catan`, shown as **Katan**. It has two rule -sets chosen at setup: the base game (`docs/RULES-catan.md`) and Cities & Knights +sets chosen at setup: the base game (`docs/RULES-catan.md`), Cities & Knights (`docs/RULES-catan-ck.md`, code in `game/catan/CatanCk*.kt`, state behind -`CatanState.ck`, which is null in the base game). The screen is layered; see +`CatanState.ck`, which is null in the base game) and Seafarers +(`docs/RULES-catan-seafarers.md`, code in `game/catan/CatanSea*.kt`, state behind +`CatanState.sea`). Rules code reads the board from `state.topo`, never from +`CatanBoard` directly, because a Seafarers map is not the 19-hex island. The +Catan Universe reverse engineering that shaped the landscape HUD and trade board +is in `docs/RE-catan-universe.md`. The screen is layered; see `docs/UI-catan.md` before changing it. ## Bash output is filtered before it reaches the model diff --git a/app/src/test/java/org/prolibertate/games/ui/game/catan/CatanSeafarersInteractionTest.kt b/app/src/test/java/org/prolibertate/games/ui/game/catan/CatanSeafarersInteractionTest.kt new file mode 100644 index 0000000..bca9a79 --- /dev/null +++ b/app/src/test/java/org/prolibertate/games/ui/game/catan/CatanSeafarersInteractionTest.kt @@ -0,0 +1,149 @@ +package org.prolibertate.games.ui.game.catan + +import kotlinx.serialization.encodeToString +import kotlinx.serialization.json.Json +import org.junit.Assert.assertEquals +import org.junit.Assert.assertTrue +import org.junit.Test +import org.prolibertate.games.game.GameCatalog +import org.prolibertate.games.game.catan.BuildShip +import org.prolibertate.games.game.catan.BuildingType +import org.prolibertate.games.game.catan.CatanAi +import org.prolibertate.games.game.catan.CatanBuilding +import org.prolibertate.games.game.catan.CatanOptions +import org.prolibertate.games.game.catan.CatanPhase +import org.prolibertate.games.game.catan.CatanRuleSet +import org.prolibertate.games.game.catan.CatanRules +import org.prolibertate.games.game.catan.CatanState +import org.prolibertate.games.game.catan.MovePirate +import org.prolibertate.games.game.catan.MoveRobber +import org.prolibertate.games.game.catan.MoveShip +import org.prolibertate.games.game.catan.PickGold +import org.prolibertate.games.game.catan.Resource +import org.prolibertate.games.game.catan.Terrain +import org.prolibertate.games.game.engine.PlayerKind +import org.prolibertate.games.game.engine.PlayerSlot +import org.prolibertate.games.game.engine.TableConfig + +/** What the screen offers on a Seafarers board: ships, the pirate, and gold. */ +class CatanSeafarersInteractionTest { + + private fun fresh(): CatanState { + val options = CatanOptions(playerCount = 3, pointsToWin = 12, ruleSet = CatanRuleSet.SEAFARERS) + return CatanRules.initialState( + TableConfig( + gameId = GameCatalog.CATAN, + seats = (0 until 3).map { PlayerSlot(it, "P$it", PlayerKind.AI, it) }, + optionsJson = Json { encodeDefaults = true }.encodeToString(options), + seed = 7L, + ), + ) + } + + /** Seat 0, mid-game, a harbour town on the coast of the home island and plenty of cards. */ + private fun harbour(): CatanState { + val s = fresh().copy( + phase = CatanPhase.PLAYING, + turn = 0, + turnNumber = 1, + resources = List(3) { Resource.entries.associateWith { 5 } }, + ) + val topo = s.topo + val v = (0 until topo.VERTEX_COUNT).first { vertex -> + topo.vertexIsland[vertex] == s.sea!!.home && + topo.VERTEX_EDGES[vertex].any { topo.edgeSea[it] && !topo.edgeLand[it] } + } + return s.copy(buildings = s.buildings.toMutableList().also { it[v] = CatanBuilding(BuildingType.SETTLEMENT, 0) }) + } + + @Test + fun `the ship is on the build menu, and arming it lights the sea edges a ship can take`() { + val s = harbour() + val legal = CatanRules.legalMoves(s, 0) + assertTrue(BuildKind.SHIP in CatanInteraction.canBuild(legal)) + + val targets = CatanInteraction.targets(s, legal, BuildKind.SHIP, null) + assertEquals(legal.filterIsInstance().map { it.edge }.toSet(), targets.edges) + + val edge = targets.edges.first { !s.topo.edgeLand[it] } + assertEquals( + TapOutcome.Submit(BuildShip(edge)), + CatanInteraction.onEdgeTap(edge, legal, BuildKind.SHIP, null), + ) + // The same tap with the road armed means nothing: a road cannot lie between two sea hexes. + assertEquals(TapOutcome.Ignored, CatanInteraction.onEdgeTap(edge, legal, BuildKind.ROAD, null)) + // A build tap waits for ✓ like any other piece. + assertEquals(BuildShip(edge), CatanInteraction.stageable(TapOutcome.Submit(BuildShip(edge)), BuildKind.SHIP)) + } + + @Test + fun `tapping a ship that can sail picks it up, and the next tap on a lit sea edge sails it`() { + val s0 = harbour() + val built = CatanRules.legalMoves(s0, 0).filterIsInstance().first() + val s = CatanRules.applyMove(s0, 0, built) + .let { it.copy(sea = it.sea!!.copy(builtThisTurn = emptyList())) } + val legal = CatanRules.legalMoves(s, 0) + + val idle = CatanInteraction.targets(s, legal, null, null) + assertEquals(setOf(built.edge), idle.ships) + assertEquals(TapOutcome.PickShip(built.edge), CatanInteraction.onEdgeTap(built.edge, legal, null, null)) + + val sailing = CatanInteraction.targets(s, legal, null, null, movingShip = built.edge) + val to = sailing.edges.first() + assertEquals( + TapOutcome.Submit(MoveShip(built.edge, to)), + CatanInteraction.onEdgeTap(to, legal, null, null, movingShip = built.edge), + ) + } + + @Test + fun `after a seven a land hex moves the robber and a sea hex moves the pirate`() { + val s = harbour().copy(phase = CatanPhase.ROBBER) + val legal = CatanRules.legalMoves(s, 0) + val targets = CatanInteraction.targets(s, legal, null, null) + val land = targets.hexes.first { s.terrains[it] != Terrain.SEA } + val sea = targets.hexes.first { s.terrains[it] == Terrain.SEA } + + val robber = CatanInteraction.onHexTap(land, legal, topo = s.topo) + assertTrue(robber is TapOutcome.Submit && robber.move is MoveRobber) + val pirate = CatanInteraction.onHexTap(sea, legal, topo = s.topo) + assertTrue(pirate is TapOutcome.Submit && pirate.move is MovePirate) + } + + @Test + fun `a gold pick is found by the cards it names`() { + val picks = listOf(PickGold(listOf(Resource.ORE)), PickGold(listOf(Resource.WOOL))) + assertEquals(PickGold(listOf(Resource.WOOL)), CatanInteraction.goldMove(picks, listOf(Resource.WOOL))) + assertEquals(null, CatanInteraction.goldMove(picks, listOf(Resource.WOOL, Resource.WOOL))) + assertEquals(1, CatanInteraction.goldCount(picks)) + } + + @Test + fun `the engines' own choices are always something the screen can make`() { + // Every legal move in a played-out game is reachable: a tap, a button or a dialog choice. + val ai = CatanAi() + var s = fresh() + var n = 0 + while (!CatanRules.isFinished(s) && n++ < 600) { + val seat = CatanRules.currentSeat(s) ?: break + val legal = CatanRules.legalMoves(s, seat) + val ships = legal.filterIsInstance() + if (s.phase == CatanPhase.PLAYING && ships.isNotEmpty()) { + val armed = CatanInteraction.targets(s, legal, BuildKind.SHIP, null) + ships.forEach { ship -> + assertTrue("ship ${ship.edge} not lit", ship.edge in armed.edges) + assertEquals(TapOutcome.Submit(ship), CatanInteraction.onEdgeTap(ship.edge, legal, BuildKind.SHIP, null)) + } + } + legal.filterIsInstance().forEach { sail -> + val lit = CatanInteraction.targets(s, legal, null, null, movingShip = sail.from) + assertTrue(sail.to in lit.edges) + assertEquals( + TapOutcome.Submit(sail), + CatanInteraction.onEdgeTap(sail.to, legal, null, null, movingShip = sail.from), + ) + } + s = CatanRules.applyMove(s, seat, ai.chooseMove(s, seat, legal)) + } + } +} diff --git a/docs/RULES-catan-seafarers.md b/docs/RULES-catan-seafarers.md new file mode 100644 index 0000000..e6ea2ac --- /dev/null +++ b/docs/RULES-catan-seafarers.md @@ -0,0 +1,71 @@ +# Katan: Seafarers + +The Seafarers rule set is chosen at setup next to *Base game* and *Cities & Knights*. It is the base +game ([RULES-catan.md](RULES-catan.md)) with a sea, ships, a pirate, gold fields and islands to +settle. Code: `game/catan/CatanSeaRules.kt` (the additions), `CatanSeaBoard.kt` (the map), +`CatanBoard.kt` (`Topology`, the geometry shared by every map), state behind `CatanState.sea` +(null in the other rule sets). It cannot be combined with Cities & Knights. + +Where the published rules leave room, or where this game differs, it says so below. + +## The map + +One map, *Heading for New Shores*: a large **home island** (21 hexes, one desert) and three small +islands (3, 3 and 2 hexes) across the water, inside a ring of sea. Which land hexes are gold, which +are the desert and where the sea lies is fixed; the **resources on the other hexes, the number tokens +and the nine harbours are shuffled** for each game. The red numbers (6, 8) are never on neighbouring +hexes. Players take three or four seats; the default target is **12 points** (menu: 8, 10, 12, 14). + +The geometry is the same lattice as the base island, generalised (`Topology`): a hex is land or sea, +a crossing can hold a town if any hex touching it is land, an edge can hold a road if any hex touching +it is land and a ship if any hex touching it is sea (so a coastal edge takes either, never both). + +## What changes + +**Setup.** Both starting settlements (and their roads) go on the home island. A starting piece is a +road, never a ship. The second settlement collects from the hexes round it as usual (gold pays nothing +at setup). + +**Ships.** A ship costs 1 lumber and 1 wool and lies on a sea edge. + +* It must join your fleet or a town of yours: one end of the edge touches your town, or another of your ships. + An opponent's town is a wall. +* Roads and ships connect **only at a town of your own**: a road cannot start from a ship's end, nor a + ship from a road's, unless a settlement or city of yours stands on that crossing. A settlement may be + built at the end of a ship route exactly as at the end of a road route. +* No more than 15 ships. Road Building may lay two roads, two ships or one of each. +* **Sailing.** Once per turn you may move one ship, never one built or moved this turn, and only a ship at the + **open end** of a route (one end touches nothing else of yours). It goes to any edge it could be built on + with it lifted off. + +**The pirate.** Starts in the open sea. On a seven (and with a Knight card) the player moves either the +robber, to any land hex, or the pirate, to any sea hex. The robber works as before. The pirate **blocks the six +edges round its hex**: no ship may be built or sail onto them (ships already there stay). It robs one card +at random from a player with a ship on an edge of its hex. + +**Gold.** A gold field has a number like any hex. When it comes up, each town beside it (one card; a city two) +pays its owner **any resource of their choice**, chosen after the ordinary production is dealt, in seat order from +the roller. The robber blocks a gold field like any hex. If the bank cannot supply the choice it is limited to +what it holds. + +**New islands.** The first player to settle on each island other than the home island scores **2 bonus points**, +permanently (`SeaState.islandBonus`). A second settlement there earns nothing extra. + +**Longest route.** Longest Road counts roads and ships together, as a path of your pieces that never runs +through an opponent's town and changes between road and ship only at a town of yours. Five or more, as before. + +Everything else (development cards, trading, harbours, Largest Army, the discard on a seven) is the base game. + +## Not included + +The physical expansion has more scenarios and the Catan Universe app adds more still. These are **out of scope here**: +fog islands, treasure islands, the oasis, the great canal, the Explorers & Pirates and Cities & Knights combinations, +the scenarios after the first, and trade ships. The `SeaScenario` enum and `SeaBoards` are built so a second map +is a new text map and a new enum entry. + +## How the AI plays it + +It settles first and sails second. A ship is built when a settlement spot reachable by sea (up to five steps from its +open end) is worth having, with a bonus for an island nobody has landed on, and ahead of a development card when that +bonus is in play. It chooses the resource it values most from gold, always moves the robber (never the pirate) and does +not sail ships it has already launched. See `CatanAi.shipValue`. diff --git a/docs/UI-catan.md b/docs/UI-catan.md index f1c2d05..8439da6 100644 --- a/docs/UI-catan.md +++ b/docs/UI-catan.md @@ -192,3 +192,19 @@ Landscape screens use the control scheme of Catan Universe's match view, redrawn ratio under the *give* card. An offer made to you opens the same panel read-only: ✓ accepts, ✕ declines, *Counter…* makes the rows editable. Cities & Knights goods trades and the counter-offer chooser still use dialogs. + +## Seafarers on the screen + +| Layer | What it adds | +| --- | --- | +| `CatanGeometry.kt` | `BoardLayout` and `CatanGeometry.fit` take the game's `Topology`, so a map of islands fits the box like the standard island does | +| `CatanStyle.kt` | gold-field colour, the pirate's and the ship sail's colours | +| `CatanBoardView.kt` | sea hexes (a faint grid, no fill), ships (hull with a sail), the pirate (a flagged hull), a ring on ships that can sail | +| `CatanInteraction.kt` | `BuildKind.SHIP`; `PickShip`, `movingShip`, ship targets; the robber's and the pirate's hexes; `goldMove` | +| `CatanDialogs.kt` | `CatanGoldDialog`, the choice of what a gold field pays | +| `CatanScreen.kt` | the picked-up ship, the ship on the build menu / column | + +**Interaction model.** Arm *Ship* (or drag it from the build column) and tap a lit sea edge: ✓ places it. To sail, +tap one of your ships that has a ring, then a lit sea edge. After a seven, tap a land hex for the robber or a sea +hex for the pirate. A gold field opens a dialog that cannot be dismissed. `CatanSeafarersInteractionTest` checks +that every build and sail the engine offers has a tap that produces it.