# Aannames — Allianties

Waar de specificatie ruimte liet, gelden deze keuzes. Ze zijn ook in de
regelmotor (`server/lib/Engine.php`) en de tests vastgelegd.

## Bord en plaatsing

- Het bord is vierkant. De host kiest de zijde in de lobby (geheel getal
  van **6 tot 24**). De voorgestelde grootte is
  `max(6 + ceil(n / 2), n + 1)`, met een maximum van 24. `ceil` rondt
  halven naar boven af (bij oneven n: drie spelers → `ceil(1,5) = 2` →
  zijde 8). Voorbeelden: 2 spelers **7×7**; 3 spelers **8×8**; 6 spelers
  **9×9**; 10 spelers **11×11**; 14 spelers **15×15**; 16 spelers
  **17×17**. Voor n ≤ 10 overheerst `6 + ceil(n/2)`; daarna `n + 1`.
- De suggestie wordt bijgewerkt als er spelers bij komen of weggaan,
  **tenzij de host het veld handmatig heeft gewijzigd** (`grid_auto`).
  “Gebruik de voorgestelde grootte” zet automatische bijwerking weer aan.
- Bij de start controleert de server: zijde tussen 6 en 24, minstens
  evenveel vakjes als spelers, en unieke startposities op het bord.
  Anders wordt de start geweigerd (`bad_grid`). Een host mag bewust
  kleiner kiezen dan de suggestie (bijvoorbeeld 6×6).
- Startposities liggen op een ring rond het midden, beginnend bovenaan en
  dan met de klok mee. Bij een botsing schuift de speler naar het dichtstbij
  zijnde vrije vakje. Dode spelers blokkeren geen vakjes meer, maar blijven
  visueel op hun laatste plek (uitgegrijsd). Op het voorgestelde 7×7
  voor twee spelers staan ze ongeveer bovenaan en onderaan het midden,
  buiten elkaars startbereik 2.
- Maximaal 16 spelers per spel, minimaal 2 om te starten. Er is geen
  aparte “klaar”-stap: de host start wanneer er minstens twee spelers zijn.
- Kleuren van de omlijning worden in volgorde van aansluiting uit een vaste
  palet van 16 contrasterende kleuren gekozen.

## Actiepunten en tijd

- Iedereen begint bij de start met 1 actiepunt, zodat je meteen kunt
  handelen.
- Daarna krijgt elke levende speler 1 punt bij elke dagelijkse uitdeling
  (in de tijdzone van de host, zie “Tijdzones”). Het tijdstip is per lobby instelbaar, standaard
  **00:00**, en volgt de wissel naar en van zomertijd. Als de server een
  paar dagen offline was, worden gemiste uitdelingen bij de volgende
  request ingehaald.
- De countdown bovenaan is `HH:MM:SS` tot de volgende uitdeling, op basis
  van de servertijd (met correctie voor klokverschil in de browser) en tikt
  live zolang het tabblad open is.
- Bereik heeft een plafond gelijk aan de maximale Chebyshev-afstand op het
  bord (`grootte − 1`), zodat “het hele bord” het maximum is.
- Meerdere actiepunten in één keer geven telt als één actie (één tik op de
  tijdlijn).

## Jury (standaard aan, in de lobby uit te zetten)

- Alleen uitgeschakelde deelnemers (inclusief wie zich heeft overgegeven)
  mogen stemmen, en alleen op een levende speler.
- Stemmen zijn geheim: anderen zien jouw stem niet. Je kunt hem wijzigen
  tot de uitdeling. Daarna worden de stemmen gewist voor de nieuwe dag.
- Bij een unieke winnaar krijgt die +1 AP bovenop het dagelijkse punt.
  **Bij een gelijke stand krijgt iedere gelijkstaande levende speler de
  bonus.** Als niemand heeft gestemd, is er geen bonus.
- De bonus wordt ná een eventuele krimp uitgedeeld, zodat wie die dag
  door de krimp sterft geen punten meer krijgt.

## Krimpend speelveld (standaard uit)

- De host zet het interval (1–30 dagen, standaard 7). De eerste krimp is
  op uitdeling nummer *N* na de start (dag *N*), daarna elke *N* dagen, op het AP-tijdstip van de lobby.
- Elke krimp maakt de buitenste begaanbare ring onbegaanbaar
  (`arena_inset` + 1). Minimum speelbaar veld is 3×3, dus op een 6×6-bord
  stopt de krimp bij 4×4 (`max_inset = floor((grootte − 3) / 2)`).
