BlueGit

projects-timfalken-com meteors

Files

meteors / docs / ASSUMPTIONS.md

ASSUMPTIONS.md

ASSUMPTIONS.md 15.8 KiB Download Raw

Aannames — Meteors

Waar de specificatie ruimte liet, staat hier hoe we het hebben ingevuld. Als iets onduidelijk was, volgden we de geest van Meteos en (voor de selectie-tween) Tim's bestaande KWin-effecten.

Fase 1 — physics-fixes (t1098u, t1100u, t1101u)

1. Vallende blokken landen op vliegende clusters

Een gespawnd (vallend) blok ging soms door een vliegende cluster heen, omdat de val alleen keek naar stilliggende/settling/locked blokken.

Aanname: het vallende blok botst alleen in dezelfde kolom. Het landt op het hoogste vliegende clustermlid onder hem, wordt vracht van die cluster (state = flying, zelfde clusterId en vy, geen vlam) en vliegt mee, inclusief omhoog als de cluster nog stijgt. Nieuwe vracht zit precies 1 tegel boven het hoogste clustermlid in die kolom.

Omgekeerd, als een stijgende cluster een vallend blok inrijdt, geldt hetzelfde. Een cluster die al geland is (rigid settling) telt als vaste ondergrond: daar landt een vallend blok gewoon op, het wordt geen vracht.

2. Grijze clusters landen als starre groep

Voorheen werd elke kolom bij landing platgedrukt op de stapel, waardoor gaten verdwenen.

Aanname: zodra één lid de vloer of een stil blok raakt, stopt de hele cluster als star lichaam. De relatieve posities blijven; een deel kan dus boven een gat blijven hangen. Gekleurde vracht (meegedragen blokken) blijft tot het einde van de settle-tijd van 3 s bij de groep — ze verkleuren niet opnieuw, maar vallen ook niet eerder. Na de conversie van de grijze blokken naar willekeurige kleuren laat de hele groep los. Blokken mét steun blijven liggen; blokken zónder steun vallen afzonderlijk, vanuit rust, met dezelfde zwaartekracht als een gewone val (eerst versnellen tot fallSpeed, zie punt 3). Gestapelde hangende blokken vallen als stapel (ze blijven op elkaar rusten, zonder te overlappen).

3. Vloeiende snelheidsovergang op de apex

Voorheen sprong vy op de apex in één frame naar -fallSpeed.

Aanname: vanaf de apex (vy = 0) versnelt de cluster (en een handmatige sprong) met constante fallAccel totdat fallSpeed is bereikt; daarna constante daalsnelheid. apexEaseTime = 0.15 * fallTime en fallAccel = fallSpeed / apexEaseTime. Lage luchtweerstand (kleine fallTime) geeft dus een kortere, snellere overgang. Voor Terra (fallTime = 3) is dat 0,45 s. Hetzelfde geldt voor hangende blokken die na conversie uit rust gaan vallen. Blokken die van boven het veld binnenkomen (spawn) starten al op fallSpeed — die vallen al een tijdje.

4. Bounce bij landing (planeetparameter)

Aanname: de bounce is visueel (squash van de sprite, plus een heel klein optisch terugveren in Y) en verandert de simulatiefysica niet. Elk blok dat op de vloer of op een ander blok landt, krijgt een bounce; hangende leden van een starre groep die niets raken, niet.

Snelheid hangt af van de luchtweerstand van het veld, via fallTime (1 = weinig lucht, 5 = veel lucht):

  • bounceDuration = 0.12 * fallTime (Terra: 0,36 s; bij fallTime = 1

twee keer zo snel als bij fallTime = 2, enz.)

  • bounceSquash = 0.16 (subtiele verticale squash naar 84%, met lichte

horizontale compensatie)

Beide zijn planeetparameters, klaar voor fase 3.

5. Handmatige sprong van het bovenste blok (t1100u)

Het naar boven slepen van een blok dat al het bovenste van zijn kolom is, moest een handmatige sprong starten (tot net onder de bovenrand). De core vroeg eerder dat de aanwijzer in de lege ruimte boven de stapel kwam (y > top + 1 + 0,25). Wie het bovenste blok vasthad en het voorbij zijn eigen positie trok, maar niet een hele tegel het gat in, kreeg geen sprong. Op touch kon lostpointercapture de sleep ook te vroeg beëindigen.

Aanname:

  • Begon de sleep al op het bovenste blok, dan is een trek van

LAUNCH_PULL = 0,35 tegel omhoog vanaf het drukpunt genoeg (“voorbij zijn eigen positie”), voor muis én touch (zelfde Pointer-Events-pad).

  • Begon de sleep lager in de stapel, dan blijft de oude drempel gelden:

