Meteors
Puzzelspel voor het web, zwaar geïnspireerd door Meteos (Nintendo DS). Gebouwd op frameworkv3 (WebGL). Speelbaar met muis op desktop en met touch op mobiel, ook in portretstand.
Live (na de eerste deploy): https://projects.timfalken.com/meteors/
Spelen
1. Open build/index.html (lokaal of live). Ben je niet ingelogd, dan vraagt het spel meteen of je wilt inloggen (via auth.timfalken.com), met daaronder Speel als gast. Een ingelogde speler ziet die vraag niet. Kies je voor gast, dan blijft die keuze bewaard in deze tab (niet over een nieuwe sessie). Het hoofdmenu (t1201) heeft Spelen (grote knop: rondes tegen lokale bots, voorheen “Offline Strijd”), Overleven (eindeloos alleen, voorheen “Spelen”), Online spelen en daaronder Ranglijst (t1247, t1263): de top 10 op het puntentotaal van je profiel (het getal waar het puntenscherm naartoe telt). Spelers met 0 punten staan er niet op. Een tweede tab toont je vrienden van auth.timfalken.com, met jou erbij gerangschikt op punten (ook jij verdwijnt bij 0 punten). Namen en avatars komen van de publieke auth-API GET /api/profiles?ids=… (gecached zo’n 10 minuten, t1253), en worden teruggeschreven op bestaande profielen. Is auth onbereikbaar, dan blijven de eerdere terugvallen (vriendenlijst, opgeslagen naam, anders het cijfer uit het account-id). Gasten zien de wereldwijde top 10; de vriendentab vraagt hen in te loggen. Sta je zelf in de lijst, dan is je rij gemarkeerd, met avatar en naam. Hieronder de regels van het veld zelf. 2. Elke seconde valt er een blokje van één van vijf kleuren in een willekeurige kolom. 3. In een stilliggende kolom sleep je blokjes verticaal; ze wisselen om met de blokjes waar je langs gaat. 4. Drie of meer blokjes van dezelfde kleur op een rij (horizontaal of verticaal) worden donkergrijs, krijgen een vlam en springen omhoog. Alles wat erop stond, vliegt mee. 5. Blokjes die boven de bovenrand van het veld (10×13) verdwijnen, leveren punten op. 6. Trek een blokje naar de top van zijn kolom en dan nóg verder omhoog: het springt tot net onder de bovenrand. Is het blokje al het bovenste van de kolom, dan is een trek voorbij zijn eigen positie genoeg (muis en touch). Komt het tegen een vliegend cluster aan, dan duwt het die kolom één tegel omhoog. Vormt dat een nieuwe drie-op-een-rij, dan springt het hele cluster opnieuw. 7. Een vallend (gespawnd) blokje landt op een vliegende cluster in dezelfde kolom en vliegt als vracht mee. 8. Een gelande grijze cluster blijft als starre groep liggen — een deel kan boven een gat blijven hangen — tot de blokjes na 3 seconden een kleur terugkrijgen. Daarna vallen ongesteunde blokjes afzonderlijk naar beneden. 9. Een kolom die van onder tot boven vol ligt, gaat op slot (donkergrijs, geen interactie, geen nieuwe val). Zitten alle tien kolommen vast, dan is het spel voorbij en ga je terug naar het menu.
Het standaardveld is de planeet Terra (volk: Terrans), met middelmatige zwaartekracht, luchtweerstand en massa. Die drie waarden, plus de Power, staan in de HUD; later (stage 3) kies je zelf een planeet.
Lokaal bouwen en draaien
# Eenmalig / bij een framework-update: bundel frameworkv3 en kopieer hem.
# cd /pad/naar/frameworkv3 && ./glbuild.sh
# cp js/framework.js /pad/naar/meteors/build/framework.js
# Tests
node --test test/*.test.js
php server/tests/run.php
# Game-bundel (src/ → build/game.js)
./src/build.sh
# of: npm run build
# Placeholder-plaatjes opnieuw maken (optioneel; Tim kan ze zelf vervangen)
python3 scripts/make-placeholders.py
# Alleen het solo-spel (zonder online-API)
python3 -m http.server 8080 --directory build
# spel: http://localhost:8080/
# Met lobby-API (lokale testers: auth.php?test=1 en ?test=2)
php -S 127.0.0.1:8080 -t build build/router.php
# spel: http://127.0.0.1:8080/
./src/build.sh zet op game.js, style.css en framework.js een content-hash (?v=12 hex tekens) in build/index.html. De vertalingen zitten in game.js (I18N_CATALOG, uit server/lib/i18n.json), dus verandert de catalogus, dan verandert ook die hash. index.html zelf wordt met Cache-Control: no-cache aangeboden (via .htaccess en de lokale router), zodat een browser altijd de nieuwe hashes ziet.
Architectuur
De spelkern is deterministisch en staat los van tekenen en invoer, zodat stage 2 (multiplayer) dezelfde simulatie kan hergebruiken.
| Pad | Rol |
|---|---|
src/planet.js | Planeet: zwaartekracht, luchtweerstand, massa, kleuren/vormen, spronghoogte, Power, apex-ease, bounce |
src/i18n.js | Vertalingen en vlaggenkiezer (t1141) |
src/blocks.js | Append-only blokjesregister, drempels, ontgrendeling |
src/designer.js | Planeetontwerper (lijst, bewerken, blokjes-modal) |
server/lib/blocks.json | Blokjesregister (JS en PHP delen dit bestand) |
server/lib/Blocks.php | Server-kant van het register en de drempels |
src/rng.js | Seedable RNG (tests en later replays) |
src/easing.js | Qt-eases (easeOutBack / easeOutElastic) en Click-Tween-defaults voor de selectie-animatie |
src/gameCore.js | Simulatie: vallen, wisselen, match-3, raketsprong, linken, push-up + her-sprong, landen als starre groep + 3 s wachten, kolom-slot, game over, punten; stage 2: outgoingShots, ingestGarbage, missChance, fieldSnapshot |
src/main.js | Menu, HUD, frameworkv3-scene, muis/touch, schaal naar het scherm, landing-bounce, selectie-tween, online-lobby |
src/offline.js | Offline Strijd: progressie, bot-AI, lokale 'multiplayer'-schoten |
src/reward.js | Puntenscherm na een spel/ronde (t1173): blokjes in 4 s (t1194) naar het profieltotaal; online rematch telt opnieuw (t1278) |
src/online.js | API-client, polling, opponent-miniaturen, vlucht-tweens van afgeschoten blokjes |
server/ | PHP API: OAuth, lobby, shots, SQLite in data/ (niet gedeployed) |
server/lib/planets.json | Catalogus van 12 planeten (JS en PHP delen dit bestand) |
docs/ASSUMPTIONS.md | Ingevulde aannames waar de specificatie ruimte liet |
src/build.sh | Concateneert de bronnen naar build/game.js, kopieert de PHP-API naar build/ en zet content-hash-querystrings (?v=) op game.js, style.css en framework.js in index.html (t1256) |
build/ | Speelbare output: index.html, style.css, framework.js, game.js, images/, PHP-API |
test/ | Unit tests (node --test) voor de kern en de deploy-guard; server/tests/run.php voor de API |
ci/ | FTP-deploy, zonder --delete. Expandeert $timftproot zelf. Raakt favicon.ico en data/ (config, database) niet aan. |
Sprongfysica is parametrisch. Zwaartekracht (jumpsToClear) loopt van 2,0 tot 4,0 (t1199: minimum was 1) en wordt getoond als percentage, lineair: pct = (v − 1) × 100 en g = 9,81 × (v − 1), dus 2,0 = 100 % (9,81 g), 3,0 = 200 % (19,62 g), 4,0 = 300 % (29,43 g) — in de planeetkaarten, de HUD en de ontwerper. Een horizontale match van 3 springt 1,5 × 13 / jumpsToClear tegels hoog (t1119: de minimumsprong is 50 % hoger); een verticale match van 3 krijgt 120 % daarvan, en elk extra blokje +5 % (wordt nergens in het spel uitgelegd). De massa bepaalt hoe lang de sprong omhoog duurt (onafhankelijk van de hoogte). Op de apex versnelt de cluster geleidelijk tot de valsnelheid (apexEaseTime = 0,15 × fallTime); daarna zweeft een cluster omlaag op de gehalveerde eindsnelheid (clusterFallSpeed = 0,5 × 13 / fallTime, t1122/t1124). Losse blokjes (spawn, ongesteund, cargo) vallen op de volle fallSpeed = 13 / fallTime. De luchtweerstand (fallTime) bepaalt die valsnelheden én hoe snel de visuele landing-bounce is (bounceDuration = 0,12 × fallTime). Een vastgehouden blokje krijgt dezelfde schaal-tween als Tim's KWin Click Tween (150 ms easeOutBack naar 80 %, 720 ms easeOutElastic terug). Wissels (speler en bot) animeren visueel in 100 ms easeOutCubic (t1121). Landt een cluster meteen in een match, dan is die sprong 25 % sterker, stapeling additief (t1120). Daarbovenop telt een combo (t1197/t1198): elke eerdere match in de lopende combo geeft +1 % sprong (1e match +0 %, 2e +1 %, 3e +2 %, …), tot maximaal +30 %; maak je 5 s geen match, dan begint de combo opnieuw. Combo en landingsketting tellen op voor de sprong; boven het veld staat als gele “+x%” met oranje rand alleen de combobonus (0,01 × min(combo, 30), t1200), zichtbaar zolang die groter dan 0 is. Zie docs/ASSUMPTIONS.md.
Menu tijdens het spel (t1193). In Spelen en Overleven staat rechtsboven een kleine menuknop (☰). Die pauzeert het spel en biedt Verder en Terug naar hoofdmenu. Terug naar het menu beëindigt de wedstrijd: ingelogd zie je eerst het puntenscherm (titel “Spel beëindigd”) zodat de punten tot dan toe via play_finish bij je profiel komen; uitgelogd ga je direct naar het menu. In Spelen (rondes) volgt dan geen volgende ronde. Het pauzemenu noemt de modus (t1201). De server-limieten op punten blijven gelden.
Laatste planeet (t1196). De laatst gekozen planeet (standaard of eigen) staat bij elk planeetkeuzescherm (Spelen, Overleven, Online) alvast geselecteerd. Ingelogd staat die in je profiel op de server (set_last_planet), uitgelogd in localStorage. Is een eigen planeet verwijderd, dan valt de keuze terug op Terra.
Planeten (stage 3)
Voor je gaat spelen — solo en in de lobby — kies je een veld. Elk veld is een planeet met een volk, vijf eigen kleuren/vormen, en drie natuurwetten:
- zwaartekracht — hoe hoog de eerste sprong is (
g, als percentage: 100 % = 9,81 g, minimaal 100 %) - luchtweerstand — hoe snel blokjes weer vallen (
d) - massa — hoe snel de sprong omhoog gaat (
F, newton)
Die drie waarden bepalen een interne moeilijkheids-Power (0–1). De miss-kans van een afgeschoten blokje is 0,60 − 0,55 × Power (60 % op het makkelijkste veld, 5 % op het moeilijkste). De getoonde Power in de kiezer, de HUD en de lobby is het omgekeerde daarvan: 1 − miss / 0,60 als percentage. 0 % miss is 100 % Power; 60 % miss is 0 % Power. Aurel toont 0 %, Terra 44 %, Cinder 92 % (de bodem is 5 % miss, dus niet 100 %). In een online wedstrijd telt jouw planeet voor de blokjes die jij verstuurt. De twaalf werelden en hun getallen staan in server/lib/planets.json. De blokplaatjes zijn unieke placeholders (build/images/block-{planeet}-{kleur}.png); Tim kan ze zelf vervangen.
Planeetontwerper
Ingelogde spelers zien op het hoofdmenu hun puntentotaal en de knop Planeetontwerper. Punten verzamel je door ingelogd te spelen (Overleven aan het einde, elke ronde van Spelen, en Online bij uitschakeling). Ze worden niet uitgegeven: bij vaste drempels (Terra gratis, daarna 500 punten en elke volgende 14,5 % hoger) ontgrendel je extra blokjes.
In de ontwerper maak, bewerk of verwijder je eigen planeten (naam, bevolking, de drie sliders voor zwaartekracht / lucht / massa, en een live Power-preview met dezelfde formule als in het spel). Vijf blokjesvakjes openen een raster van het hele register: blokjes die al in een ander vak zitten zijn grijs, vergrendelde blokjes zijn grijs mét een slotje.
Eigen planeten kun je in elke modus kiezen (Spelen, Overleven, Online). Online valideert de server de configuratie en deelt een snapshot met de andere spelers.
Lokaal inloggen: auth.php?test=1. Op de live site blijft de ontwerper verborgen tot OAuth (callback.php + CI-geheim auth_client_secret) is ingesteld.
Puntenscherm (ingelogd)
Na een spel in Overleven, na elke ronde van Spelen en na een Online-wedstrijd zie je als ingelogde speler eerst midden in beeld “You won!” of “You lost...” (in de gekozen taal). Na een seconde schuift die tekst naar boven en vliegen blokjes van jouw planeet (ook eigen planeten) in boogjes naar het getal onderaan: je profieltotaal. Elk blokje is één nieuw verdiend punt, dus het getal loopt van het totaal vóór de ronde naar het nieuwe totaal dat de server bevestigt. Het tempo begint op 3 blokjes per seconde en versnelt per beloning precies zo veel dat het laatste blokje altijd na ~4 s vertrekt, hoeveel punten het ook zijn (t1194; bij weinig punten een vast tempo, zie docs/ASSUMPTIONS.md). Daarna nog de vlucht van het laatste blokje. Daarna ga je, net als voorheen, naar het menu, de volgende ronde, het resultaatscherm of de lobby. Uitgelogd verandert er niets. Zie docs/ASSUMPTIONS.md (t1173).
Taalkeuze
Het spel is standaard Engels. Rechtsonder op het hoofdmenu staat de vlag van de huidige taal; een klik opent tien vlaggen (VK, Nederland, Duitsland, Frankrijk, Japan, China, Korea, Polen, Rusland, Spanje). Gasten houden hun keuze in deze browser. Ben je ingelogd, dan is de taal op auth.timfalken.com (locale-claim op /oauth/token en GET /api/me, BCP 47; zh-Hans wordt hier zh) de standaard, totdat je in het spel zelf een taal kiest. Die expliciete keuze wordt opgeslagen en wint altijd (t1250).
Deploy
BlueGit CI (blue-ci-cd.yml) draait tests en een build op feature-branches en op master. Op master volgt daarna ftp_upload: build/ gaat via FTP naar projectftp (secret: $timftproot/meteors; de job expandeert $timftproot zelf en normaliseert dubbele slashes). Geen --delete. De eerste deploy weigert te schrijven als de doelmap al vreemde bestanden bevat.
Secrets: timftphost / timftpuser / timftppassword / timftproot (groep), projectftp (dit project), en auth_client_secret (dit project, zie hieronder). De groep en de andere projecten (verhalenboek, microchess) hebben geen auth-geheim; alleen FTP-gegevens.
Spelen (rondes tegen bots, voorheen Offline Strijd)
Op het menu kies je de grote knop Spelen, daarna een planeet (het planeetscherm noemt de modus). Je speelt tegen lokale bots alsof het multiplayer is (schoten, miss-kans, miniatuurvelden), helemaal in de browser. Eerst 1 tegenstander, daarna 2, en verder N tegenstanders voor N−1 rondes, met stijgende skill (5 % + 1 % per ronde). Als je verliest zie je de bereikte ronde en hoeveel tegenstanders je in totaal (over alle rondes) hebt verslagen (t1198), onder de titel “Uitslag” (t1201). De HUD toont alleen “Ronde N”.
Overleven (eindeloos, voorheen Spelen)
Overleven is het eindeloze spel alleen: blokjes blijven vallen en steeds sneller komen tot al je kolommen vastzitten. Intern heet de modus nog solo (ook in play_finish), Spelen/rondes heet intern offline (t1201). Zie docs/ASSUMPTIONS.md (t1119).
Online spelen (stage 2)
Solo blijft werken, ook als online nog niet is ingesteld. Op het menu kies je Online spelen. Na inloggen via auth.timfalken.com (gestart vanuit Online kom je terug in het online-paneel; gestart vanaf het hoofdmenu kom je terug op het hoofdmenu, t1193) maak je een lobby (of val je in met een code). Onbeperkt aantal spelers, praktisch maximum 32. Iedereen drukt op Gereed; de host start als er minstens twee spelers zijn en iedereen gereed is.
Je eigen veld is het hoofdspel; miniaturen van de tegenstanders staan erboven. Op een smal/staand scherm (t1203) worden die miniaturen (en hun labels) kleiner gemaakt tot ze allemaal boven je veld passen (canvas van 80 px breed tot minimaal 32 px, labels 11 → 9 px; rijen gebalanceerd). Passen ze zelfs op 32 px niet, dan schuiven de al verslagen tegenstanders naar achteren (volgorde blijft stabiel), zodat juist die achter het veld vallen. Dit geldt voor Spelen (bots) en Online spelen; brede schermen houden de layout naast het veld. Blokjes die van je veld afschieten kiezen een willekeurige andere (nog niet uitgeschakelde) speler en vliegen daar in een korte tween naartoe (draaien en krimpen). De kans dat ze missen komt uit de Power van jouw planeet (60 % op het makkelijkste veld, 5 % op het moeilijkste); dat gooit de server. Een raak schot komt bij de ander aan als een vallend donkergrijs blokje dat na 3 seconden op een stapel weer een kleur krijgt. Wie al zijn kolommen vol heeft, is toeschouwer en geen doelwit meer. De laatste die overblijft wint; 1e/2e/3e staan 5 seconden op het podium en daarna ga je terug naar de lobby.
Vallende blokken en vertrekkende raketten
- Vliegt een raketstapel omhoog, is het hoogste blok voorbij 75% van de
veldhoogte en gaat hij zeker het scherm uit, dan valt er geen nieuw blok en geen ontvangen (grijs) blok in de kolommen van die stapel: ze kiezen een andere kolom.
- Start van elke match/ronde: de eerste 3 s valt er elke 0,1 s een blok
(verdeeld over de legere kolommen), van 3 tot 6 s loopt de tussentijd lineair terug naar 1 s.
- Daarna loopt het tempo op: na elk nieuw blok wordt de spawn-interval 0,3%
korter (minimum 0,1 s, na ca. 767 blokken / 5 minuten). Elk spel en elke ronde begint weer bij 0 s, ook voor bots en online.
Ontvangen blokken
Blokken die je van een tegenstander (of bot) krijgt gaan nooit verloren. Ze komen in een wachtrij en vallen pas als er plek is: het vorige blok in die kolom moet een hele cel onder de bovenste rij zitten. Is de gewenste kolom vol, geblokkeerd of bezet door een vertrekkende raket, dan kiest het blok een andere open kolom; is er geen enkele open, dan wacht het.
Raketvlam
De vlam onder een raketblok wisselt 25 keer per seconde naar een willekeurig ander frame, spiegelt in de helft van de gevallen en varieert licht in grootte, breedte, hoogte (elk ±6–7%) en hoek (±2,5°). Alles draait om het bovenste midden van de vlam, waar hij aan het blok vastzit. Met "verminderde beweging" (prefers-reduced-motion) blijft het bij 12,5 fps en alleen wisselende frames.
Vliegende blokken en mini-velden (vloeiend)
- Een blok dat je wegschiet vliegt meteen lokaal weg (geen wachten op de
server). Zodra de server antwoordt (raak/mis, doelkolom) buigt dezelfde vlucht vloeiend af naar het echte doel; geen sprong, geen tweede blok.
- Een tegenstander ziet de vlucht vanaf jouw mini-veld vertrekken zodra het
serverbericht binnenkomt, als volledige boog (iets ingekort bij vertraging).
- Op de mini-velden van tegenstanders vallen blokken tussen de
serverupdates door vloeiend verder (voorspelling met hun valsnelheid). Landen of lijnen wissen wordt nooit voorspeld: dat komt altijd van de server.
Wat Tim moet instellen
Online werkt pas als OAuth is ingesteld. Zolang dat niet zo is, blijft solo beschikbaar en toont Online spelen een duidelijke boodschap. Je hoeft data/config.php niet via FTP te zetten: de deploy schrijft dat bestand zelf vanuit een CI-geheim.
1. Ga naar https://auth.timfalken.com/admin, bij de bestaande client projects.timfalken.com (dezelfde als de andere sites op dit domein). 2. Voeg het callback-pad /meteors/callback.php toe. Volledige URL: https://projects.timfalken.com/meteors/callback.php. 3. Kopieer het bestaande client-geheim. Genereer het niet opnieuw — dat breekt de andere sites die dit geheim al gebruiken. 4. Zet in BlueGit, bij dit project (projects-timfalken-com/meteors), een protected (alleen master) geheim met de naam auth_client_secret en als waarde dat bestaande geheim. Er is geen groepsgeheim voor dit: de groep en verhalenboek hebben alleen FTP-credentials. Optioneel is auth_client_id (standaard projects.timfalken.com); dat hoeft Tim niet te zetten. 5. De volgende deploy naar master schrijft data/config.php op de server (alleen als het geheim niet leeg is; de waarde komt nooit in de logs). Zonder geheim blijft een bestaand data/config.php ongemoeid. De SQLite-database en sessies worden nooit gewist. data/.htaccess weigert alle HTTP-toegang tot die map. favicon.ico wordt niet overschreven.
Lokaal (alleen op loopback, host én remote-adres) kun je zonder geheim inloggen als auth.php?test=1 of auth.php?test=2.
Source
| 1 | # Meteors |
| 2 | |
| 3 | Puzzelspel voor het web, zwaar geïnspireerd door *Meteos* (Nintendo DS). Gebouwd op |
| 4 | [frameworkv3](https://git.timfalken.com/timfa/frameworkv3) (WebGL). Speelbaar met |
| 5 | muis op desktop en met touch op mobiel, ook in portretstand. |
| 6 | |
| 7 | Live (na de eerste deploy): https://projects.timfalken.com/meteors/ |
| 8 | |
| 9 | ## Spelen |
| 10 | |
| 11 | 1. Open `build/index.html` (lokaal of live). Ben je niet ingelogd, dan |
| 12 | vraagt het spel meteen of je wilt inloggen (via |
| 13 | [auth.timfalken.com](https://auth.timfalken.com)), met daaronder |
| 14 | **Speel als gast**. Een ingelogde speler ziet die vraag niet. Kies je |
| 15 | voor gast, dan blijft die keuze bewaard in deze tab (niet over een |
| 16 | nieuwe sessie). Het hoofdmenu (t1201) heeft **Spelen** (grote knop: |
| 17 | rondes tegen lokale bots, voorheen “Offline Strijd”), **Overleven** |
| 18 | (eindeloos alleen, voorheen “Spelen”), **Online spelen** en daaronder |
| 19 | **Ranglijst** (t1247, t1263): de top 10 op het puntentotaal van je profiel |
| 20 | (het getal waar het puntenscherm naartoe telt). Spelers met 0 punten |
| 21 | staan er niet op. Een tweede tab toont je vrienden van |
| 22 | [auth.timfalken.com](https://auth.timfalken.com), met jou erbij |
| 23 | gerangschikt op punten (ook jij verdwijnt bij 0 punten). Namen en avatars |
| 24 | komen van de publieke auth-API `GET /api/profiles?ids=…` (gecached |
| 25 | zo’n 10 minuten, t1253), en worden teruggeschreven op bestaande |
| 26 | profielen. Is auth onbereikbaar, dan blijven de eerdere terugvallen |
| 27 | (vriendenlijst, opgeslagen naam, anders het cijfer uit het |
| 28 | account-id). Gasten zien |
| 29 | de wereldwijde top 10; de vriendentab vraagt hen in te loggen. Sta je |
| 30 | zelf in de lijst, dan is je rij gemarkeerd, met avatar en naam. |
| 31 | Hieronder de regels van het veld zelf. |
| 32 | 2. Elke seconde valt er een blokje van één van vijf kleuren in een willekeurige kolom. |
| 33 | 3. In een stilliggende kolom sleep je blokjes verticaal; ze wisselen om met de blokjes waar je langs gaat. |
| 34 | 4. Drie of meer blokjes van dezelfde kleur op een rij (horizontaal of verticaal) worden donkergrijs, krijgen een vlam en springen omhoog. Alles wat erop stond, vliegt mee. |
| 35 | 5. Blokjes die boven de bovenrand van het veld (10×13) verdwijnen, leveren punten op. |
| 36 | 6. Trek een blokje naar de top van zijn kolom en dan nóg verder omhoog: het springt tot net onder de bovenrand. Is het blokje al het bovenste van de kolom, dan is een trek voorbij zijn eigen positie genoeg (muis en touch). Komt het tegen een vliegend cluster aan, dan duwt het die kolom één tegel omhoog. Vormt dat een nieuwe drie-op-een-rij, dan springt het hele cluster opnieuw. |
| 37 | 7. Een vallend (gespawnd) blokje landt op een vliegende cluster in dezelfde kolom en vliegt als vracht mee. |
| 38 | 8. Een gelande grijze cluster blijft als starre groep liggen — een deel kan boven een gat blijven hangen — tot de blokjes na 3 seconden een kleur terugkrijgen. Daarna vallen ongesteunde blokjes afzonderlijk naar beneden. |
| 39 | 9. Een kolom die van onder tot boven vol ligt, gaat op slot (donkergrijs, geen interactie, geen nieuwe val). Zitten alle tien kolommen vast, dan is het spel voorbij en ga je terug naar het menu. |
| 40 | |
| 41 | Het standaardveld is de planeet **Terra** (volk: Terrans), met middelmatige zwaartekracht, luchtweerstand en massa. Die drie waarden, plus de Power, staan in de HUD; later (stage 3) kies je zelf een planeet. |
| 42 | |
| 43 | ## Lokaal bouwen en draaien |
| 44 | |
| 45 | ```bash |
| 46 | # Eenmalig / bij een framework-update: bundel frameworkv3 en kopieer hem. |
| 47 | # cd /pad/naar/frameworkv3 && ./glbuild.sh |
| 48 | # cp js/framework.js /pad/naar/meteors/build/framework.js |
| 49 | |
| 50 | # Tests |
| 51 | node --test test/*.test.js |
| 52 | php server/tests/run.php |
| 53 | |
| 54 | # Game-bundel (src/ → build/game.js) |
| 55 | ./src/build.sh |
| 56 | # of: npm run build |
| 57 | |
| 58 | # Placeholder-plaatjes opnieuw maken (optioneel; Tim kan ze zelf vervangen) |
| 59 | python3 scripts/make-placeholders.py |
| 60 | |
| 61 | # Alleen het solo-spel (zonder online-API) |
| 62 | python3 -m http.server 8080 --directory build |
| 63 | # spel: http://localhost:8080/ |
| 64 | |
| 65 | # Met lobby-API (lokale testers: auth.php?test=1 en ?test=2) |
| 66 | php -S 127.0.0.1:8080 -t build build/router.php |
| 67 | # spel: http://127.0.0.1:8080/ |
| 68 | ``` |
| 69 | |
| 70 | `./src/build.sh` zet op `game.js`, `style.css` en `framework.js` een |
| 71 | content-hash (`?v=12 hex tekens`) in `build/index.html`. De vertalingen |
| 72 | zitten in `game.js` (`I18N_CATALOG`, uit `server/lib/i18n.json`), dus |
| 73 | verandert de catalogus, dan verandert ook die hash. `index.html` zelf |
| 74 | wordt met `Cache-Control: no-cache` aangeboden (via `.htaccess` en de |
| 75 | lokale router), zodat een browser altijd de nieuwe hashes ziet. |
| 76 | |
| 77 | ## Architectuur |
| 78 | |
| 79 | De spelkern is deterministisch en staat los van tekenen en invoer, zodat stage 2 |
| 80 | (multiplayer) dezelfde simulatie kan hergebruiken. |
| 81 | |
| 82 | | Pad | Rol | |
| 83 | | --- | --- | |
| 84 | | `src/planet.js` | Planeet: zwaartekracht, luchtweerstand, massa, kleuren/vormen, spronghoogte, Power, apex-ease, bounce | |
| 85 | | `src/i18n.js` | Vertalingen en vlaggenkiezer (t1141) | |
| 86 | | `src/blocks.js` | Append-only blokjesregister, drempels, ontgrendeling | |
| 87 | | `src/designer.js` | Planeetontwerper (lijst, bewerken, blokjes-modal) | |
| 88 | | `server/lib/blocks.json` | Blokjesregister (JS en PHP delen dit bestand) | |
| 89 | | `server/lib/Blocks.php` | Server-kant van het register en de drempels | |
| 90 | | `src/rng.js` | Seedable RNG (tests en later replays) | |
| 91 | | `src/easing.js` | Qt-eases (easeOutBack / easeOutElastic) en Click-Tween-defaults voor de selectie-animatie | |
| 92 | | `src/gameCore.js` | Simulatie: vallen, wisselen, match-3, raketsprong, linken, push-up + her-sprong, landen als starre groep + 3 s wachten, kolom-slot, game over, punten; stage 2: `outgoingShots`, `ingestGarbage`, `missChance`, `fieldSnapshot` | |
| 93 | | `src/main.js` | Menu, HUD, frameworkv3-scene, muis/touch, schaal naar het scherm, landing-bounce, selectie-tween, online-lobby | |
| 94 | | `src/offline.js` | Offline Strijd: progressie, bot-AI, lokale 'multiplayer'-schoten | |
| 95 | | `src/reward.js` | Puntenscherm na een spel/ronde (t1173): blokjes in 4 s (t1194) naar het profieltotaal; online rematch telt opnieuw (t1278) | |
| 96 | | `src/online.js` | API-client, polling, opponent-miniaturen, vlucht-tweens van afgeschoten blokjes | |
| 97 | | `server/` | PHP API: OAuth, lobby, shots, SQLite in `data/` (niet gedeployed) | |
| 98 | | `server/lib/planets.json` | Catalogus van 12 planeten (JS en PHP delen dit bestand) | |
| 99 | | `docs/ASSUMPTIONS.md` | Ingevulde aannames waar de specificatie ruimte liet | |
| 100 | | `src/build.sh` | Concateneert de bronnen naar `build/game.js`, kopieert de PHP-API naar `build/` en zet content-hash-querystrings (`?v=`) op `game.js`, `style.css` en `framework.js` in `index.html` (t1256) | |
| 101 | | `build/` | Speelbare output: `index.html`, `style.css`, `framework.js`, `game.js`, `images/`, PHP-API | |
| 102 | | `test/` | Unit tests (`node --test`) voor de kern en de deploy-guard; `server/tests/run.php` voor de API | |
| 103 | | `ci/` | FTP-deploy, **zonder** `--delete`. Expandeert `$timftproot` zelf. Raakt `favicon.ico` en `data/` (config, database) niet aan. | |
| 104 | |
| 105 | Sprongfysica is parametrisch. Zwaartekracht (`jumpsToClear`) loopt van |
| 106 | 2,0 tot 4,0 (t1199: minimum was 1) en wordt getoond als percentage, |
| 107 | lineair: `pct = (v − 1) × 100` en `g = 9,81 × (v − 1)`, dus 2,0 = 100 % |
| 108 | (9,81 g), 3,0 = 200 % (19,62 g), 4,0 = 300 % (29,43 g) — in de |
| 109 | planeetkaarten, de HUD en de ontwerper. Een horizontale match van 3 springt |
| 110 | `1,5 × 13 / jumpsToClear` tegels hoog (t1119: de minimumsprong is 50 % |
| 111 | hoger); een verticale match van 3 krijgt 120 % daarvan, en elk extra |
| 112 | blokje +5 % (wordt nergens in het spel uitgelegd). De massa bepaalt hoe |
| 113 | lang de sprong omhoog duurt (onafhankelijk van de hoogte). Op de apex |
| 114 | versnelt de cluster geleidelijk tot de valsnelheid |
| 115 | (`apexEaseTime = 0,15 × fallTime`); daarna zweeft een cluster omlaag |
| 116 | op de **gehalveerde** eindsnelheid |
| 117 | (`clusterFallSpeed = 0,5 × 13 / fallTime`, t1122/t1124). Losse blokjes |
| 118 | (spawn, ongesteund, cargo) vallen op de volle |
| 119 | `fallSpeed = 13 / fallTime`. De luchtweerstand (`fallTime`) bepaalt die |
| 120 | valsnelheden én hoe snel de visuele landing-bounce is |
| 121 | (`bounceDuration = 0,12 × fallTime`). Een |
| 122 | vastgehouden blokje krijgt dezelfde schaal-tween als Tim's KWin Click |
| 123 | Tween (150 ms easeOutBack naar 80 %, 720 ms easeOutElastic terug). |
| 124 | Wissels (speler en bot) animeren visueel in 100 ms easeOutCubic (t1121). |
| 125 | Landt een cluster meteen in een match, dan is die sprong 25 % sterker, |
| 126 | stapeling additief (t1120). Daarbovenop telt een **combo** (t1197/t1198): elke |
| 127 | eerdere match in de lopende combo geeft +1 % sprong (1e match +0 %, 2e |
| 128 | +1 %, 3e +2 %, …), tot maximaal +30 %; maak je 5 s geen match, dan |
| 129 | begint de combo opnieuw. |
| 130 | Combo en landingsketting tellen op voor de sprong; boven het veld staat |
| 131 | als gele “+x%” met oranje rand **alleen de combobonus** |
| 132 | (`0,01 × min(combo, 30)`, t1200), zichtbaar zolang die groter dan 0 is. Zie `docs/ASSUMPTIONS.md`. |
| 133 | |
| 134 | **Menu tijdens het spel (t1193).** In **Spelen** en **Overleven** |
| 135 | staat rechtsboven een kleine menuknop (☰). Die pauzeert het spel en |
| 136 | biedt **Verder** en **Terug naar hoofdmenu**. Terug naar het menu beëindigt |
| 137 | de wedstrijd: ingelogd zie je eerst het puntenscherm (titel “Spel |
| 138 | beëindigd”) zodat de punten tot dan toe via `play_finish` bij je profiel |
| 139 | komen; uitgelogd ga je direct naar het menu. In Spelen (rondes) volgt dan |
| 140 | geen volgende ronde. Het pauzemenu noemt de modus (t1201). De server-limieten op punten blijven gelden. |
| 141 | |
| 142 | **Laatste planeet (t1196).** De laatst gekozen planeet (standaard of |
| 143 | eigen) staat bij elk planeetkeuzescherm (Spelen, Overleven, Online) |
| 144 | alvast geselecteerd. Ingelogd staat die in je profiel op de server |
| 145 | (`set_last_planet`), uitgelogd in `localStorage`. Is een eigen planeet |
| 146 | verwijderd, dan valt de keuze terug op Terra. |
| 147 | |
| 148 | |
| 149 | ## Planeten (stage 3) |
| 150 | |
| 151 | Voor je gaat spelen — solo en in de lobby — kies je een **veld**. Elk veld |
| 152 | is een planeet met een volk, vijf eigen kleuren/vormen, en drie natuurwetten: |
| 153 | |
| 154 | - zwaartekracht — hoe hoog de eerste sprong is (`g`, als percentage: 100 % = 9,81 g, minimaal 100 %) |
| 155 | - luchtweerstand — hoe snel blokjes weer vallen (`d`) |
| 156 | - massa — hoe snel de sprong omhoog gaat (`F`, newton) |
| 157 | |
| 158 | Die drie waarden bepalen een interne moeilijkheids-Power (0–1). De |
| 159 | miss-kans van een afgeschoten blokje is `0,60 − 0,55 × Power` (60 % op |
| 160 | het makkelijkste veld, 5 % op het moeilijkste). De **getoonde** Power in |
| 161 | de kiezer, de HUD en de lobby is het omgekeerde daarvan: |
| 162 | `1 − miss / 0,60` als percentage. 0 % miss is 100 % Power; 60 % miss is |
| 163 | 0 % Power. Aurel toont 0 %, Terra 44 %, Cinder 92 % (de bodem is 5 % |
| 164 | miss, dus niet 100 %). In een online wedstrijd telt **jouw** planeet |
| 165 | voor de blokjes die jij verstuurt. De twaalf werelden en hun getallen |
| 166 | staan in `server/lib/planets.json`. De blokplaatjes zijn unieke |
| 167 | placeholders (`build/images/block-{planeet}-{kleur}.png`); Tim kan ze |
| 168 | zelf vervangen. |
| 169 | |
| 170 | ## Planeetontwerper |
| 171 | |
| 172 | Ingelogde spelers zien op het hoofdmenu hun puntentotaal en de knop |
| 173 | **Planeetontwerper**. Punten verzamel je door ingelogd te spelen |
| 174 | (Overleven aan het einde, elke ronde van Spelen, en Online bij |
| 175 | uitschakeling). Ze worden niet uitgegeven: bij vaste drempels (Terra |
| 176 | gratis, daarna 500 punten en elke volgende 14,5 % hoger) ontgrendel |
| 177 | je extra blokjes. |
| 178 | |
| 179 | In de ontwerper maak, bewerk of verwijder je eigen planeten (naam, |
| 180 | bevolking, de drie sliders voor zwaartekracht / lucht / massa, en |
| 181 | een live Power-preview met dezelfde formule als in het spel). Vijf |
| 182 | blokjesvakjes openen een raster van het hele register: blokjes die |
| 183 | al in een ander vak zitten zijn grijs, vergrendelde blokjes zijn |
| 184 | grijs mét een slotje. |
| 185 | |
| 186 | Eigen planeten kun je in **elke** modus kiezen (Spelen, Overleven, |
| 187 | Online). Online valideert de server de configuratie en |
| 188 | deelt een snapshot met de andere spelers. |
| 189 | |
| 190 | Lokaal inloggen: `auth.php?test=1`. Op de live site blijft de |
| 191 | ontwerper verborgen tot OAuth (`callback.php` + CI-geheim |
| 192 | `auth_client_secret`) is ingesteld. |
| 193 | |
| 194 | ## Puntenscherm (ingelogd) |
| 195 | |
| 196 | Na een spel in **Overleven**, na elke ronde van **Spelen** en na |
| 197 | een **Online**-wedstrijd zie je als ingelogde speler eerst midden in |
| 198 | beeld “You won!” of “You lost...” (in de gekozen taal). Na een seconde |
| 199 | schuift die tekst naar boven en vliegen blokjes van jouw planeet (ook |
| 200 | eigen planeten) in boogjes naar het getal onderaan: je profieltotaal. |
| 201 | Elk blokje is één nieuw verdiend punt, dus het getal loopt van het |
| 202 | totaal vóór de ronde naar het nieuwe totaal dat de server bevestigt. |
| 203 | Het tempo begint op 3 blokjes per seconde en versnelt per beloning |
| 204 | precies zo veel dat het laatste blokje altijd na ~4 s vertrekt, hoeveel |
| 205 | punten het ook zijn (t1194; bij weinig punten een vast tempo, zie |
| 206 | `docs/ASSUMPTIONS.md`). Daarna nog de vlucht van het laatste blokje. Daarna ga je, net als voorheen, |
| 207 | naar het menu, de volgende ronde, het resultaatscherm of de lobby. |
| 208 | Uitgelogd verandert er niets. Zie `docs/ASSUMPTIONS.md` (t1173). |
| 209 | |
| 210 | ## Taalkeuze |
| 211 | |
| 212 | Het spel is standaard Engels. Rechtsonder op het hoofdmenu staat de |
| 213 | vlag van de huidige taal; een klik opent tien vlaggen (VK, Nederland, |
| 214 | Duitsland, Frankrijk, Japan, China, Korea, Polen, Rusland, Spanje). |
| 215 | Gasten houden hun keuze in deze browser. Ben je ingelogd, dan is de |
| 216 | taal op auth.timfalken.com (`locale`-claim op `/oauth/token` en |
| 217 | `GET /api/me`, BCP 47; `zh-Hans` wordt hier `zh`) de standaard, totdat |
| 218 | je in het spel zelf een taal kiest. Die expliciete keuze wordt |
| 219 | opgeslagen en wint altijd (t1250). |
| 220 | |
| 221 | ## Deploy |
| 222 | |
| 223 | BlueGit CI (`blue-ci-cd.yml`) draait tests en een build op feature-branches en op `master`. Op `master` volgt daarna `ftp_upload`: `build/` gaat via FTP naar `projectftp` (secret: `$timftproot/meteors`; de job expandeert `$timftproot` zelf en normaliseert dubbele slashes). **Geen `--delete`**. De eerste deploy weigert te schrijven als de doelmap al vreemde bestanden bevat. |
| 224 | |
| 225 | Secrets: `timftphost` / `timftpuser` / `timftppassword` / `timftproot` (groep), `projectftp` (dit project), en `auth_client_secret` (dit project, zie hieronder). De groep en de andere projecten (verhalenboek, microchess) hebben geen auth-geheim; alleen FTP-gegevens. |
| 226 | |
| 227 | ## Spelen (rondes tegen bots, voorheen Offline Strijd) |
| 228 | |
| 229 | Op het menu kies je de grote knop **Spelen**, daarna een planeet (het |
| 230 | planeetscherm noemt de modus). Je speelt |
| 231 | tegen lokale bots alsof het multiplayer is (schoten, miss-kans, |
| 232 | miniatuurvelden), helemaal in de browser. Eerst 1 tegenstander, daarna |
| 233 | 2, en verder N tegenstanders voor N−1 rondes, met stijgende skill |
| 234 | (5 % + 1 % per ronde). Als je verliest zie je de bereikte ronde en |
| 235 | hoeveel tegenstanders je in totaal (over alle rondes) hebt verslagen |
| 236 | (t1198), onder de titel “Uitslag” (t1201). De HUD toont alleen “Ronde N”. |
| 237 | |
| 238 | ## Overleven (eindeloos, voorheen Spelen) |
| 239 | |
| 240 | **Overleven** is het eindeloze spel alleen: blokjes blijven vallen en |
| 241 | steeds sneller komen tot al je kolommen vastzitten. Intern heet de modus |
| 242 | nog `solo` (ook in `play_finish`), Spelen/rondes heet intern `offline` |
| 243 | (t1201). |
| 244 | Zie `docs/ASSUMPTIONS.md` (t1119). |
| 245 | |
| 246 | ## Online spelen (stage 2) |
| 247 | |
| 248 | Solo blijft werken, ook als online nog niet is ingesteld. Op het menu kies je |
| 249 | **Online spelen**. Na inloggen via [auth.timfalken.com](https://auth.timfalken.com) |
| 250 | (gestart vanuit Online kom je terug in het online-paneel; gestart vanaf |
| 251 | het hoofdmenu kom je terug op het hoofdmenu, t1193) maak je een lobby (of val je in met een code). Onbeperkt aantal spelers, praktisch |
| 252 | maximum 32. Iedereen drukt op Gereed; de host start als er minstens twee spelers |
| 253 | zijn en iedereen gereed is. |
| 254 | |
| 255 | Je eigen veld is het hoofdspel; miniaturen van de tegenstanders staan erboven. |
| 256 | Op een smal/staand scherm (t1203) worden die miniaturen (en hun labels) |
| 257 | kleiner gemaakt tot ze **allemaal** boven je veld passen (canvas van |
| 258 | 80 px breed tot minimaal 32 px, labels 11 → 9 px; rijen gebalanceerd). |
| 259 | Passen ze zelfs op 32 px niet, dan schuiven de al verslagen tegenstanders |
| 260 | naar achteren (volgorde blijft stabiel), zodat juist die achter het veld |
| 261 | vallen. Dit geldt voor Spelen (bots) en Online spelen; brede schermen |
| 262 | houden de layout naast het veld. |
| 263 | Blokjes die van je veld afschieten kiezen een willekeurige andere (nog niet |
| 264 | uitgeschakelde) speler en vliegen daar in een korte tween naartoe (draaien en |
| 265 | krimpen). De kans dat ze missen komt uit de **Power van jouw planeet** (60 % op het |
| 266 | makkelijkste veld, 5 % op het moeilijkste); dat gooit de server. Een raak |
| 267 | schot komt bij de ander aan als een vallend donkergrijs blokje dat na 3 seconden |
| 268 | op een stapel weer een kleur krijgt. Wie al zijn kolommen vol heeft, is toeschouwer |
| 269 | en geen doelwit meer. De laatste die overblijft wint; 1e/2e/3e staan 5 seconden |
| 270 | op het podium en daarna ga je terug naar de lobby. |
| 271 | |
| 272 | ### Vallende blokken en vertrekkende raketten |
| 273 | |
| 274 | - Vliegt een raketstapel omhoog, is het hoogste blok voorbij 75% van de |
| 275 | veldhoogte en gaat hij zeker het scherm uit, dan valt er geen nieuw blok |
| 276 | en geen ontvangen (grijs) blok in de kolommen van die stapel: ze kiezen |
| 277 | een andere kolom. |
| 278 | - Start van elke match/ronde: de eerste 3 s valt er elke 0,1 s een blok |
| 279 | (verdeeld over de legere kolommen), van 3 tot 6 s loopt de tussentijd |
| 280 | lineair terug naar 1 s. |
| 281 | - Daarna loopt het tempo op: na elk nieuw blok wordt de spawn-interval 0,3% |
| 282 | korter (minimum 0,1 s, na ca. 767 blokken / 5 minuten). Elk spel en elke |
| 283 | ronde begint weer bij 0 s, ook voor bots en online. |
| 284 | |
| 285 | ### Ontvangen blokken |
| 286 | |
| 287 | Blokken die je van een tegenstander (of bot) krijgt gaan nooit verloren. |
| 288 | Ze komen in een wachtrij en vallen pas als er plek is: het vorige blok in |
| 289 | die kolom moet een hele cel onder de bovenste rij zitten. Is de gewenste |
| 290 | kolom vol, geblokkeerd of bezet door een vertrekkende raket, dan kiest het |
| 291 | blok een andere open kolom; is er geen enkele open, dan wacht het. |
| 292 | |
| 293 | ### Raketvlam |
| 294 | |
| 295 | De vlam onder een raketblok wisselt 25 keer per seconde naar een willekeurig |
| 296 | ander frame, spiegelt in de helft van de gevallen en varieert licht in |
| 297 | grootte, breedte, hoogte (elk ±6–7%) en hoek (±2,5°). Alles draait om het |
| 298 | bovenste midden van de vlam, waar hij aan het blok vastzit. Met |
| 299 | "verminderde beweging" (prefers-reduced-motion) blijft het bij 12,5 fps en |
| 300 | alleen wisselende frames. |
| 301 | |
| 302 | ### Vliegende blokken en mini-velden (vloeiend) |
| 303 | |
| 304 | - Een blok dat je wegschiet vliegt **meteen** lokaal weg (geen wachten op de |
| 305 | server). Zodra de server antwoordt (raak/mis, doelkolom) buigt dezelfde |
| 306 | vlucht vloeiend af naar het echte doel; geen sprong, geen tweede blok. |
| 307 | - Een tegenstander ziet de vlucht vanaf jouw mini-veld vertrekken zodra het |
| 308 | serverbericht binnenkomt, als volledige boog (iets ingekort bij vertraging). |
| 309 | - Op de mini-velden van tegenstanders vallen blokken tussen de |
| 310 | serverupdates door vloeiend verder (voorspelling met hun valsnelheid). |
| 311 | Landen of lijnen wissen wordt nooit voorspeld: dat komt altijd van de server. |
| 312 | |
| 313 | ### Wat Tim moet instellen |
| 314 | |
| 315 | Online werkt pas als OAuth is ingesteld. Zolang dat niet zo is, blijft solo |
| 316 | beschikbaar en toont **Online spelen** een duidelijke boodschap. Je hoeft |
| 317 | `data/config.php` **niet** via FTP te zetten: de deploy schrijft dat bestand |
| 318 | zelf vanuit een CI-geheim. |
| 319 | |
| 320 | 1. Ga naar https://auth.timfalken.com/admin, bij de **bestaande** client |
| 321 | `projects.timfalken.com` (dezelfde als de andere sites op dit domein). |
| 322 | 2. Voeg het callback-pad **`/meteors/callback.php`** toe. Volledige URL: |
| 323 | `https://projects.timfalken.com/meteors/callback.php`. |
| 324 | 3. Kopieer het **bestaande** client-geheim. **Genereer het niet opnieuw** — |
| 325 | dat breekt de andere sites die dit geheim al gebruiken. |
| 326 | 4. Zet in BlueGit, bij dit project (`projects-timfalken-com/meteors`), een |
| 327 | **protected** (alleen `master`) geheim met de naam **`auth_client_secret`** |
| 328 | en als waarde dat bestaande geheim. Er is geen groepsgeheim voor dit: |
| 329 | de groep en verhalenboek hebben alleen FTP-credentials. Optioneel is |
| 330 | `auth_client_id` (standaard `projects.timfalken.com`); dat hoeft Tim |
| 331 | niet te zetten. |
| 332 | 5. De volgende deploy naar `master` schrijft `data/config.php` op de server |
| 333 | (alleen als het geheim niet leeg is; de waarde komt nooit in de logs). |
| 334 | Zonder geheim blijft een bestaand `data/config.php` ongemoeid. De |
| 335 | SQLite-database en sessies worden nooit gewist. `data/.htaccess` |
| 336 | weigert alle HTTP-toegang tot die map. `favicon.ico` wordt niet |
| 337 | overschreven. |
| 338 | |
| 339 | Lokaal (alleen op loopback, host én remote-adres) kun je zonder geheim |
| 340 | inloggen als `auth.php?test=1` of `auth.php?test=2`. |