BlueGit

projects-timfalken-com meteors

docs: record t1102/t1103 assumptions for recolor, merge, and grab

Document leftover-vy cleanup after grey recolor, mass-weighted
cluster merge by block count, and instant grab with no long press
(SNAP_Y, HORIZONTAL_SLOP, SWAP_DISTANCE).

timfa Grok Bot · pushed by timfa

Authored 2026-11-13 · 4 days ago

Hash
51b58cb626fe460744b2a5c5d5302b01ed56b5bd
Parent
f476da04
1 file changed +65 −0
docs/ASSUMPTIONS.md +65 −0
@@ -133,3 +133,68 @@ nooit `--delete`, dus ze blijven staan en zijn onschadelijk.
133 133 `favicon.ico` op de server wordt niet overschreven en niet verwijderd
134 134 (mogelijk van Tim of de host). De deploy sluit dat bestand uit van de
135 135 upload, 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
139 Na het herkleuren van een gelande grijze groep schoten blokken erboven
140 soms heel hard van de bovenkant af. Oorzaak: een restant van de
141 lanceringssnelheid (`vy` omhoog) of van een handmatige sprong, dat
142 na de release in `integrateFalling` alsnog werd gebruikt. Daarnaast
143 telde `releaseUnsupported` in dezelfde tick nog de hangende leden als
144 steun, zodat blokken die erop stonden `still` bleven en in
145 `resolveMatches` een match in de lucht konden vormen.
146
147 Aanname / 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
163 Twee (of meer) vliegende clusters die in dezelfde kolom in Y
164 overlappen, worden één cluster.
165
166 Aanname: de nieuwe snelheid is het **massagewogen gemiddelde op
167 blok-aantal** (niet het eenvoudige gemiddelde van de twee
168 clustersnelheden):
169
170 vy = (n1·vy1 + n2·vy2) / (n1 + n2)
171
172 Hetzelfde gewogen gemiddelde geldt voor `decel` en `jumpHeight`.
173 De fase is `up` als de samengevoegde `vy > 0`, anders `down`.
174 Overlappende leden in één kolom worden van onder naar boven
175 aangepakt, zodat de hogere strak op de lagere rust (geen twee
176 blokken in dezelfde cel). Keuze vastgelegd: gewogen op blok-aantal.
177
178 ### 9. Direct vastpakken, geen long-press (t1102 / t1103)
179
180 Er is **geen** long-press en **geen** wachttijd. Een blok wordt op
181 `pointerdown` (tap of klik) meteen vastgepakt en blijft in de sleep
182 zolang de vinger of muisknop omlaag is; loslaten beëindigt de sleep.
183 De click-tween start in hetzelfde moment als `pointerdown`.
184
185 Aanname:
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).
@@ -133,3 +133,68 @@ nooit `--delete`, dus ze blijven staan en zijn onschadelijk.
133`favicon.ico` op de server wordt niet overschreven en niet verwijderd
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
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.
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).