BlueGit

projects-timfalken-com meteors

Files

meteors / README.md

README.md

README.md 10.1 KiB Download Raw

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) en druk op Spelen, of op Offline Strijd voor een singleplayer-wedstrijd tegen lokale bots. 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/

Architectuur

De spelkern is deterministisch en staat los van tekenen en invoer, zodat stage 2 (multiplayer) dezelfde simulatie kan hergebruiken.

PadRol
src/planet.jsPlaneet: zwaartekracht, luchtweerstand, massa, kleuren/vormen, spronghoogte, Power, apex-ease, bounce
src/rng.jsSeedable RNG (tests en later replays)
src/easing.jsQt-eases (easeOutBack / easeOutElastic) en Click-Tween-defaults voor de selectie-animatie
src/gameCore.jsSimulatie: 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.jsMenu, HUD, frameworkv3-scene, muis/touch, schaal naar het scherm, landing-bounce, selectie-tween, online-lobby
src/offline.jsOffline Strijd: progressie, bot-AI, lokale 'multiplayer'-schoten
src/online.jsAPI-client, polling, opponent-miniaturen, vlucht-tweens van afgeschoten blokjes
server/PHP API: OAuth, lobby, shots, SQLite in data/ (niet gedeployed)
server/lib/planets.jsonCatalogus van 12 planeten (JS en PHP delen dit bestand)
docs/ASSUMPTIONS.mdIngevulde aannames waar de specificatie ruimte liet
src/build.shConcateneert de bronnen naar build/game.js en kopieert de PHP-API naar build/
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. 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 is de daalsnelheid constant en gehalveerd (fallSpeed = 0,5 × 13 / fallTime, t1122). De luchtweerstand (fallTime) bepaalt die valsnelheid é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). Zie docs/ASSUMPTIONS.md.

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, m/s²)
  • 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.

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.

Offline Strijd