eerst wisselen, en pas lanceren als de aanwijzer in de lege ruimte boven de (nieuwe) top zit. Zo lanceer je niet per ongeluk een blok dat je alleen naar de bovenste plek wilt schuiven.

  • De view luistert na pointerdown op window voor pointermove /

pointerup / pointercancel, zodat een sleep boven het canvas (nodig bij een volle kolom) niet verloren gaat. lostpointercapture beëindigt de sleep niet meer.

6. Selectie-tween (t1101u)

Een vastgehouden (geselecteerd) blok krijgt dezelfde schaal-animatie als de DEFAULT-instellingen van Tim's KWin Click Tween-effect.

Bron (op deze box): /workspace/click-tween/, specifiek:

  • settings.h: clickTime = 150 ms, releaseTime = 720 ms,

clickEasing = easeOutBack, releaseEasing = easeOutElastic

  • clicktween.cpp: pers-doel 0.8, loslaat-doel 1.0; een onderbroken

animatie start vanaf de huidige schaal (QVariantAnimation)

  • README.md: “krimpt naar 80% in 150 ms”, “groeit in 720 ms terug”,

“curveparameters zijn Qt-standaardwaarden”

Qt QEasingCurve-standaardwaarden, ook in de README genoemd:

  • Back-overshoot: 1.70158
  • Elastic: amplitude 1.0, periode 0.3

Het blok blijft op 80% zolang het geselecteerd is, en veert bij loslaten terug (ook als het ondertussen gelanceerd wordt). Muis en touch gebruiken dezelfde tween.

Fase 2 — multiplayer (samenvatting)

De miss-kans van 30% was de stage-2-parameter; stage 3 vervangt die door parameter (missChance, standaard 0,30); de planeetformule Planet.missChance (60%–5% via Power) is voor fase 3.

Deploy: vreemde bestanden en favicon.ico

De FTP-guard blokkeert alleen een duidelijk verkeerd doel (FTP-root, pad zonder meteors als laatste segment, map buiten $timftproot). Extra bestanden die al in de remote map staan, worden alleen gelogd: we gebruiken nooit --delete, dus ze blijven staan en zijn onschadelijk.

favicon.ico op de server wordt niet overschreven en niet verwijderd (mogelijk van Tim of de host). De deploy sluit dat bestand uit van de upload, ook als er lokaal een build/favicon.ico staat voor eigen gebruik.

7. Recolor stuurt blokken niet extra hard naar boven (t1102)

Na het herkleuren van een gelande grijze groep schoten blokken erboven soms heel hard van de bovenkant af. Oorzaak: een restant van de lanceringssnelheid (vy omhoog) of van een handmatige sprong, dat na de release in integrateFalling alsnog werd gebruikt. Daarnaast telde releaseUnsupported in dezelfde tick nog de hangende leden als steun, zodat blokken die erop stonden still bleven en in resolveMatches een match in de lucht konden vormen.

Aanname / aanpak:

  • Bij elke overgang naar still of falling na release (en bij het

loslaten van ongesteunde still-blokken) wordt clearFlightState aangeroepen: vy = 0, geen vlam, geen restant van een handmatige sprong.

  • releaseUnsupported draait opnieuw ná advanceSettle, zodat

blokken op zojuist losgelaten hangende leden vanaf rust vallen voordat er gematcht wordt.

  • Een échte nieuwe match na herkleuren is toegestaan en gebruikt de

normale sprong: launchVelocity(planet, jumpHeight) en de bijbehorende deceleratie, niet een opgetelde of achtergebleven vy. Dat zit in een regressietest (inclusief een kunstmatig achtergebleven vy = 40).

8. Botsende vliegende clusters smelten samen (t1102)

Twee (of meer) vliegende clusters die in dezelfde kolom in Y overlappen, worden één cluster.

Aanname: de nieuwe snelheid is het massagewogen gemiddelde op blok-aantal (niet het eenvoudige gemiddelde van de twee clustersnelheden):

vy = (n1·vy1 + n2·vy2) / (n1 + n2)

Hetzelfde gewogen gemiddelde geldt voor decel en jumpHeight. De fase is up als de samengevoegde vy > 0, anders down. Overlappende leden in één kolom worden van onder naar boven aangepakt, zodat de hogere strak op de lagere rust (geen twee blokken in dezelfde cel). Keuze vastgelegd: gewogen op blok-aantal.

9. Direct vastpakken, geen long-press (t1102 / t1103)

Er is geen long-press en geen wachttijd. Een blok wordt op pointerdown (tap of klik) meteen vastgepakt en blijft in de sleep zolang de vinger of muisknop omlaag is; loslaten beëindigt de sleep. De click-tween start in hetzelfde moment als pointerdown.

Aanname:

  • Verticaal: snap naar het dichtstbijzijnde still-blok in de kolom,