- Spelers op de nieuwe ring verliezen 1 leven. Overleven ze, dan gaan ze
  naar het dichtstbijzijnde vrije begaanbare vakje (eerst Chebyshev, dan
  Euclidean naar het midden, dan een vaste (y, x)-volgorde). Spelers worden
  in volgorde van hun id verplaatst, zodat het deterministisch is.
- Is er géén vrij begaanbaar vakje meer, dan is de speler
  **vermorzeld**: 0 levens, uitgeschakeld.
- Sterven de laatste twee (of meer) in dezelfde krimp, dan is het
  **gelijkspel**.
- De UI toont wanneer de volgende krimp is en markeert de ring die dan
  verdwijnt.

## Gedwongen staakt-het-vuren (standaard uit)

- De host tekent één of meer periodes op een 24-uursklok (0 bovenaan, met
  de klok mee), of vult exacte tijden in. Periodes mogen over middernacht
  lopen. Een periode met gelijke begin- en eindtijd wordt genegeerd.
  Overlappende periodes worden voor de countdown samengevoegd.
- Tijden zijn wandkloktijden in de **tijdzone van de host** (`rules.tz`, zie
  “Tijdzones”). Bij de overgang naar
  zomertijd is een periode korter in echte seconden (het overgeslagen uur
  telt niet); bij de terugzetting is hij langer (het herhaalde uur telt
  twee keer). Het einde van een periode is exclusief (06:00 precies is
  niet meer staakt-het-vuren als de periode tot 06:00 loopt).
- Tijdens het staakt-het-vuren is schieten server-side geweigerd
  (`ceasefire`). Bewegen, punten geven, bereik vergroten, overgeven,
  stemmen, notities en chat blijven mogelijk. De knop Aanvallen is
  uitgeschakeld met een toelichting.
- Onder de AP-timer staat “Tijd over in het staakt-het-vuren: HH:MM:SS”
  of “Tijd tot het staakt-het-vuren: HH:MM:SS”.
- Staat de regel aan zonder periodes, dan is er feitelijk geen
  staakt-het-vuren.

## Lobby, sessie, verwante zaken

- Uitnodigen gaat via een 6-teken-code (zonder 0/O/I/1/L) en een deelbare
  link `?join=CODE`. Na inloggen kom je terug bij die link.
- Verlaat de host de lobby vóór de start, dan wordt de vroegst
  aangesloten overgebleven speler de nieuwe host. Is de lobby leeg, dan
  verdwijnt hij.
- Tijdens een lopend spel kun je niet meer instappen. Eén speler mag in
  meerdere spellen tegelijk zitten.
- Overgeven maakt je dood (0 levens, vlag `surrendered`); je mag daarna
  nog wel als jury stemmen en berichten sturen, als de jury aan staat.
- Privénotities staan server-side, per kijker, over een andere (of jezelf)
  speler. Chat is 1:1, alleen zichtbaar voor de twee betrokkenen. Dode
  spelers mogen nog chatten.
- Sessie duurt 30 dagen en wordt bij activiteit verlengd. Avatar komt uit
  het profiel van auth.timfalken.com (`avatar_url` / `avatar` / `picture`)
  of, als fallback, `https://auth.timfalken.com/avatar/{id}`. Die
  fallback-URL bestaat niet voor iemand zonder profielplaatje (404).
- **Speelstuk zonder (werkend) profielplaatje** (t1179): elk speelstuk is
  altijd een zichtbare cirkel in de unieke spelerskleur (vulling én rand)
  met de initialen (eerste letters van het eerste en laatste naamdeel,
  gescheiden door spatie, `_`, `-` of `.`; bij één woord de eerste twee
  letters). Een profielplaatje wordt er alleen bovenop gelegd. Laadt het
  niet (lege URL, 404, geblokkeerd, 0×0), dan verdwijnt alleen het
  plaatje en blijven de initialen staan. Mislukte URL's worden per
  paginabezoek onthouden, zodat de 3-secondenpoll ze niet steeds opnieuw
  probeert (geen flikkering). Zelfde stuk in lobbylijst, jurylijst en
  menu. Tekstkleur (zwart/wit) volgt de helderheid van de spelerskleur.
- Oorzaak van de onzichtbare tegenstander: het bord haalde het `<img>`
  uit een wrapper en zette het in het vakje. Bij een laadfout werd het
  `<img>` verwijderd en de initialen-fallback in de (losgekoppelde)
  wrapper gezet, dus nergens op het scherm. Bij elke tik/poll werd het
  bord opnieuw opgebouwd met een nieuw `<img>`, dat even zichtbaar was
  tot de 404 binnenkwam — vandaar “alleen kort zichtbaar na tikken”.
