211 lines
14 KiB
Markdown
211 lines
14 KiB
Markdown
# Katan UI — how it is built, and how to change it
|
|
|
|
The Katan screen (`app/src/main/java/org/prolibertate/games/ui/game/catan/`) is
|
|
built in layers so that **look, wording, layout and interaction can each be
|
|
changed on their own**. If you are an agent asked to restyle, retheme,
|
|
re-copy or re-lay-out Katan, start here and touch only the layer you were asked
|
|
about.
|
|
|
|
The rules live elsewhere and are not part of the UI: `game/catan/` is a pure
|
|
state machine (see [RULES-catan.md](RULES-catan.md)). **Nothing in `ui/game/catan/`
|
|
decides what is legal.** The engine's legal-move list is the single source of
|
|
truth, so the UI can only ever offer a move the rules would accept.
|
|
|
|
## The layers
|
|
|
|
| Layer | File | Owns | Change it to… |
|
|
| --- | --- | --- | --- |
|
|
| **Style** | `CatanStyle.kt` | Every colour, proportion and the light/dark palettes | Re-skin: new terrain colours, seat colours, piece sizes, token look |
|
|
| **Copy** | `CatanText.kt` | Every sentence, button label and name shown | Reword, localise, rename resources |
|
|
| **Geometry** | `CatanGeometry.kt` | Engine lattice → pixels, and pixel → nearest vertex/edge/hex | Change board scale, margin, harbour placement, tap reach (rarely) |
|
|
| **Interaction** | `CatanInteraction.kt` | What is tappable, what a tap means, which buttons are live | Change *how* something is selected (never *whether* it is legal) |
|
|
| **Board drawing** | `CatanBoardView.kt` | The `Canvas`: tiles, tokens, ports, robber, roads, pieces, highlights | Change how a piece is drawn (art, shapes, animation) |
|
|
| **Panels** | `CatanPanels.kt` | Resource tiles, hand, player cards, dice, action bar, log | Restyle or rearrange widgets |
|
|
| **Dialogs** | `CatanDialogs.kt` | Discard, robber victim, play card, trade, trade reply, game over | Change a dialog's flow or look |
|
|
| **HUD** | `CatanHud.kt` | The landscape controls: build column, ✓ / ✗, round turn / trade buttons, pinch-pan board | Move or restyle a landscape control |
|
|
| **Trade board** | `CatanTradeBoard.kt` | The base-game trade panel (offer, bank, reply) | Change how trades are composed or answered |
|
|
| **Screen** | `CatanScreen.kt` | Wiring to `MatchController`, portrait/landscape layout, which dialog shows | Change the layout or add a new element |
|
|
| **Previews** | `CatanPreviews.kt` | Android Studio previews of real positions | Iterate on the look without a match |
|
|
|
|
Everything outside this folder that mentions Katan is one-line wiring:
|
|
`PlayScreen.kt` (builds the `MatchController`), `GameSetupScreen.kt` (players and
|
|
points-to-win options), `Catalog.kt` (the catalogue entry).
|
|
|
|
## Recipes
|
|
|
|
**Change colours or sizes.** Edit `CatanStyle.kt`. `LightStyle` is the reference
|
|
palette; `DarkStyle` is derived from it. Metrics (`roadWidth`, `settlementSize`,
|
|
`tokenRadius`, …) are fractions of the hex radius, so they scale with the screen.
|
|
To try a whole new theme, provide it at the root:
|
|
`CompositionLocalProvider(LocalCatanStyle provides myStyle) { … }`.
|
|
|
|
**Change wording or translate.** Edit `CatanText.kt`. Composables never build a
|
|
sentence themselves. `prompt(...)` is the one-line "what is happening / what do I
|
|
do" text; it is a pure function of the state, with tests in `CatanTextTest`.
|
|
|
|
**Redraw a piece** (settlement, road, robber, port, token). Edit the matching
|
|
`draw…` function in `CatanBoardView.kt`. Positions come from `BoardLayout`, so you
|
|
only decide the shape. Keep the hit target generous (see Accessibility).
|
|
|
|
**Rearrange the screen.** Edit `CatanScreen.kt`. It builds four independent
|
|
pieces (`board`, `players`, `promptRow`, `handAndActions`) and arranges them
|
|
differently in portrait and landscape. Moving or dropping a piece does not affect
|
|
the others.
|
|
|
|
**Add a widget.** Make it a stateless composable in `CatanPanels.kt` (values in,
|
|
lambdas out). Do not give it the `MatchController`.
|
|
|
|
**Change how a selection works** (for example a one-tap build instead of a
|
|
build-mode toggle). Edit `CatanInteraction.kt` and its tests, then adjust the
|
|
screen's UI state. The legal-move list stays the gate.
|
|
|
|
## Rules of the road
|
|
|
|
1. **Never put a rule in a composable.** If a button's enabled state or a tap's
|
|
result depends on game logic, it goes in `CatanInteraction` (pure, tested) and
|
|
is derived from the engine's `legal` list or `CatanRules`.
|
|
2. **Never hard-code a colour or a string** outside `CatanStyle` / `CatanText`.
|
|
3. **Stateless by default.** Panels and dialogs take values and report events. The
|
|
only state they may own is the transient selection they are helping the player
|
|
make (cards picked in a trade, for example).
|
|
4. **Hidden information.** The local view comes from `CatanRules.viewFor`: other
|
|
players' development cards and the deck are empty on a client. Do not show the
|
|
size of the deck; it is not known to a client. Card *counts* (`resourceCount`,
|
|
`devHandCounts`) are public.
|
|
5. **The state is immutable.** Never mutate it; submit a move.
|
|
6. **The layout must not move.** Everything outside the board has a *fixed
|
|
height*, and the board takes whatever is left, so the island's scale is the
|
|
same all game. Concretely: a control is *enabled or disabled*, never
|
|
*present or absent* (the action bar always shows every button); text that can
|
|
vary in length is pinned to a fixed number of lines (`minLines = maxLines`);
|
|
a line that is sometimes empty is still drawn (a non-breaking space), as the
|
|
award line on a player card is. A change that makes any non-board element
|
|
taller or shorter at runtime will rescale the board under the player's thumb.
|
|
|
|
## Interaction model (what the player actually does)
|
|
|
|
| Phase | The player… |
|
|
| --- | --- |
|
|
| Setup | taps a highlighted crossing (settlement), then a highlighted edge beside it (road). *Cancel* re-picks the settlement |
|
|
| Roll | presses **Roll dice** |
|
|
| Seven | **Discard** dialog (forced); then taps a hex to move the robber; a victim dialog appears only if more than one player can be robbed |
|
|
| Main turn | arms **Road / Settlement / City** and taps a highlighted spot; **Buy card**; **Play card**; **Trade**; **End turn** |
|
|
| Road Building | taps highlighted edges, or **Done with roads** |
|
|
| Offered a trade | **Accept / Decline / Counter…** dialog (forced); *Counter…* opens a picker pre-filled with the mirror of the offer |
|
|
| Counter-offers received | **Counter-offers** dialog: *Accept* beside the one to take, or *No deal* |
|
|
| Game over | result dialog |
|
|
|
|
Trade offers are free-form (two card multisets), so they are validated with
|
|
`CatanRules.isLegalMove`, not looked up in the legal list.
|
|
|
|
## Testing
|
|
|
|
Gradle does not run in the agent sandbox; **CI is the compile and test check**
|
|
(dispatch `ci.yml` on your branch). What is covered:
|
|
|
|
- `CatanGeometryTest` — the island fits any box, edges and corners are one radius,
|
|
hit-testing finds the right vertex/edge/hex.
|
|
- `CatanInteractionTest` — targets and tap outcomes for setup, building, free
|
|
roads, the robber (including the victim choice), discards, bank trades, offers,
|
|
development cards and trade replies, all against real engine states.
|
|
- `CatanTextTest` — the prompts and tallies.
|
|
|
|
Drawing and dialogs are not unit-tested; use the previews in `CatanPreviews.kt`
|
|
and play a game on a dev build.
|
|
|
|
## Accessibility notes
|
|
|
|
- Tap targets: vertices and edges accept a tap within `tapReach` (0.7) hex radii,
|
|
about 23 dp on a phone. If you shrink the board, keep that physical size.
|
|
- Seat colours are blue, orange, white and purple, each outlined in near-black so
|
|
they read on any terrain. Colour is the only piece identity today; adding a
|
|
shape or letter per seat would help colour-blind players (a good first task).
|
|
- The board has a content description but no per-hex semantics; a screen-reader
|
|
mode would need one.
|
|
|
|
## Cities & Knights on the screen
|
|
|
|
The same layers carry the expansion; the screen only adds pieces, and **none of them
|
|
decides what is legal** — each reads the engine's legal-move list.
|
|
|
|
| Layer | What it adds |
|
|
| --- | --- |
|
|
| `CatanStyle.kt` | commodity colours, a colour per improvement track, the wall and barbarian colours, the awake-knight halo |
|
|
| `CatanText.kt` | goods, track, knight and progress-card names and help text; the prompts for every chore |
|
|
| `CatanInteraction.kt` | `BuildKind.WALL` / `KNIGHT`; chore taps; the moving-knight and armed-card modes; `knightActions`, `progressHand`, `goodsBankTrades` |
|
|
| `CatanBoardView.kt` | shields for knights (strength dots; faded when asleep, white halo when awake), dashed walls, a pennant for each metropolis, the merchant coin, a faint robber until the first attack |
|
|
| `CatanPanels.kt` | commodity tiles in the hand, the barbarian strip, the yellow / red / event dice, the extra player-card lines, the Improve and Progress buttons |
|
|
| `CatanCkDialogs.kt` | goods picker (discard, wedding, harbour), improvements, progress cards, the knight menu, deck / aqueduct / spy / drop choices, goods trade |
|
|
| `CatanScreen.kt` | the visual state: knight menu, moving knight, armed card, and which chore dialog shows |
|
|
|
|
**Interaction model.** Tap one of your own knights (it gets a yellow ring when it can do
|
|
something) for its menu: wake, promote, move or chase the robber. *Move* arms the board
|
|
with the crossings the knight can reach. A progress card that needs a place on the board
|
|
(Engineer, Medicine, Merchant, Diplomat, Intrigue, Inventor) closes the dialog and
|
|
**arms** the board; the next tap plays it. Chores that are answered with a place — a city
|
|
to lose, a metropolis site, a driven knight's refuge, a free knight — light the crossings
|
|
on the board and the prompt line says what to tap; the others open a dialog that cannot
|
|
be dismissed, because the game is waiting on it.
|
|
|
|
**Testing.** `CatanCkInteractionTest` plays whole games and checks that for *every* legal
|
|
move at *every* position some control (a tap, a button or a dialog choice) produces it, so
|
|
a legal move with no way to make it — a stuck phone — fails the build.
|
|
|
|
## Status and known gaps
|
|
|
|
The screen is **playable and feature-complete for the engine's rules**, but is
|
|
**unverified on two real devices**, so the catalogue entry is `devPreview`
|
|
(openable on a dev build, hidden from production). To release it: verify
|
|
two-device play, then in `Catalog.kt` set `available = true` and remove
|
|
`devPreview = true`, and update `CatalogTest`.
|
|
|
|
Not done yet, in rough priority order:
|
|
|
|
1. Two-device verification (host + guest over the LAN) and a full game on a phone
|
|
and a tablet.
|
|
2. Feedback on events: dice-roll animation, a highlight on hexes that produced,
|
|
resource-gain flourishes, haptics. The state carries the dice and a text log;
|
|
it does not say which hexes paid out, so that needs either a diff of two states
|
|
or an engine addition.
|
|
3. Art: terrain textures, resource and harbour icons, a real robber pawn.
|
|
4. A timer or cancel button on offers (the engine has neither).
|
|
5. A board that shows the *last* move (a faint highlight of what just changed).
|
|
6. Landscape polish on large tablets; the right-hand panel scrolls but is plain.
|
|
|
|
## Landscape HUD and trade board (from Catan Universe)
|
|
|
|
Landscape screens use the control scheme of Catan Universe's match view, redrawn in 2D
|
|
(what was learned, and from where: [RE-catan-universe.md](RE-catan-universe.md)). Portrait keeps the stacked layout.
|
|
|
|
* **Drag to build.** The left column holds Road / Settlement / City (and Wall / Knight in
|
|
Cities & Knights). Drag a piece onto the island: lit spots snap under the finger
|
|
(`CatanInteraction.snap`), release over one to **stage** it, then press **✓** to place or **✕**
|
|
to cancel (`CatanInteraction.stageable`, `spotOf`). A tap on a piece still arms the board for
|
|
tapping a spot. Setup placements, free roads and chores are not staged: they commit on tap.
|
|
* **Pinch and pan** the island (`ZoomPanBox`). The board is drawn through a graphics layer, so
|
|
taps and drops arrive in board coordinates; hit-testing is unchanged.
|
|
* **Round buttons**, bottom right: the big one is roll / end turn / done (whatever the engine
|
|
currently allows); ⇄ is trade; the small pair is buy / play card (Improve / Cards in C&K).
|
|
* **Trade board** (`CatanTradeBoard`, base game): a panel over the bottom of the island with a
|
|
Bank / Player toggle, a round button per rival to address an offer to one player, a *get* row on
|
|
top, a *give* row below, and ▾ hide / ✕ clear / ✓ send on the right. Bank mode shows each resource's
|
|
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.
|