tot SNAP_Y = 0,65 tegel (een iets misplaatste druk pakt nog).

  • Horizontaal: op de druk, als de aanwijzer binnen

HORIZONTAL_SLOP = 0,35 tegel van de kolomrand zit, mag het buurblok gepakt worden. Tijdens de sleep blijft de startkolom vast, ook bij een iets diagonale beweging.

  • Wisselen: alleen een minimale opgetelde verticale afstand

SWAP_DISTANCE = 0,25 tegel per stap, zonder vertraging vóór de sleep. Een enkele grote pointermove (snelle swipe) loopt alle tegels langs (één wissel per tegel, geen overslaan). Er is geen extra drempel of hold voordat de sleep begint.

  • touch-action: none op canvas en pagina, preventDefault op

pointer-events met { passive: false }, setPointerCapture, en window-listeners voor move/up (zoals al bij t1100).

Fase 2 — multiplayer

Polling en autorisatie

  • De client pollt elke 0,75 s (Online.POLL_MS). Dat valt in de gevraagde

0,5–1 s. Er is geen websocket.

  • Login via auth.timfalken.com (/oauth/authorize, /oauth/token, /api/me),

client_id projects.timfalken.com. Callback https://projects.timfalken.com/meteors/callback.php. Het geheim zet Tim als protected projectgeheim auth_client_secret (niet opnieuw genereren); de deploy schrijft dan data/config.php. Zonder geheim blijft solo werken, met een duidelijke online-melding.

  • Testers auth.php?test=1 / ?test=2 alleen als localDev() waar is:

loopback-host én loopback-remote-adres (zelfde regel als verhalenboek).

  • Sessies staan in data/sessions, cookie-pad is de map van het script

(/meteors/ live). CSRF-token op elke POST (X-CSRF-Token).

Lobby en wedstrijd

  • Onbeperkt in de zin van de regel; praktisch maximum 32 (METEORS_MAX_PLAYERS).
  • De host start alleen als iedereen gereed is en er minstens twee spelers zijn.
  • Eigen veld is het hoofdspel; miniaturen van anderen staan in een strook

boven het veld (onder de HUD).

  • Afgeschoten blokjes gaan als outgoingShots mee in de volgende poll. De

server kiest het doel en gooit de miss-kans (niet de client, zodat die niet kan valsspelen). Doel is een willekeurige andere speler die nog niet is uitgeschakeld.

  • missChance is een parameter, standaard 0,30, op de lobby én op

GameCore. Planet.missChance (Power, 60 %–5 %) blijft voor stage 3 en wordt hier niet gebruikt.

  • Een raak schot komt na flight_duration = 1,2 s bij de ontvanger aan als

vallend donkergrijs vuil (ingestGarbage), dat na de gewone 3 s settle een willekeurige kleur krijgt.

  • De vlucht-tween is een kwadratische Bézier, met semi-willekeurige rotatie

(tot ±720°) en krimpen (“de verte in”). Een miss vliegt het scherm af en vervaagt; een raak schot landt in de miniatuur van het doel.

  • Uitgeschakelde spelers zijn toeschouwer (geen doelwit, geen shots). De

laatste die overblijft is 1e; de eerder uitgeschakelden 2e, 3e, … Het podium blijft 5 seconden (METEORS_PODIUM_SECONDS) en daarna gaat de lobby terug naar waiting (ready-vlaggen gereset).

  • data/ (sqlite, sessies) wordt nooit gespiegeld of gewist. Alleen

data/.htaccess (Require all denied) wordt na de mirror gezet. Als het projectgeheim auth_client_secret niet leeg is, schrijft de deploy data/config.php vanuit dat geheim (waarde nooit in de logs). Is het leeg of afwezig, dan blijft een bestaand bestand staan. De groep projects-timfalken-com en verhalenboek hebben dit geheim niet (alleen FTP); Tim zet het op het meteors-project. Optioneel: auth_client_id (standaard projects.timfalken.com). favicon.ico blijft ongemoeid. router.php is alleen voor lokale php -S en gaat niet mee naar live.

Fase 3 — planeten (velden)

  • Een veld is een planeet, met een naam voor de planeet en voor het volk.

De catalogus staat in server/lib/planets.json (bron voor JS én PHP) en telt 12 werelden, van makkelijk (Aurel: gameplay-Power 0, 60 % miss, getoonde Power 0 %) tot moeilijk (Cinder: gameplay-Power 1, 5 % miss, getoonde Power 92 %). Terra (44 % getoonde Power) blijft de standaard.

  • Zwaartekracht (jumpsToClear 1–4): één sprong haalt 1/jumpsToClear van

de veldhoogte. Luchtweerstand (fallTime 1–5 s tot de bodem). Massa (riseTime 0,5–3 s tot de apex). Lage massa en lage luchtweerstand en hoge zwaartekracht zijn moeilijker. Bounce-duur en apex-ease schalen al met fallTime (gebouwd in stage 1).

  • De interne (gameplay-)Power is het gemiddelde van die drie assen,