- Taalcodes volgen Meteors: intern `zh` (HTML `zh-Hans`), vlaggen `gb`,
  `jp`, `cn`, `kr`. De keuze staat in `localStorage` (`allianties-locale`)
  en in het profiel.
- Extra regels (harten op het bord, levens kopen, AP plunderen bij een
  kill, …) zijn nog niet gebouwd; de motor is modulair zodat ze later als
  schakelaar kunnen.



## Actiepunten-tijdstip en plunderen

- Elke lobby heeft een **dagelijks AP-tijdstip** (in de tijdzone van de host),
  standaard 00:00. De host stelt het in met een tijdkiezer. Op dat
  moment gebeuren de AP-uitdeling, de jurybonus en (indien aan) het
  krimpen van het veld. Een “dag” in het spel is één zo’n uitdeling.
  Bij een DST-lentesprong bestaat een gekozen tijd in de overgeslagen
  periode (bijv. 02:30) niet; PHP landt op het eerste geldige moment
  daarna (typisch 03:30 CEST). Bij de herfst blijft 02:30 geldig
  (PHP gebruikt de eerste voorkomst).
- **Actiepunten plunderen bij een kill** staat standaard uit. Als de
  host het aanzet, krijgt de schutter bij een *uitschakelend* schot de
  resterende AP van het doelwit (ná het uitgeven van 1 AP voor het
  schot). Overgave en krimp/verpletteren geven geen AP. Het geplunderde
  aantal staat op het schot-event (`loot`) en is zichtbaar volgens de
  AP-zichtbaarheidsregel (de schutter ziet het altijd).
- Er zijn **geen harten** op het bord en je kunt **geen levens kopen**.
  Die regels bestaan niet als optie.

## Tijdlijnbediening

Op de tijdlijnbalk: stap terug, afspelen/pauzeren, stap vooruit, en
“Live” (naar het heden). Toetsen (alleen in een lopend spel, niet in
een invoerveld): ← stap terug, → stap vooruit, spatiebalk afspelen of
pauzeren, End springt naar het heden. Klikken/tikken ergens op de balk
springt naar het dichtstbijzijnde event; slepen scrubt.

## Zichtbaarheid (lobby-opties)

Standaard staat elke optie op de meest open waarde, **Openbaar**. De host
kiest dit in de lobby; na de start liggen de regels vast. De server filtert
iedere API-response (volle staat, sync, tijdlijn, replay) per kijker. Eigen
gegevens (levens, actiepunten, bereik) zijn altijd zichtbaar voor jezelf.
Verplaatsingen zijn altijd openbaar. Levend/dood en overgave zijn altijd
openbaar (nodig voor de jury en de winstvoorwaarde); verborgen is alleen
het resterende *aantal* levens.

- **Schoten:** *Openbaar* — iedereen ziet elk schot (schutter, doelwit,
  schade). *Alleen uitschakelende schoten zijn openbaar* — een schot dat
  niet elimineert is alleen zichtbaar voor schutter en doelwit; een
  uitschakelend schot is voor iedereen zichtbaar (inclusief wie schoot).
  *Alleen bekend bij het doelwit* — alleen schutter en doelwit zien het
  schot, ook als het elimineert; anderen zien wel de dood, maar zonder
  schutter (`by` wordt weggelaten). *Alleen een uitschakelend schot is
  bekend bij het doelwit* — een niet-uitschakelend schot is alleen voor
  de schutter zichtbaar (het doelwit ziet het eigen levensverlies, niet
  van wie); een uitschakelend schot is bekend bij schutter en doelwit;
  anderen zien de dood zonder schutter.
- **Giften:** *Openbaar* — iedereen ziet gever, ontvanger en aantal.
  *Alleen bekend bij de ontvanger* — gever en ontvanger zien de gift
  volledig; anderen zien niets. *Anoniem* — de ontvanger ziet dat hij
  punten krijgt en hoeveel, maar niet van wie (`player` wordt weggelaten,
  `anonymous: true`). Anderen zien de gift niet. De gever ziet de eigen
  gift altijd.
- **Actiepuntentotalen:** *Openbaar*, *Binnen bereik*, of *Verborgen*.
  Bij verborgen is alleen je eigen totaal in de staat aanwezig; in het
  dagelijkse event staat alleen je eigen toekenning. Bij *Binnen bereik*
  zie je het AP-totaal van een andere speler als die speler in **jouw**
  schootsveld staat: Chebyshev-afstand tot die speler ≤ **jouw** (de
  kijker’s) huidige bereik. Hetzelfde geldt voor toekenningen in het
  dagelijkse event en voor `loot` op een schot (zichtbaar als je de
  AP van de schutter mag zien; de schutter ziet het altijd).
  Jury-winnaars blijven openbaar (de bekendmaking); stemtellingen
  worden niet meegestuurd.