Op het menu kies je Offline Strijd, daarna een planeet. 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. 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 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. 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.

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
3Puzzelspel voor het web, zwaar geïnspireerd door *Meteos* (Nintendo DS). Gebouwd op
4[frameworkv3](https://git.timfalken.com/timfa/frameworkv3) (WebGL). Speelbaar met
5muis op desktop en met touch op mobiel, ook in portretstand.
6
7Live (na de eerste deploy): https://projects.timfalken.com/meteors/
8
9## Spelen
10
111. Open `build/index.html` (lokaal of live) en druk op **Spelen**, of op
12 **Offline Strijd** voor een singleplayer-wedstrijd tegen lokale bots.
132. Elke seconde valt er een blokje van één van vijf kleuren in een willekeurige kolom.
143. In een stilliggende kolom sleep je blokjes verticaal; ze wisselen om met de blokjes waar je langs gaat.
154. 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.
165. Blokjes die boven de bovenrand van het veld (10×13) verdwijnen, leveren punten op.
176. 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.
187. Een vallend (gespawnd) blokje landt op een vliegende cluster in dezelfde kolom en vliegt als vracht mee.
198. 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.
209. 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.
21
22Het 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.
23
24## Lokaal bouwen en draaien
25
26```bash
27# Eenmalig / bij een framework-update: bundel frameworkv3 en kopieer hem.
28# cd /pad/naar/frameworkv3 && ./glbuild.sh
29# cp js/framework.js /pad/naar/meteors/build/framework.js
30
31# Tests
32node --test test/*.test.js
33php server/tests/run.php
34
35# Game-bundel (src/ → build/game.js)
36./src/build.sh
37# of: npm run build
38
39# Placeholder-plaatjes opnieuw maken (optioneel; Tim kan ze zelf vervangen)
40python3 scripts/make-placeholders.py
41
42# Alleen het solo-spel (zonder online-API)
43python3 -m http.server 8080 --directory build
44# spel: http://localhost:8080/
45
46# Met lobby-API (lokale testers: auth.php?test=1 en ?test=2)
47php -S 127.0.0.1:8080 -t build build/router.php
48# spel: http://127.0.0.1:8080/
49```
50
51## Architectuur
52
53De spelkern is deterministisch en staat los van tekenen en invoer, zodat stage 2
54(multiplayer) dezelfde simulatie kan hergebruiken.
55
56| Pad | Rol |
57| --- | --- |
58| `src/planet.js` | Planeet: zwaartekracht, luchtweerstand, massa, kleuren/vormen, spronghoogte, Power, apex-ease, bounce |
59| `src/rng.js` | Seedable RNG (tests en later replays) |
60| `src/easing.js` | Qt-eases (easeOutBack / easeOutElastic) en Click-Tween-defaults voor de selectie-animatie |
61| `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` |
62| `src/main.js` | Menu, HUD, frameworkv3-scene, muis/touch, schaal naar het scherm, landing-bounce, selectie-tween, online-lobby |
63| `src/offline.js` | Offline Strijd: progressie, bot-AI, lokale 'multiplayer'-schoten |
64| `src/online.js` | API-client, polling, opponent-miniaturen, vlucht-tweens van afgeschoten blokjes |
65| `server/` | PHP API: OAuth, lobby, shots, SQLite in `data/` (niet gedeployed) |
66| `server/lib/planets.json` | Catalogus van 12 planeten (JS en PHP delen dit bestand) |
67| `docs/ASSUMPTIONS.md` | Ingevulde aannames waar de specificatie ruimte liet |
68| `src/build.sh` | Concateneert de bronnen naar `build/game.js` en kopieert de PHP-API naar `build/` |
69| `build/` | Speelbare output: `index.html`, `style.css`, `framework.js`, `game.js`, `images/`, PHP-API |
70| `test/` | Unit tests (`node --test`) voor de kern en de deploy-guard; `server/tests/run.php` voor de API |
71| `ci/` | FTP-deploy, **zonder** `--delete`. Expandeert `$timftproot` zelf. Raakt `favicon.ico` en `data/` (config, database) niet aan. |
72
73Sprongfysica is parametrisch. Een horizontale match van 3 springt
74`1,5 × 13 / jumpsToClear` tegels hoog (t1119: de minimumsprong is 50 %
75hoger); een verticale match van 3 krijgt 120 % daarvan, en elk extra
76blokje +5 % (wordt nergens in het spel uitgelegd). De massa bepaalt hoe
77lang de sprong omhoog duurt (onafhankelijk van de hoogte). Op de apex
78versnelt de cluster geleidelijk tot de valsnelheid
79(`apexEaseTime = 0,15 × fallTime`); daarna is de daalsnelheid constant
80en **gehalveerd** (`fallSpeed = 0,5 × 13 / fallTime`, t1122). De
81luchtweerstand (`fallTime`) bepaalt die valsnelheid én hoe snel de
82visuele landing-bounce is (`bounceDuration = 0,12 × fallTime`). Een
83vastgehouden blokje krijgt dezelfde schaal-tween als Tim's KWin Click
84Tween (150 ms easeOutBack naar 80 %, 720 ms easeOutElastic terug).
85Wissels (speler en bot) animeren visueel in 100 ms easeOutCubic (t1121).
86Landt een cluster meteen in een match, dan is die sprong 25 % sterker,
87stapeling additief (t1120). Zie `docs/ASSUMPTIONS.md`.
88
89
90## Planeten (stage 3)
91
92Voor je gaat spelen — solo en in de lobby — kies je een **veld**. Elk veld
93is een planeet met een volk, vijf eigen kleuren/vormen, en drie natuurwetten:
94
95- zwaartekracht — hoe hoog de eerste sprong is (`g`, m/s²)
96- luchtweerstand — hoe snel blokjes weer vallen (`d`)
97- massa — hoe snel de sprong omhoog gaat (`F`, newton)
98
99Die drie waarden bepalen een interne moeilijkheids-Power (0–1). De
100miss-kans van een afgeschoten blokje is `0,60 − 0,55 × Power` (60 % op
101het makkelijkste veld, 5 % op het moeilijkste). De **getoonde** Power in
102de kiezer, de HUD en de lobby is het omgekeerde daarvan:
103`1 − miss / 0,60` als percentage. 0 % miss is 100 % Power; 60 % miss is
1040 % Power. Aurel toont 0 %, Terra 44 %, Cinder 92 % (de bodem is 5 %
105miss, dus niet 100 %). In een online wedstrijd telt **jouw** planeet
106voor de blokjes die jij verstuurt. De twaalf werelden en hun getallen
107staan in `server/lib/planets.json`. De blokplaatjes zijn unieke
108placeholders (`build/images/block-{planeet}-{kleur}.png`); Tim kan ze
109zelf vervangen.
110
111## Deploy
112
113BlueGit 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.
114
115Secrets: `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.
116
117## Offline Strijd
118
119Op het menu kies je **Offline Strijd**, daarna een planeet. Je speelt
120tegen lokale bots alsof het multiplayer is (schoten, miss-kans,
121miniatuurvelden), helemaal in de browser. Eerst 1 tegenstander, daarna
1222, en verder N tegenstanders voor N−1 rondes, met stijgende skill
123(5 % + 1 % per ronde). Als je verliest zie je de bereikte ronde.
124Zie `docs/ASSUMPTIONS.md` (t1119).
125
126## Online spelen (stage 2)
127
128Solo blijft werken, ook als online nog niet is ingesteld. Op het menu kies je
129**Online spelen**. Na inloggen via [auth.timfalken.com](https://auth.timfalken.com)
130maak je een lobby (of val je in met een code). Onbeperkt aantal spelers, praktisch
131maximum 32. Iedereen drukt op Gereed; de host start als er minstens twee spelers
132zijn en iedereen gereed is.
133
134Je eigen veld is het hoofdspel; miniaturen van de tegenstanders staan erboven.
135Blokjes die van je veld afschieten kiezen een willekeurige andere (nog niet
136uitgeschakelde) speler en vliegen daar in een korte tween naartoe (draaien en
137krimpen). De kans dat ze missen komt uit de **Power van jouw planeet** (60 % op het
138makkelijkste veld, 5 % op het moeilijkste); dat gooit de server. Een raak
139schot komt bij de ander aan als een vallend donkergrijs blokje dat na 3 seconden
140op een stapel weer een kleur krijgt. Wie al zijn kolommen vol heeft, is toeschouwer
141en geen doelwit meer. De laatste die overblijft wint; 1e/2e/3e staan 5 seconden
142op het podium en daarna ga je terug naar de lobby.
143
144### Wat Tim moet instellen
145
146Online werkt pas als OAuth is ingesteld. Zolang dat niet zo is, blijft solo
147beschikbaar en toont **Online spelen** een duidelijke boodschap. Je hoeft
148`data/config.php` **niet** via FTP te zetten: de deploy schrijft dat bestand
149zelf vanuit een CI-geheim.
150
1511. Ga naar https://auth.timfalken.com/admin, bij de **bestaande** client
152 `projects.timfalken.com` (dezelfde als de andere sites op dit domein).
1532. Voeg het callback-pad **`/meteors/callback.php`** toe. Volledige URL:
154 `https://projects.timfalken.com/meteors/callback.php`.
1553. Kopieer het **bestaande** client-geheim. **Genereer het niet opnieuw** —
156 dat breekt de andere sites die dit geheim al gebruiken.
1574. Zet in BlueGit, bij dit project (`projects-timfalken-com/meteors`), een
158 **protected** (alleen `master`) geheim met de naam **`auth_client_secret`**
159 en als waarde dat bestaande geheim. Er is geen groepsgeheim voor dit:
160 de groep en verhalenboek hebben alleen FTP-credentials. Optioneel is
161 `auth_client_id` (standaard `projects.timfalken.com`); dat hoeft Tim
162 niet te zetten.
1635. De volgende deploy naar `master` schrijft `data/config.php` op de server
164 (alleen als het geheim niet leeg is; de waarde komt nooit in de logs).
165 Zonder geheim blijft een bestaand `data/config.php` ongemoeid. De
166 SQLite-database en sessies worden nooit gewist. `data/.htaccess`
167 weigert alle HTTP-toegang tot die map. `favicon.ico` wordt niet
168 overschreven.
169
170Lokaal (alleen op loopback, host én remote-adres) kun je zonder geheim
171inloggen als `auth.php?test=1` of `auth.php?test=2`.