genormaliseerd 0–1. Miss-kans = 0,60 − 0,55 × Power (60 % bij 0, 5 % bij 1). Dat formule blijft de gameplay: schoten en de server gebruiken hem onveranderd. De getoonde Power in kiezer, HUD en lobby is 1 − miss / 0,60 als percentage (0 % miss → 100 % Power, 60 % miss → 0 % Power). Dat is alleen weergave (t1105). In multiplayer gebruikt de server de gameplay-Power van jouw planeet voor de blokjes die jij afschiet (niet de lobby-waarde, niet de planeet van het doel). De client kan dat niet vervalsen.

  • De vier getallen op de kiezers en in de HUD: g als

zwaartekrachtsconstante (m/s²), d als luchtdichtheid, F in newton, getoonde Power als percentage. Alleen de getallen, zonder uitleg. Verticale match van 3 = 120 % sprong, +5 % per extra blokje (al gebouwd, nergens uitgelegd).

  • Elk veld heeft een eigen set van 5 kleuren, elk met een uniek vormpje

en een uniek placeholder-PNG (build/images/block-{planeet}-{kleur}.png). Tim kan die bestanden zelf vervangen; de namen blijven gelijk. Te (her)genereren met python3 scripts/gen_planet_blocks.py.

  • Planeetkeuze komt vóór solo-spel (Spelen opent de kiezer) en in de

lobby (iedereen kiest zelf; zichtbaar voor de anderen). De keuze wordt onthouden in localStorage (meteors-planet). Na de start van een wedstrijd kun je niet meer wisselen.

t1104 — 1:1-slepen en spontane raketten

  • Oorzaak van de sleepbug: moveDrag werkte met een opgetelde

pointer-delta en een drempel van SWAP_DISTANCE (0,25 tegel). Een klein stukje sleep deed daardoor al een hele tegel, en één grote pointermove (typisch op touch) kon de rest van de kolom aflopen — precies “meestal gelijk helemaal omlaag of omhoog”. De doelrij was niet de rij onder de vinger, dus als de vinger stopte kon het blokje al aan de top of de bodem zitten. Daarnaast liep de pointer-mapping via canvas.width / app.tile, wat deltas zou vermenigvuldigen met de devicePixelRatio als de backing-store en de CSS-maat ooit uit elkaar lopen.

  • Nu: de doelrij is floor(pointerY), geklemd op de still-stapel van

de kolom. swapToward wisselt stap voor stap met elke buur, en stopt precies daar. Als de pointer stilstaat, beweegt er niets meer. Optrekken-boven-de-top om te lanceren blijft. Coordinaten komen uit getBoundingClientRect en de veldgrootte (10×13), zonder canvas-backing of app.tile.

  • Spontane rijen (na vallen, settle/recolor, cargo-attach op een

vliegende cluster, cluster-merge) worden altijd raketten, net als wanneer de speler ze maakt. In een al vliegende cluster geeft dat een extra sprong vanaf de huidige positie (checkChainRelaunch, dezelfde hoogte als bij een player-push). Mid-air hangend cargo na recolor valt nog steeds vanuit stilstand (t1102), geen launch.

t1105 — getoonde Power omgekeerd

  • Alleen de weergave. Gameplay power() en missChance() zijn

onveranderd (miss = 0,60 − 0,55 × power). Getoonde Power = 1 − missChance / 0,60, afgerond als percentage, in JS (Planet.displayValues / formatStats) en PHP (Planets::displayValues), dus op de planeetkiezer, in de HUD en in de lobby. 0 % miss is 100 % Power; Aurel 0 %, Terra 44 %, Cinder 92 %.