- **Bereik:** *Openbaar*, *Bekend bij spelers binnen bereik*, of
  *Verborgen*. “Bekend bij spelers binnen bereik” betekent: Chebyshev-
  afstand tot die speler ≤ **diens** huidige bereik (jij staat in
  **hun** schootsveld). Dit is het **omgekeerde** criterium van
  “Binnen bereik” bij levens en actiepunten. Voorbeeld: jij hebt
  bereik 2, de ander bereik 4, afstand 3 — jij ziet hun bereik (jij
  staat in hun schootsveld) maar niet hun levens of AP (zij staan
  niet in het jouwe). Upgrade-events volgen dezelfde regel als het
  bereik-stat, op basis van de *huidige* posities (niet de historische).
- **Levens:** *Openbaar*, *Binnen bereik*, of *Verborgen*. “Binnen
  bereik” gebruikt hetzelfde criterium als bij actiepunten: afstand ≤
  **jouw** bereik (huidige posities). Bij een zichtbaar schot gaat
  `lives_left` alleen mee als je de levens van het doelwit mag zien
  (openbaar, jij bent het doelwit, of het doelwit staat in jouw
  bereik). De schade van het schot (`damage`, nu altijd 1) is wel
  zichtbaar als je het schot mag zien — dat lekt het resterende
  aantal levens niet. De `hurt`-lijst van een krimp volgt dezelfde
  levens-zichtbaarheid.
- Verborgen events worden **volledig weggelaten** (geen generiek streepje
  op de tijdlijn): een streepje zou lekken *dat* er iets gebeurde.
  Ticks en replay tonen alleen events die deze kijker mag zien.
- De opgeslagen wedstrijd blijft ongefilterd; `present()` stuurt een
  kopie. Combinaties van opties kunnen aftellen mogelijk maken (bijv.
  openbare AP-totalen plus anonieme giften); dat is een keuze van de
  host. Bij openbare levens en verborgen niet-uitschakelende schoten
  kan een levensverandering in de staat zichtbaar zijn zonder bijbehorend
  schot-event; de replay verzint geen events.

## Weergave van events (geen tekstlog)

Er is geen tekstlog van zetten. Events zijn alleen te zien in de
**video-weergave** van de tijdlijn (afspelen 1 actie per 0,5 s, of
scrubben):

- Een gift: groene pijl van gever naar ontvanger, met het aantal AP.
  Bij een anonieme gift (voor de ontvanger) verschijnt alleen “+N” op de
  ontvanger, **zonder** bronpijl — een pijl “van nergens” zou nog een
  richting kunnen suggereren en zo de gever verraden.
- Een schot: rode pijl van schutter naar doelwit, met de schade (levens
  die dit schot kost). Alleen als dit event voor de kijker zichtbaar is.
- Een zet: de pion schuift van het oude naar het nieuwe vak.
- Een bereik-upgrade: een korte gouden pulsering om de pion.
- Levens, AP en bereik staan in het Info-venster van een speler, en
  alleen als ze voor de kijker zichtbaar zijn (anders “Verborgen”).
  Er staan geen permanente getallen op het bord voor verborgen stats.

Klikken of tikken **ergens op de tijdlijnbalk** springt naar het
dichtstbijzijnde event. Slepen scrubt door de events. Dit werkt met
muis en touch (`pointer` + `touch`, `touch-action: none`).

De uitnodigingslink (`?join=CODE`) herstelt na een verversing de lobby
of, als het spel al loopt en je lid bent, het lopende spel.

## Techniek

- Geen WebGL/frameworkv3: het bord, de avatars, de modals en de tijdlijn
  zijn DOM+CSS, beter voor touch, tekst en toegankelijkheid. De rest van
  de stapel (PHP-API, SQLite, CI, OAuth, i18n) volgt Meteors.
- Elke mutatie loopt in `BEGIN IMMEDIATE`. Een geweigerde zet rolt terug.
- De client polt elke 3 seconden een licht `sync`-eindpunt (versie,
  servertijd, countdowns). Alleen bij een gewijzigde versie komt de volle
  staat, inclusief chat. Bij een verborgen tabblad stopt het pollen; bij
  terugkeer volgt een volle verversing.
