> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/adr/0026-eight-players-at-most.md).

# ADR 0026: Eight players at most

## Status

Accepted (owner decision, 2026-09-30, relayed by the docs session: "do 8 players at most, since no console supports 16"). Supersedes the player count in ADR 0002 and in `docs/ARCHITECTURE.md`, `docs/FEATURE_PLAN.md`, `docs/DESIGN.md` and `docs/PLAN_V2.md` Phase 3 (the connect screen's paged players 9–16).

## Context

* Kouch was built for 16 players: 16 slots in `SlotManager`, four DSU servers (`26760`–`26763`) of 4 slots each, motion on at most 8 of them, and a connect screen that pages players 9–16 behind LB/RB.
* The owner's point: no console the emulators emulate takes more than 8 players. Seats 9–16 cost layout, testing and code paths (the paged connect layout, 16 player colours, the second pair of DSU servers) for a case no game uses.
* The motion cap was already 8, so with 8 seats every player can have motion.

## Decision

* **Kouch seats at most 8 players,** and every one of them may have motion. The motion cap equals the seat count, so the "motion flags ≤ 8" bookkeeping becomes "every seat".
* **DSU:** two servers (`127.0.0.1:26760` and `26761`), 4 slots each; seat p → server p/4, slot p%4 as before.
  * Seats 1–8 keep the same ports and slots, so every emulator config written so far stays valid.
  * The third and fourth servers aren't started. Emulator profiles never pointed at them, since `{dsu_port}` derives from the seat.
* **A ninth controller waits:** it shows on the connect screen as waiting, with a plain note that all 8 seats are taken, until a seat frees up. Nothing is dropped silently.
* **The connect screen's largest layout is 2 × 4.** The paged 9–16 layout and its LB/RB paging go away.
* **Saved seats:** a `players.json` with seats 9–16 loads its seats 1–8. Pads that were seated at 9–16 join as waiting pads. The file is rewritten on the next seat change.
* **LAN seats, the keyboard seat and Remote Play guests** count toward the same 8.
* **Colours:** the player palette keeps its first 8 colours in all three places (`PLAYER_PALETTE`, `--k-player-1..8`, the lab's LED palette).

## Consequences

* **Simpler:** the connect screen, the routing table (8 entries), and fewer DSU sockets.
* **Tests change:** the 16-slot routing/claim tests become 8, and the lab's `sixteen` test becomes an 8-seat test, keeping its name out of the UI.
* **Docs change:** CLAUDE.md, ARCHITECTURE, FEATURE\_PLAN, DESIGN (connect layouts), PLAN\_V2, EARLY\_TESTS, PROFILE\_AUTHORING (the DSU ports), and the user guide (joining, players and seats, FAQ, the creators page).
* **Store and site copy** say "up to 8 players, every one with motion".
* **Going back to more than 8** would need a new ADR and brings back the paged layout. The DSU layout already allows it (a third and fourth server) without changing seats 1–8.

## Work

| Who     | What                                                                                                                                                                                                                                                           |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C       | `kouch-core`/`kouch-input` (8 slots, motion on every seat, the waiting ninth pad, players.json migration), `kouch-dsu` (2 servers), the connect screen (2 × 4 max, no paging, the "all 8 seats taken" note), the lab's tests, `docs/DESIGN.md` connect section |
| B       | profile templates and validation that mention 16 or ports 26762/26763, `schemas/` (PlayersFile), LAN seat range, the mock's pads in `transport.ts` if over 8, `docs/PROFILE_AUTHORING.md`                                                                      |
| A       | `--k-player-9..16` tokens and anything in the shell that counts to 16                                                                                                                                                                                          |
| central | this ADR, CLAUDE.md, ARCHITECTURE/FEATURE\_PLAN/PLAN\_V2/EARLY\_TESTS wording, telling the docs session when the app change is on main                                                                                                                         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kouch.dev/docs/adr/0026-eight-players-at-most.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.