Source
1# Aannames — Meteors
2
3Waar de specificatie ruimte liet, staat hier hoe we het hebben ingevuld.
4Als iets onduidelijk was, volgden we de geest van Meteos en (voor de
5selectie-tween) Tim's bestaande KWin-effecten.
6
7## Fase 1 — physics-fixes (t1098u, t1100u, t1101u)
8
9### 1. Vallende blokken landen op vliegende clusters
10
11Een gespawnd (vallend) blok ging soms door een vliegende cluster heen,
12omdat de val alleen keek naar stilliggende/settling/locked blokken.
13
14Aanname: het vallende blok botst alleen in dezelfde kolom. Het landt op
15het hoogste vliegende clustermlid onder hem, wordt vracht van die
16cluster (`state = flying`, zelfde `clusterId` en `vy`, geen vlam) en
17vliegt mee, inclusief omhoog als de cluster nog stijgt. Nieuwe vracht
18zit precies 1 tegel boven het hoogste clustermlid in die kolom.
19
20Omgekeerd, als een stijgende cluster een vallend blok inrijdt, geldt
21hetzelfde. Een cluster die al geland is (rigid settling) telt als vaste
22ondergrond: daar landt een vallend blok gewoon op, het wordt geen vracht.
23
24### 2. Grijze clusters landen als starre groep
25
26Voorheen werd elke kolom bij landing platgedrukt op de stapel, waardoor
27gaten verdwenen.
28
29Aanname: zodra één lid de vloer of een stil blok raakt, stopt de hele
30cluster als star lichaam. De relatieve posities blijven; een deel kan
31dus boven een gat blijven hangen. Gekleurde vracht (meegedragen blokken)
32blijft tot het einde van de settle-tijd van 3 s bij de groep — ze
33verkleuren niet opnieuw, maar vallen ook niet eerder. Na de conversie
34van de grijze blokken naar willekeurige kleuren laat de hele groep los.
35Blokken mét steun blijven liggen; blokken zónder steun vallen
36afzonderlijk, vanuit rust, met dezelfde zwaartekracht als een gewone
37val (eerst versnellen tot `fallSpeed`, zie punt 3). Gestapelde hangende
38blokken vallen als stapel (ze blijven op elkaar rusten, zonder te
39overlappen).
40
41### 3. Vloeiende snelheidsovergang op de apex
42
43Voorheen sprong `vy` op de apex in één frame naar `-fallSpeed`.
44
45Aanname: vanaf de apex (vy = 0) versnelt de cluster (en een handmatige
46sprong) met constante `fallAccel` totdat `fallSpeed` is bereikt; daarna
47constante daalsnelheid. `apexEaseTime = 0.15 * fallTime` en
48`fallAccel = fallSpeed / apexEaseTime`. Lage luchtweerstand (kleine
49`fallTime`) geeft dus een kortere, snellere overgang. Voor Terra
50(`fallTime = 3`) is dat 0,45 s. Hetzelfde geldt voor hangende blokken
51die na conversie uit rust gaan vallen. Blokken die van boven het veld
52binnenkomen (spawn) starten al op `fallSpeed` — die vallen al een
53tijdje.
54
55### 4. Bounce bij landing (planeetparameter)
56
57Aanname: de bounce is visueel (squash van de sprite, plus een heel klein
58optisch terugveren in Y) en verandert de simulatiefysica niet. Elk blok
59dat op de vloer of op een ander blok landt, krijgt een bounce; hangende
60leden van een starre groep die niets raken, niet.
61
62Snelheid hangt af van de luchtweerstand van het veld, via `fallTime`
63(1 = weinig lucht, 5 = veel lucht):
64
65- `bounceDuration = 0.12 * fallTime` (Terra: 0,36 s; bij `fallTime = 1`
66 twee keer zo snel als bij `fallTime = 2`, enz.)
67- `bounceSquash = 0.16` (subtiele verticale squash naar 84%, met lichte
68 horizontale compensatie)
69
70Beide zijn planeetparameters, klaar voor fase 3.
71
72### 5. Handmatige sprong van het bovenste blok (t1100u)
73
74Het naar boven slepen van een blok dat al het bovenste van zijn kolom
75is, moest een handmatige sprong starten (tot net onder de bovenrand).
76De core vroeg eerder dat de aanwijzer in de lege ruimte boven de stapel
77kwam (`y > top + 1 + 0,25`). Wie het bovenste blok vasthad en het
78voorbij zijn eigen positie trok, maar niet een hele tegel het gat in,
79kreeg geen sprong. Op touch kon `lostpointercapture` de sleep ook te
80vroeg beëindigen.
81
82Aanname:
83
84- Begon de sleep al op het bovenste blok, dan is een trek van
85 `LAUNCH_PULL = 0,35` tegel omhoog vanaf het drukpunt genoeg
86 (“voorbij zijn eigen positie”), voor muis én touch (zelfde
87 Pointer-Events-pad).
88- Begon de sleep lager in de stapel, dan blijft de oude drempel gelden:
89 eerst wisselen, en pas lanceren als de aanwijzer in de lege ruimte
90 boven de (nieuwe) top zit. Zo lanceer je niet per ongeluk een blok
91 dat je alleen naar de bovenste plek wilt schuiven.
92- De view luistert na `pointerdown` op `window` voor `pointermove` /
93 `pointerup` / `pointercancel`, zodat een sleep boven het canvas
94 (nodig bij een volle kolom) niet verloren gaat. `lostpointercapture`
95 beëindigt de sleep niet meer.
96
97### 6. Selectie-tween (t1101u)
98
99Een vastgehouden (geselecteerd) blok krijgt dezelfde schaal-animatie
100als de **DEFAULT**-instellingen van Tim's KWin Click Tween-effect.
101
102Bron (op deze box): `/workspace/click-tween/`, specifiek:
103
104- `settings.h`: `clickTime = 150` ms, `releaseTime = 720` ms,
105 `clickEasing = easeOutBack`, `releaseEasing = easeOutElastic`
106- `clicktween.cpp`: pers-doel `0.8`, loslaat-doel `1.0`; een onderbroken
107 animatie start vanaf de huidige schaal (`QVariantAnimation`)
108- `README.md`: “krimpt naar 80% in 150 ms”, “groeit in 720 ms terug”,
109 “curveparameters zijn Qt-standaardwaarden”
110
111Qt `QEasingCurve`-standaardwaarden, ook in de README genoemd:
112
113- Back-overshoot: `1.70158`
114- Elastic: amplitude `1.0`, periode `0.3`
115
116Het blok blijft op 80% zolang het geselecteerd is, en veert bij loslaten
117terug (ook als het ondertussen gelanceerd wordt). Muis en touch gebruiken
118dezelfde tween.
119
120## Fase 2 — multiplayer (samenvatting)
121
122De miss-kans van 30% was de stage-2-parameter; stage 3 vervangt die door
123parameter (`missChance`, standaard 0,30); de planeetformule
124`Planet.missChance` (60%–5% via Power) is voor fase 3.
125
126## Deploy: vreemde bestanden en favicon.ico
127
128De FTP-guard blokkeert alleen een duidelijk verkeerd doel (FTP-root, pad
129zonder `meteors` als laatste segment, map buiten `$timftproot`). Extra
130bestanden die al in de remote map staan, worden alleen gelogd: we gebruiken
131nooit `--delete`, dus ze blijven staan en zijn onschadelijk.
132
133`favicon.ico` op de server wordt niet overschreven en niet verwijderd
134(mogelijk van Tim of de host). De deploy sluit dat bestand uit van de
135upload, ook als er lokaal een `build/favicon.ico` staat voor eigen gebruik.
136
137### 7. Recolor stuurt blokken niet extra hard naar boven (t1102)
138
139Na het herkleuren van een gelande grijze groep schoten blokken erboven
140soms heel hard van de bovenkant af. Oorzaak: een restant van de
141lanceringssnelheid (`vy` omhoog) of van een handmatige sprong, dat
142na de release in `integrateFalling` alsnog werd gebruikt. Daarnaast
143telde `releaseUnsupported` in dezelfde tick nog de hangende leden als
144steun, zodat blokken die erop stonden `still` bleven en in
145`resolveMatches` een match in de lucht konden vormen.
146
147Aanname / aanpak:
148
149- Bij elke overgang naar `still` of `falling` na release (en bij het
150 loslaten van ongesteunde still-blokken) wordt `clearFlightState`
151 aangeroepen: `vy = 0`, geen vlam, geen restant van een handmatige
152 sprong.
153- `releaseUnsupported` draait opnieuw ná `advanceSettle`, zodat
154 blokken op zojuist losgelaten hangende leden vanaf rust vallen
155 voordat er gematcht wordt.
156- Een échte nieuwe match na herkleuren is toegestaan en gebruikt de
157 normale sprong: `launchVelocity(planet, jumpHeight)` en de bijbehorende
158 deceleratie, niet een opgetelde of achtergebleven `vy`. Dat zit in
159 een regressietest (inclusief een kunstmatig achtergebleven `vy = 40`).
160
161### 8. Botsende vliegende clusters smelten samen (t1102)
162
163Twee (of meer) vliegende clusters die in dezelfde kolom in Y
164overlappen, worden één cluster.
165
166Aanname: de nieuwe snelheid is het **massagewogen gemiddelde op
167blok-aantal** (niet het eenvoudige gemiddelde van de twee
168clustersnelheden):
169
170 vy = (n1·vy1 + n2·vy2) / (n1 + n2)
171
172Hetzelfde gewogen gemiddelde geldt voor `decel` en `jumpHeight`.
173De fase is `up` als de samengevoegde `vy > 0`, anders `down`.
174Overlappende leden in één kolom worden van onder naar boven
175aangepakt, zodat de hogere strak op de lagere rust (geen twee
176blokken in dezelfde cel). Keuze vastgelegd: gewogen op blok-aantal.
177
178### 9. Direct vastpakken, geen long-press (t1102 / t1103)
179
180Er is **geen** long-press en **geen** wachttijd. Een blok wordt op
181`pointerdown` (tap of klik) meteen vastgepakt en blijft in de sleep
182zolang de vinger of muisknop omlaag is; loslaten beëindigt de sleep.
183De click-tween start in hetzelfde moment als `pointerdown`.
184
185Aanname:
186
187- Verticaal: snap naar het dichtstbijzijnde still-blok in de kolom,
188 tot `SNAP_Y = 0,65` tegel (een iets misplaatste druk pakt nog).
189- Horizontaal: op de druk, als de aanwijzer binnen
190 `HORIZONTAL_SLOP = 0,35` tegel van de kolomrand zit, mag het
191 buurblok gepakt worden. Tijdens de sleep blijft de startkolom
192 vast, ook bij een iets diagonale beweging.
193- Wisselen: alleen een **minimale** opgetelde verticale afstand
194 `SWAP_DISTANCE = 0,25` tegel per stap, zonder vertraging vóór de
195 sleep. Een enkele grote `pointermove` (snelle swipe) loopt alle
196 tegels langs (één wissel per tegel, geen overslaan). Er is geen
197 extra drempel of hold voordat de sleep begint.
198- `touch-action: none` op canvas en pagina, `preventDefault` op
199 pointer-events met `{ passive: false }`, `setPointerCapture`,
200 en window-listeners voor move/up (zoals al bij t1100).
201
202## Fase 2 — multiplayer
203
204### Polling en autorisatie
205
206- De client pollt elke **0,75 s** (`Online.POLL_MS`). Dat valt in de gevraagde
207 0,5–1 s. Er is geen websocket.
208- Login via auth.timfalken.com (`/oauth/authorize`, `/oauth/token`, `/api/me`),
209 client_id `projects.timfalken.com`. Callback
210 `https://projects.timfalken.com/meteors/callback.php`. Het geheim zet Tim
211 als protected projectgeheim `auth_client_secret` (niet opnieuw genereren);
212 de deploy schrijft dan `data/config.php`. Zonder geheim blijft solo
213 werken, met een duidelijke online-melding.
214- Testers `auth.php?test=1` / `?test=2` alleen als `localDev()` waar is:
215 loopback-host **én** loopback-remote-adres (zelfde regel als verhalenboek).
216- Sessies staan in `data/sessions`, cookie-pad is de map van het script
217 (`/meteors/` live). CSRF-token op elke POST (`X-CSRF-Token`).
218
219### Lobby en wedstrijd
220
221- Onbeperkt in de zin van de regel; praktisch maximum **32** (`METEORS_MAX_PLAYERS`).
222- De host start alleen als iedereen gereed is en er minstens twee spelers zijn.
223- Eigen veld is het hoofdspel; miniaturen van anderen staan in een strook
224 boven het veld (onder de HUD).
225- Afgeschoten blokjes gaan als `outgoingShots` mee in de volgende poll. De
226 **server** kiest het doel en gooit de miss-kans (niet de client, zodat die
227 niet kan valsspelen). Doel is een willekeurige andere speler die nog niet
228 is uitgeschakeld.
229- `missChance` is een **parameter**, standaard **0,30**, op de lobby én op
230 `GameCore`. `Planet.missChance` (Power, 60 %–5 %) blijft voor stage 3 en
231 wordt hier niet gebruikt.
232- Een raak schot komt na `flight_duration = 1,2 s` bij de ontvanger aan als
233 vallend donkergrijs vuil (`ingestGarbage`), dat na de gewone 3 s settle
234 een willekeurige kleur krijgt.
235- De vlucht-tween is een kwadratische Bézier, met semi-willekeurige rotatie
236 (tot ±720°) en krimpen (“de verte in”). Een miss vliegt het scherm af en
237 vervaagt; een raak schot landt in de miniatuur van het doel.
238- Uitgeschakelde spelers zijn toeschouwer (geen doelwit, geen shots). De
239 laatste die overblijft is 1e; de eerder uitgeschakelden 2e, 3e, … Het
240 podium blijft **5 seconden** (`METEORS_PODIUM_SECONDS`) en daarna gaat de
241 lobby terug naar `waiting` (ready-vlaggen gereset).
242- `data/` (sqlite, sessies) wordt nooit gespiegeld of gewist. Alleen
243 `data/.htaccess` (Require all denied) wordt na de mirror gezet.
244 Als het projectgeheim `auth_client_secret` niet leeg is, schrijft de
245 deploy `data/config.php` vanuit dat geheim (waarde nooit in de logs).
246 Is het leeg of afwezig, dan blijft een bestaand bestand staan. De groep
247 `projects-timfalken-com` en verhalenboek hebben dit geheim niet (alleen
248 FTP); Tim zet het op het meteors-project. Optioneel: `auth_client_id`
249 (standaard `projects.timfalken.com`). `favicon.ico` blijft ongemoeid.
250 `router.php` is alleen voor lokale `php -S` en gaat niet mee naar live.
251
252## Fase 3 — planeten (velden)
253
254- Een veld is een planeet, met een naam voor de planeet en voor het volk.
255 De catalogus staat in `server/lib/planets.json` (bron voor JS én PHP) en
256 telt **12** werelden, van makkelijk (Aurel: gameplay-Power 0, 60 % miss,
257 getoonde Power 0 %) tot moeilijk (Cinder: gameplay-Power 1, 5 % miss,
258 getoonde Power 92 %). Terra (44 % getoonde Power) blijft de standaard.
259- Zwaartekracht (`jumpsToClear` 1–4): één sprong haalt `1/jumpsToClear` van
260 de veldhoogte. Luchtweerstand (`fallTime` 1–5 s tot de bodem). Massa
261 (`riseTime` 0,5–3 s tot de apex). Lage massa en lage luchtweerstand en
262 hoge zwaartekracht zijn moeilijker. Bounce-duur en apex-ease schalen al
263 met `fallTime` (gebouwd in stage 1).
264- De interne (gameplay-)Power is het gemiddelde van die drie assen,
265 genormaliseerd 0–1. Miss-kans = `0,60 − 0,55 × Power` (60 % bij 0,
266 5 % bij 1). Dat formule blijft de gameplay: schoten en de server
267 gebruiken hem onveranderd. De **getoonde** Power in kiezer, HUD en
268 lobby is `1 − miss / 0,60` als percentage (0 % miss → 100 % Power,
269 60 % miss → 0 % Power). Dat is alleen weergave (t1105). In
270 multiplayer gebruikt de **server** de gameplay-Power van **jouw**
271 planeet voor de blokjes die jij afschiet (niet de lobby-waarde, niet
272 de planeet van het doel). De client kan dat niet vervalsen.
273- De vier getallen op de kiezers en in de HUD: `g` als
274 zwaartekrachtsconstante (m/s²), `d` als luchtdichtheid, `F` in newton,
275 getoonde Power als percentage. Alleen de getallen, zonder uitleg.
276 Verticale match van 3 = 120 % sprong, +5 % per extra blokje (al
277 gebouwd, nergens uitgelegd).
278- Elk veld heeft een eigen set van 5 kleuren, elk met een uniek vormpje
279 en een uniek placeholder-PNG (`build/images/block-{planeet}-{kleur}.png`).
280 Tim kan die bestanden zelf vervangen; de namen blijven gelijk. Te
281 (her)genereren met `python3 scripts/gen_planet_blocks.py`.
282- Planeetkeuze komt vóór solo-spel (`Spelen` opent de kiezer) en in de
283 lobby (iedereen kiest zelf; zichtbaar voor de anderen). De keuze wordt
284 onthouden in `localStorage` (`meteors-planet`). Na de start van een
285 wedstrijd kun je niet meer wisselen.
286
287## t1104 — 1:1-slepen en spontane raketten
288
289- Oorzaak van de sleepbug: `moveDrag` werkte met een opgetelde
290 pointer-delta en een drempel van `SWAP_DISTANCE` (0,25 tegel). Een
291 klein stukje sleep deed daardoor al een hele tegel, en één grote
292 `pointermove` (typisch op touch) kon de rest van de kolom aflopen —
293 precies “meestal gelijk helemaal omlaag of omhoog”. De doelrij was
294 niet de rij onder de vinger, dus als de vinger stopte kon het blokje
295 al aan de top of de bodem zitten. Daarnaast liep de pointer-mapping
296 via `canvas.width` / `app.tile`, wat deltas zou vermenigvuldigen met
297 de devicePixelRatio als de backing-store en de CSS-maat ooit
298 uit elkaar lopen.
299- Nu: de doelrij is `floor(pointerY)`, geklemd op de still-stapel van
300 de kolom. `swapToward` wisselt stap voor stap met elke buur, en stopt
301 precies daar. Als de pointer stilstaat, beweegt er niets meer.
302 Optrekken-boven-de-top om te lanceren blijft. Coordinaten komen uit
303 `getBoundingClientRect` en de veldgrootte (10×13), zonder
304 canvas-backing of `app.tile`.
305- Spontane rijen (na vallen, settle/recolor, cargo-attach op een
306 vliegende cluster, cluster-merge) worden altijd raketten, net als
307 wanneer de speler ze maakt. In een al vliegende cluster geeft dat
308 een extra sprong vanaf de huidige positie (`checkChainRelaunch`,
309 dezelfde hoogte als bij een player-push). Mid-air hangend cargo na
310 recolor valt nog steeds vanuit stilstand (t1102), geen launch.
311
312## t1105 — getoonde Power omgekeerd
313
314- Alleen de weergave. Gameplay `power()` en `missChance()` zijn
315 onveranderd (`miss = 0,60 − 0,55 × power`). Getoonde Power =
316 `1 − missChance / 0,60`, afgerond als percentage, in JS
317 (`Planet.displayValues` / `formatStats`) en PHP (`Planets::displayValues`),
318 dus op de planeetkiezer, in de HUD en in de lobby. 0 % miss is 100 %
319 Power; Aurel 0 %, Terra 44 %, Cinder 92 %.
320