- Lokale testers: `auth.php?test=1` t/m `?test=8`, alleen op localhost.
  Op de live site staat dat uit.
- Het OAuth-callbackpad is `https://projects.timfalken.com/allianties/callback.php`.
  Dat moet op auth.timfalken.com bij de bestaande client
  `projects.timfalken.com` worden toegevoegd. Het clientgeheim wordt níet
  opnieuw gegenereerd (dat zou de andere sites breken) en komt als
  projectgeheim `auth_client_secret` in de CI.

## Tijdzones

- Alle tijden worden getoond en ingevoerd in de **lokale tijdzone van de
  speler** (de IANA-zone van de browser, `Intl…resolvedOptions().timeZone`).
  Bij de tijdvelden en de klok staat subtiel “lokale tijd · <zone>”.
- De host definieert het AP-tijdstip en de staakt-het-vuren-periodes in
  zijn eigen lokale tijd. De server bewaart ze als wandkloktijd **plus de
  IANA-zone van de host** (`rules.tz`, standaard Europe/Amsterdam; onbekende
  zones of kale offsets zoals `+02:00` vallen terug op Europe/Amsterdam,
  omdat alleen een benoemde zone zomertijdregels heeft). Alle berekeningen
  (uitdeling, wel/geen staakt-het-vuren, aftellers) gebeuren op de server
  in die zone en leveren absolute tijdstempels; zomertijd is dus exact,
  ook als de zones van host en speler op verschillende dagen wisselen.
- Andere spelers zien dezelfde tijden omgerekend naar hun eigen zone. Een
  wandkloktijd omrekenen hangt af van de datum (zomertijd); de weergave
  gebruikt de **huidige dag** in de zone van de host. Rond een
  zomertijdwissel kan de getoonde tijd dus een dag later een uur
  verschuiven; de echte regel (op de server) verschuift niet.
- Na omrekening kan een periode over middernacht lopen (bijv. 14:00–20:00
  Amsterdam is 22:00–04:00 Tokyo); de klok draait de taartpunten mee.
- Bewerkt de host de regels vanuit een andere zone (bijv. op reis), dan
  worden eerst alle tijden naar die zone omgerekend en met die zone
  opgeslagen, zodat het formulier altijd in één zone werkt.

## Lobbyformulier tijdens bewerken

- Oorzaak van het slechte slepen en typen (t1171): elke 3 s haalde de
  browser de lobby opnieuw op. Na elke wijziging (ook de eigen opslag van
  de host, of een speler die joint) kwam er een nieuwe versie binnen en
  werd het hele regelsformulier opnieuw opgebouwd: de lijst met tijdvelden
  werd leeggemaakt en opnieuw aangemaakt (focus weg, half getypte waarde
  weg) en de klok-SVG werd vervangen. Bovendien bouwde de klok zichzelf
  bij **elke** muis-/vingerbeweging opnieuw op, waardoor de pointer
  capture verloren ging, en kon een poll met de oude serverwaarden de
  lokale, nog niet opgeslagen wijziging terugzetten.
- Nu: de klok wordt één keer opgebouwd; tijdens het slepen worden alleen de
  taartpunten en handvatten in dezelfde SVG bijgewerkt (pointer capture,
  `touch-action: none`, snappen op 15 minuten). Tijdvelden worden ter
  plekke bijgewerkt en een veld met focus wordt nooit overschreven.
  Zolang de host typt, sleept of een opslag onderweg is, winnen de lokale
  waarden van de poll. Opslaan gebeurt gedebounced (600 ms) en wacht tot
  een sleepbeweging klaar is.
- Alleen de host mag de regels wijzigen: de server weigert anderen met
  HTTP 403 (`not_host`); niet-hosts zien het formulier alleen-lezen met
  de melding “Alleen de host kan de spelregels aanpassen.”

## Spelscherm op mobiel (t1180)

- Het spelscherm is precies één schermhoogte (`100dvh`, dus de zichtbare
  hoogte, ook met de adresbalk van mobiele browsers). Kop, statusregel,
  bord en tijdlijn staan in één kolom; het bord neemt de resterende ruimte
  (container query, vierkant, maximaal 560 px). De pagina scrolt niet;
  alleen als er écht meer is (bijv. het jurypaneel) scrolt het spelscherm
  binnen zichzelf.
- De kop is in het spel niet meer `sticky`, zodat hij nooit over de
  statusregel valt. De taalknop staat in het spel rechtsboven naast de kop
  (de lijst klapt naar beneden open) in plaats van over de tijdlijn.

