BlueGit

projects-timfalken-com allianties

Files

allianties / docs / ASSUMPTIONS.md

ASSUMPTIONS.md

ASSUMPTIONS.md 18.8 KiB Download Raw

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.

Source
1# Aannames — Allianties
2
3Waar de specificatie ruimte liet, gelden deze keuzes. Ze zijn ook in de
4regelmotor (`server/lib/Engine.php`) en de tests vastgelegd.
5
6## Bord en plaatsing
7
8- Het bord is vierkant. De host kiest de zijde in de lobby (geheel getal
9 van **6 tot 24**). De voorgestelde grootte is
10 `max(6 + ceil(n / 2), n + 1)`, met een maximum van 24. `ceil` rondt
11 halven naar boven af (bij oneven n: drie spelers → `ceil(1,5) = 2` →
12 zijde 8). Voorbeelden: 2 spelers **7×7**; 3 spelers **8×8**; 6 spelers
13 **9×9**; 10 spelers **11×11**; 14 spelers **15×15**; 16 spelers
14 **17×17**. Voor n ≤ 10 overheerst `6 + ceil(n/2)`; daarna `n + 1`.
15- De suggestie wordt bijgewerkt als er spelers bij komen of weggaan,
16 **tenzij de host het veld handmatig heeft gewijzigd** (`grid_auto`).
17 “Gebruik de voorgestelde grootte” zet automatische bijwerking weer aan.
18- Bij de start controleert de server: zijde tussen 6 en 24, minstens
19 evenveel vakjes als spelers, en unieke startposities op het bord.
20 Anders wordt de start geweigerd (`bad_grid`). Een host mag bewust
21 kleiner kiezen dan de suggestie (bijvoorbeeld 6×6).
22- Startposities liggen op een ring rond het midden, beginnend bovenaan en
23 dan met de klok mee. Bij een botsing schuift de speler naar het dichtstbij
24 zijnde vrije vakje. Dode spelers blokkeren geen vakjes meer, maar blijven
25 visueel op hun laatste plek (uitgegrijsd). Op het voorgestelde 7×7
26 voor twee spelers staan ze ongeveer bovenaan en onderaan het midden,
27 buiten elkaars startbereik 2.
28- Maximaal 16 spelers per spel, minimaal 2 om te starten. Er is geen
29 aparte “klaar”-stap: de host start wanneer er minstens twee spelers zijn.
30- Kleuren van de omlijning worden in volgorde van aansluiting uit een vaste
31 palet van 16 contrasterende kleuren gekozen.
32
33## Actiepunten en tijd
34
35- Iedereen begint bij de start met 1 actiepunt, zodat je meteen kunt
36 handelen.
37- Daarna krijgt elke levende speler 1 punt bij elke dagelijkse uitdeling
38 (in de tijdzone van de host, zie “Tijdzones”). Het tijdstip is per lobby instelbaar, standaard
39 **00:00**, en volgt de wissel naar en van zomertijd. Als de server een
40 paar dagen offline was, worden gemiste uitdelingen bij de volgende
41 request ingehaald.
42- De countdown bovenaan is `HH:MM:SS` tot de volgende uitdeling, op basis
43 van de servertijd (met correctie voor klokverschil in de browser) en tikt
44 live zolang het tabblad open is.
45- Bereik heeft een plafond gelijk aan de maximale Chebyshev-afstand op het
46 bord (`grootte − 1`), zodat “het hele bord” het maximum is.
47- Meerdere actiepunten in één keer geven telt als één actie (één tik op de
48 tijdlijn).
49
50## Jury (standaard aan, in de lobby uit te zetten)
51
52- Alleen uitgeschakelde deelnemers (inclusief wie zich heeft overgegeven)
53 mogen stemmen, en alleen op een levende speler.
54- Stemmen zijn geheim: anderen zien jouw stem niet. Je kunt hem wijzigen
55 tot de uitdeling. Daarna worden de stemmen gewist voor de nieuwe dag.
56- Bij een unieke winnaar krijgt die +1 AP bovenop het dagelijkse punt.
57 **Bij een gelijke stand krijgt iedere gelijkstaande levende speler de
58 bonus.** Als niemand heeft gestemd, is er geen bonus.
59- De bonus wordt ná een eventuele krimp uitgedeeld, zodat wie die dag
60 door de krimp sterft geen punten meer krijgt.
61
62## Krimpend speelveld (standaard uit)
63
64- De host zet het interval (1–30 dagen, standaard 7). De eerste krimp is
65 op uitdeling nummer *N* na de start (dag *N*), daarna elke *N* dagen, op het AP-tijdstip van de lobby.
66- Elke krimp maakt de buitenste begaanbare ring onbegaanbaar
67 (`arena_inset` + 1). Minimum speelbaar veld is 3×3, dus op een 6×6-bord
68 stopt de krimp bij 4×4 (`max_inset = floor((grootte − 3) / 2)`).
69- Spelers op de nieuwe ring verliezen 1 leven. Overleven ze, dan gaan ze
70 naar het dichtstbijzijnde vrije begaanbare vakje (eerst Chebyshev, dan
71 Euclidean naar het midden, dan een vaste (y, x)-volgorde). Spelers worden
72 in volgorde van hun id verplaatst, zodat het deterministisch is.
73- Is er géén vrij begaanbaar vakje meer, dan is de speler
74 **vermorzeld**: 0 levens, uitgeschakeld.
75- Sterven de laatste twee (of meer) in dezelfde krimp, dan is het
76 **gelijkspel**.
77- De UI toont wanneer de volgende krimp is en markeert de ring die dan
78 verdwijnt.
79
80## Gedwongen staakt-het-vuren (standaard uit)
81
82- De host tekent één of meer periodes op een 24-uursklok (0 bovenaan, met
83 de klok mee), of vult exacte tijden in. Periodes mogen over middernacht
84 lopen. Een periode met gelijke begin- en eindtijd wordt genegeerd.
85 Overlappende periodes worden voor de countdown samengevoegd.
86- Tijden zijn wandkloktijden in de **tijdzone van de host** (`rules.tz`, zie
87 “Tijdzones”). Bij de overgang naar
88 zomertijd is een periode korter in echte seconden (het overgeslagen uur
89 telt niet); bij de terugzetting is hij langer (het herhaalde uur telt
90 twee keer). Het einde van een periode is exclusief (06:00 precies is
91 niet meer staakt-het-vuren als de periode tot 06:00 loopt).
92- Tijdens het staakt-het-vuren is schieten server-side geweigerd
93 (`ceasefire`). Bewegen, punten geven, bereik vergroten, overgeven,
94 stemmen, notities en chat blijven mogelijk. De knop Aanvallen is
95 uitgeschakeld met een toelichting.
96- Onder de AP-timer staat “Tijd over in het staakt-het-vuren: HH:MM:SS”
97 of “Tijd tot het staakt-het-vuren: HH:MM:SS”.
98- Staat de regel aan zonder periodes, dan is er feitelijk geen
99 staakt-het-vuren.
100
101## Lobby, sessie, verwante zaken
102
103- Uitnodigen gaat via een 6-teken-code (zonder 0/O/I/1/L) en een deelbare
104 link `?join=CODE`. Na inloggen kom je terug bij die link.
105- Verlaat de host de lobby vóór de start, dan wordt de vroegst
106 aangesloten overgebleven speler de nieuwe host. Is de lobby leeg, dan
107 verdwijnt hij.
108- Tijdens een lopend spel kun je niet meer instappen. Eén speler mag in
109 meerdere spellen tegelijk zitten.
110- Overgeven maakt je dood (0 levens, vlag `surrendered`); je mag daarna
111 nog wel als jury stemmen en berichten sturen, als de jury aan staat.
112- Privénotities staan server-side, per kijker, over een andere (of jezelf)
113 speler. Chat is 1:1, alleen zichtbaar voor de twee betrokkenen. Dode
114 spelers mogen nog chatten.
115- Sessie duurt 30 dagen en wordt bij activiteit verlengd. Avatar komt uit
116 het profiel van auth.timfalken.com (`avatar_url` / `avatar` / `picture`)
117 of, als fallback, `https://auth.timfalken.com/avatar/{id}`. Die
118 fallback-URL bestaat niet voor iemand zonder profielplaatje (404).
119- **Speelstuk zonder (werkend) profielplaatje** (t1179): elk speelstuk is
120 altijd een zichtbare cirkel in de unieke spelerskleur (vulling én rand)
121 met de initialen (eerste letters van het eerste en laatste naamdeel,
122 gescheiden door spatie, `_`, `-` of `.`; bij één woord de eerste twee
123 letters). Een profielplaatje wordt er alleen bovenop gelegd. Laadt het
124 niet (lege URL, 404, geblokkeerd, 0×0), dan verdwijnt alleen het
125 plaatje en blijven de initialen staan. Mislukte URL's worden per
126 paginabezoek onthouden, zodat de 3-secondenpoll ze niet steeds opnieuw
127 probeert (geen flikkering). Zelfde stuk in lobbylijst, jurylijst en
128 menu. Tekstkleur (zwart/wit) volgt de helderheid van de spelerskleur.
129- Oorzaak van de onzichtbare tegenstander: het bord haalde het `<img>`
130 uit een wrapper en zette het in het vakje. Bij een laadfout werd het
131 `<img>` verwijderd en de initialen-fallback in de (losgekoppelde)
132 wrapper gezet, dus nergens op het scherm. Bij elke tik/poll werd het
133 bord opnieuw opgebouwd met een nieuw `<img>`, dat even zichtbaar was
134 tot de 404 binnenkwam — vandaar “alleen kort zichtbaar na tikken”.
135- Taalcodes volgen Meteors: intern `zh` (HTML `zh-Hans`), vlaggen `gb`,
136 `jp`, `cn`, `kr`. De keuze staat in `localStorage` (`allianties-locale`)
137 en in het profiel.
138- Extra regels (harten op het bord, levens kopen, AP plunderen bij een
139 kill, …) zijn nog niet gebouwd; de motor is modulair zodat ze later als
140 schakelaar kunnen.
141
142
143
144## Actiepunten-tijdstip en plunderen
145
146- Elke lobby heeft een **dagelijks AP-tijdstip** (in de tijdzone van de host),
147 standaard 00:00. De host stelt het in met een tijdkiezer. Op dat
148 moment gebeuren de AP-uitdeling, de jurybonus en (indien aan) het
149 krimpen van het veld. Een “dag” in het spel is één zo’n uitdeling.
150 Bij een DST-lentesprong bestaat een gekozen tijd in de overgeslagen
151 periode (bijv. 02:30) niet; PHP landt op het eerste geldige moment
152 daarna (typisch 03:30 CEST). Bij de herfst blijft 02:30 geldig
153 (PHP gebruikt de eerste voorkomst).
154- **Actiepunten plunderen bij een kill** staat standaard uit. Als de
155 host het aanzet, krijgt de schutter bij een *uitschakelend* schot de
156 resterende AP van het doelwit (ná het uitgeven van 1 AP voor het
157 schot). Overgave en krimp/verpletteren geven geen AP. Het geplunderde
158 aantal staat op het schot-event (`loot`) en is zichtbaar volgens de
159 AP-zichtbaarheidsregel (de schutter ziet het altijd).
160- Er zijn **geen harten** op het bord en je kunt **geen levens kopen**.
161 Die regels bestaan niet als optie.
162
163## Tijdlijnbediening
164
165Op de tijdlijnbalk: stap terug, afspelen/pauzeren, stap vooruit, en
166“Live” (naar het heden). Toetsen (alleen in een lopend spel, niet in
167een invoerveld): ← stap terug, → stap vooruit, spatiebalk afspelen of
168pauzeren, End springt naar het heden. Klikken/tikken ergens op de balk
169springt naar het dichtstbijzijnde event; slepen scrubt.
170
171## Zichtbaarheid (lobby-opties)
172
173Standaard staat elke optie op de meest open waarde, **Openbaar**. De host
174kiest dit in de lobby; na de start liggen de regels vast. De server filtert
175iedere API-response (volle staat, sync, tijdlijn, replay) per kijker. Eigen
176gegevens (levens, actiepunten, bereik) zijn altijd zichtbaar voor jezelf.
177Verplaatsingen zijn altijd openbaar. Levend/dood en overgave zijn altijd
178openbaar (nodig voor de jury en de winstvoorwaarde); verborgen is alleen
179het resterende *aantal* levens.
180
181- **Schoten:** *Openbaar* — iedereen ziet elk schot (schutter, doelwit,
182 schade). *Alleen uitschakelende schoten zijn openbaar* — een schot dat
183 niet elimineert is alleen zichtbaar voor schutter en doelwit; een
184 uitschakelend schot is voor iedereen zichtbaar (inclusief wie schoot).
185 *Alleen bekend bij het doelwit* — alleen schutter en doelwit zien het
186 schot, ook als het elimineert; anderen zien wel de dood, maar zonder
187 schutter (`by` wordt weggelaten). *Alleen een uitschakelend schot is
188 bekend bij het doelwit* — een niet-uitschakelend schot is alleen voor
189 de schutter zichtbaar (het doelwit ziet het eigen levensverlies, niet
190 van wie); een uitschakelend schot is bekend bij schutter en doelwit;
191 anderen zien de dood zonder schutter.
192- **Giften:** *Openbaar* — iedereen ziet gever, ontvanger en aantal.
193 *Alleen bekend bij de ontvanger* — gever en ontvanger zien de gift
194 volledig; anderen zien niets. *Anoniem* — de ontvanger ziet dat hij
195 punten krijgt en hoeveel, maar niet van wie (`player` wordt weggelaten,
196 `anonymous: true`). Anderen zien de gift niet. De gever ziet de eigen
197 gift altijd.
198- **Actiepuntentotalen:** *Openbaar*, *Binnen bereik*, of *Verborgen*.
199 Bij verborgen is alleen je eigen totaal in de staat aanwezig; in het
200 dagelijkse event staat alleen je eigen toekenning. Bij *Binnen bereik*
201 zie je het AP-totaal van een andere speler als die speler in **jouw**
202 schootsveld staat: Chebyshev-afstand tot die speler ≤ **jouw** (de
203 kijker’s) huidige bereik. Hetzelfde geldt voor toekenningen in het
204 dagelijkse event en voor `loot` op een schot (zichtbaar als je de
205 AP van de schutter mag zien; de schutter ziet het altijd).
206 Jury-winnaars blijven openbaar (de bekendmaking); stemtellingen
207 worden niet meegestuurd.
208- **Bereik:** *Openbaar*, *Bekend bij spelers binnen bereik*, of
209 *Verborgen*. “Bekend bij spelers binnen bereik” betekent: Chebyshev-
210 afstand tot die speler ≤ **diens** huidige bereik (jij staat in
211 **hun** schootsveld). Dit is het **omgekeerde** criterium van
212 “Binnen bereik” bij levens en actiepunten. Voorbeeld: jij hebt
213 bereik 2, de ander bereik 4, afstand 3 — jij ziet hun bereik (jij
214 staat in hun schootsveld) maar niet hun levens of AP (zij staan
215 niet in het jouwe). Upgrade-events volgen dezelfde regel als het
216 bereik-stat, op basis van de *huidige* posities (niet de historische).
217- **Levens:** *Openbaar*, *Binnen bereik*, of *Verborgen*. “Binnen
218 bereik” gebruikt hetzelfde criterium als bij actiepunten: afstand ≤
219 **jouw** bereik (huidige posities). Bij een zichtbaar schot gaat
220 `lives_left` alleen mee als je de levens van het doelwit mag zien
221 (openbaar, jij bent het doelwit, of het doelwit staat in jouw
222 bereik). De schade van het schot (`damage`, nu altijd 1) is wel
223 zichtbaar als je het schot mag zien — dat lekt het resterende
224 aantal levens niet. De `hurt`-lijst van een krimp volgt dezelfde
225 levens-zichtbaarheid.
226- Verborgen events worden **volledig weggelaten** (geen generiek streepje
227 op de tijdlijn): een streepje zou lekken *dat* er iets gebeurde.
228 Ticks en replay tonen alleen events die deze kijker mag zien.
229- De opgeslagen wedstrijd blijft ongefilterd; `present()` stuurt een
230 kopie. Combinaties van opties kunnen aftellen mogelijk maken (bijv.
231 openbare AP-totalen plus anonieme giften); dat is een keuze van de
232 host. Bij openbare levens en verborgen niet-uitschakelende schoten
233 kan een levensverandering in de staat zichtbaar zijn zonder bijbehorend
234 schot-event; de replay verzint geen events.
235
236## Weergave van events (geen tekstlog)
237
238Er is geen tekstlog van zetten. Events zijn alleen te zien in de
239**video-weergave** van de tijdlijn (afspelen 1 actie per 0,5 s, of
240scrubben):
241
242- Een gift: groene pijl van gever naar ontvanger, met het aantal AP.
243 Bij een anonieme gift (voor de ontvanger) verschijnt alleen “+N” op de
244 ontvanger, **zonder** bronpijl — een pijl “van nergens” zou nog een
245 richting kunnen suggereren en zo de gever verraden.
246- Een schot: rode pijl van schutter naar doelwit, met de schade (levens
247 die dit schot kost). Alleen als dit event voor de kijker zichtbaar is.
248- Een zet: de pion schuift van het oude naar het nieuwe vak.
249- Een bereik-upgrade: een korte gouden pulsering om de pion.
250- Levens, AP en bereik staan in het Info-venster van een speler, en
251 alleen als ze voor de kijker zichtbaar zijn (anders “Verborgen”).
252 Er staan geen permanente getallen op het bord voor verborgen stats.
253
254Klikken of tikken **ergens op de tijdlijnbalk** springt naar het
255dichtstbijzijnde event. Slepen scrubt door de events. Dit werkt met
256muis en touch (`pointer` + `touch`, `touch-action: none`).
257
258De uitnodigingslink (`?join=CODE`) herstelt na een verversing de lobby
259of, als het spel al loopt en je lid bent, het lopende spel.
260
261## Techniek
262
263- Geen WebGL/frameworkv3: het bord, de avatars, de modals en de tijdlijn
264 zijn DOM+CSS, beter voor touch, tekst en toegankelijkheid. De rest van
265 de stapel (PHP-API, SQLite, CI, OAuth, i18n) volgt Meteors.
266- Elke mutatie loopt in `BEGIN IMMEDIATE`. Een geweigerde zet rolt terug.
267- De client polt elke 3 seconden een licht `sync`-eindpunt (versie,
268 servertijd, countdowns). Alleen bij een gewijzigde versie komt de volle
269 staat, inclusief chat. Bij een verborgen tabblad stopt het pollen; bij
270 terugkeer volgt een volle verversing.
271- Lokale testers: `auth.php?test=1` t/m `?test=8`, alleen op localhost.
272 Op de live site staat dat uit.
273- Het OAuth-callbackpad is `https://projects.timfalken.com/allianties/callback.php`.
274 Dat moet op auth.timfalken.com bij de bestaande client
275 `projects.timfalken.com` worden toegevoegd. Het clientgeheim wordt níet
276 opnieuw gegenereerd (dat zou de andere sites breken) en komt als
277 projectgeheim `auth_client_secret` in de CI.
278
279## Tijdzones
280
281- Alle tijden worden getoond en ingevoerd in de **lokale tijdzone van de
282 speler** (de IANA-zone van de browser, `Intl…resolvedOptions().timeZone`).
283 Bij de tijdvelden en de klok staat subtiel “lokale tijd · <zone>”.
284- De host definieert het AP-tijdstip en de staakt-het-vuren-periodes in
285 zijn eigen lokale tijd. De server bewaart ze als wandkloktijd **plus de
286 IANA-zone van de host** (`rules.tz`, standaard Europe/Amsterdam; onbekende
287 zones of kale offsets zoals `+02:00` vallen terug op Europe/Amsterdam,
288 omdat alleen een benoemde zone zomertijdregels heeft). Alle berekeningen
289 (uitdeling, wel/geen staakt-het-vuren, aftellers) gebeuren op de server
290 in die zone en leveren absolute tijdstempels; zomertijd is dus exact,
291 ook als de zones van host en speler op verschillende dagen wisselen.
292- Andere spelers zien dezelfde tijden omgerekend naar hun eigen zone. Een
293 wandkloktijd omrekenen hangt af van de datum (zomertijd); de weergave
294 gebruikt de **huidige dag** in de zone van de host. Rond een
295 zomertijdwissel kan de getoonde tijd dus een dag later een uur
296 verschuiven; de echte regel (op de server) verschuift niet.
297- Na omrekening kan een periode over middernacht lopen (bijv. 14:00–20:00
298 Amsterdam is 22:00–04:00 Tokyo); de klok draait de taartpunten mee.
299- Bewerkt de host de regels vanuit een andere zone (bijv. op reis), dan
300 worden eerst alle tijden naar die zone omgerekend en met die zone
301 opgeslagen, zodat het formulier altijd in één zone werkt.
302
303## Lobbyformulier tijdens bewerken
304
305- Oorzaak van het slechte slepen en typen (t1171): elke 3 s haalde de
306 browser de lobby opnieuw op. Na elke wijziging (ook de eigen opslag van
307 de host, of een speler die joint) kwam er een nieuwe versie binnen en
308 werd het hele regelsformulier opnieuw opgebouwd: de lijst met tijdvelden
309 werd leeggemaakt en opnieuw aangemaakt (focus weg, half getypte waarde
310 weg) en de klok-SVG werd vervangen. Bovendien bouwde de klok zichzelf
311 bij **elke** muis-/vingerbeweging opnieuw op, waardoor de pointer
312 capture verloren ging, en kon een poll met de oude serverwaarden de
313 lokale, nog niet opgeslagen wijziging terugzetten.
314- Nu: de klok wordt één keer opgebouwd; tijdens het slepen worden alleen de
315 taartpunten en handvatten in dezelfde SVG bijgewerkt (pointer capture,
316 `touch-action: none`, snappen op 15 minuten). Tijdvelden worden ter
317 plekke bijgewerkt en een veld met focus wordt nooit overschreven.
318 Zolang de host typt, sleept of een opslag onderweg is, winnen de lokale
319 waarden van de poll. Opslaan gebeurt gedebounced (600 ms) en wacht tot
320 een sleepbeweging klaar is.
321- Alleen de host mag de regels wijzigen: de server weigert anderen met
322 HTTP 403 (`not_host`); niet-hosts zien het formulier alleen-lezen met
323 de melding “Alleen de host kan de spelregels aanpassen.”
324
325## Spelscherm op mobiel (t1180)
326
327- Het spelscherm is precies één schermhoogte (`100dvh`, dus de zichtbare
328 hoogte, ook met de adresbalk van mobiele browsers). Kop, statusregel,
329 bord en tijdlijn staan in één kolom; het bord neemt de resterende ruimte
330 (container query, vierkant, maximaal 560 px). De pagina scrolt niet;
331 alleen als er écht meer is (bijv. het jurypaneel) scrolt het spelscherm
332 binnen zichzelf.
333- De kop is in het spel niet meer `sticky`, zodat hij nooit over de
334 statusregel valt. De taalknop staat in het spel rechtsboven naast de kop
335 (de lijst klapt naar beneden open) in plaats van over de tijdlijn.
336