CI failed once on aGameInProgressSurvivesARestart: a room took its snapshot after an event was handled, but sent the new table during it, so a server stopping in between saved the game one move behind what the players had already seen. A room now takes its snapshot before it sends a table or the seating. A refused connection (too many from one address, or too many messages) now flushes its error before the socket closes, so the client reads it. The connection-limit test waits for the server to see the first connection close before opening another, instead of racing it. Failing server tests now print their full message in the build log, as CI runs them inside the image build. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Bela
Hrvatska Bela do 1001 za Android i web. Igra se lokalno (ti i partner protiv računala) ili online s prijateljima: netko otvori sobu, ostali uđu s kodom sobe, a prazna mjesta igra računalo. Web (https://bela.mariosem.es) je ujedno i server na koji se spajaju i Android aplikacija i preglednik.
Struktura
| Modul | Što je u njemu |
|---|---|
engine/ |
Kotlin Multiplatform (JVM i Wasm): karte, pravila, zvanja, bodovanje, bot, pogled igrača na stol (TableView) i protokol za online igru (hr.bela.protocol). Isti kod vrti server, Android i preglednik. |
shared/ |
Cijelo sučelje (Compose Multiplatform) za Android i web: ekrani, stol, dijalozi, trening, online predvorje i soba, view modeli. |
app/ |
Android aplikacija: MainActivity, slike karata (2x), spremanje postavki, ažuriranje APK-a. |
web/ |
Web aplikacija (Kotlin/Wasm): ulazna točka, index.html, slike karata (1x). |
server/ |
Server (Ktor): sobe i online partije preko WebSocketa /ws, poslužuje i web aplikaciju. |
Važne datoteke:
engine/.../Game.kt: tijek partije (dijeljenje, zvanje aduta, štihovi, obračun).engine/.../Trick.kt: dozvoljeni potezi (praćenje boje, iber, sječenje).engine/.../Declarations.kt: zvanja.engine/.../RuleSet.kt: kućna pravila (do koliko se igra, štiglja, iber, belot, "visi").engine/.../Bot.kt: heuristički bot.shared/.../ui/CardArt.kt: sve što crta kartu, vidi niže.shared/.../online/OnlineViewModel.kt: veza sa serverom, ponovno spajanje, animacija poteza.shared/.../ui/WideTable.ktiLayout.kt: raspored za široki ekran (desktop, 16:9). Kad je prozor širi od 900 dp, visok barem 560 dp i položen (isWideLayout), stol se crta preko cijelog prozora s bočnom pločom (rezultat, adut, zadnji štih, blok), a početni ekran, predvorje i soba idu u dva stupca. Uži prozori i Android aplikacija zadržavaju raspored za mobitel.server/.../Room.kt: jedna soba (igrači, botovi, tempo partije).
Build i pokretanje
gradlew :engine:jvmTest :server:test # testovi pravila, simulacija 1000 partija, server (cijela online partija)
gradlew :app:assembleDebug # APK u app/build/outputs/apk/debug/
gradlew :app:installDebug # instalacija na spojeni uređaj ili emulator
gradlew :web:wasmJsBrowserDistribution # web u web/build/dist/wasmJs/productionExecutable/
gradlew :server:run # server na http://localhost:8080 (s gornjim webom)
Android aplikacija se spaja na wss://bela.mariosem.es/ws. Za lokalni server s emulatora: gradlew :app:installDebug -PbelaServer=ws://10.0.2.2:8080/ws.
Bez Android SDK-a (npr. u Dockeru) build se pokreće s -PbelaNoAndroid=true: tada se grade samo engine, shared (web), web i server. Kotlin/Wasm sam preuzima Node.js; na računalu gdje sigurnosni softver blokira novo preuzeti node.exe, u ~/.gradle/gradle.properties stoji belaDownloadNode=false, pa se koristi Node koji je već u ~/.gradle/nodejs.
Projekt koristi AGP 9.4.1, Kotlin 2.4.21, Gradle 9.8.2 i compileSdk 36, iste verzije kao AndroidTV projekt.
Karte
Android koristi slike lica karata iz app/src/main/res/drawable-nodpi/ (card_<boja>_<vrijednost>.webp, 726 px), web iz web/src/wasmJsMain/composeResources/files/cards/ (363 px, preglednik ih sve preuzme na početku), a znakovi boja (suit_<boja>.webp) i logo su zajednički u shared/src/commonMain/composeResources/drawable/. Postoje dva izvora, a skripta odabranog izvora prepisuje te slike:
| Izvor | Naredba | Napomena |
|---|---|---|
PNG špil (trenutno u upotrebi): tomasdrus/hungarian-playing-cards, kopiran u card_assets/hungarian-playing-cards/ |
python tools/import_png_cards.py |
363×585 px, WebP bez gubitaka. Repozitorij nema licencu, vidi NOTICE.md u toj mapi. Prije objave aplikacije treba dopuštenje autora. |
Naši SVG-ovi u card_assets/*.svg |
python tools/render_cards.py |
Treba Inkscape 1.x. Renderira 720 px. |
Poleđina je naša i crta se vektorski u kodu (CardBack).
Pravilo oštrine: karta se nikad ne crta šire od svoje slike. Svaka veličina karte ograničava se s maxCardWidth(). Slike se pripremaju u rezoluciji u kojoj se crtaju: Android ih dekodira smanjene, s mipmapama (app/.../platform/AndroidPlatform.kt), a web i znakovi boja smanjuju se prepolavljanjem (reduceImage). U debug buildu na Androidu svako povećanje slike zapisuje se u logcat pod oznakom BelaCards, pa se provjerava s adb logcat -s BelaCards.
Sve što crta kartu nalazi se u shared/src/commonMain/kotlin/hr/bela/shared/ui/CardArt.kt (CardFace, CardBack, SuitIcon, maxCardWidth).
U kodu se boje zovu HERC, KARO, PIK i TREF (= herc, bundeva, zelje, žir), a vrijednosti SEDAM … AS.
Trening brojanja
S početnog ekrana ("Trening brojanja"). Svaka runda je hrpa osvojenih štihova (po 4 karte) s izmišljenim adutom i ponekad zadnjim štihom (+10). Karte se pokazuju jedna po jedna, a zatim igrač bira jedan od četiri zbroja. Netočni odgovori nastaju iz tipičnih grešaka (dečko ili devetka u adutu, zaboravljen zadnji štih, propuštena desetka ili as…). Nakon odgovora vidi se svaka karta s bodovima i objašnjenje greške.
- Logika runde:
engine/.../CountingDrill.kt(s testovima). - Razine (Lako 8 karata, Srednje 12–16, Teško 20–28) i stanje:
shared/.../TrainingViewModel.kt. - Ekran:
shared/.../ui/TrainingScreen.kt.
Izgled
- Fontovi: Cinzel (naslovi, rezultat, oznake) i Inter (tekst), u
shared/src/commonMain/composeResources/font/. Oba su pod licencom SIL Open Font License, tekst licence je ulicenses/. - Boje, prijelazi i filc stola su u
ui/Theme.kt, zajednički gumbi i ukrasi uui/Components.kt. - Nova ruka se dijeli kao za stolom: 3, pa 3, pa 2 karte (talon) svakom igraču, počevši od igrača do djelitelja. Paketi lete od djelitelja, a karte se pojavljuju u ruci i lepezama tek kad stignu (
DealPlanushared/.../Deal.kt,DealOverlayuui/TableMotion.kt). Dijeljenje traje oko 1,6 s i završi prije nego što prvo računalo zove. - Kartu možeš kliknuti ili povući na stol. Kad je pustiš iznad ruke, odigrana je i dolijeće s mjesta gdje je puštena. Ako je pustiš niže, vraća se u ruku.
Zvuk
Igra daje zvučne signale za ove događaje:
- tvoj red za igru ili zvanje;
- upozorenje kad ti ostane 10 s, zatim otkucaji zadnjih 5 s (samo online);
- karta, dijeljenje, pokupljeni štih, zvanje aduta i kraj ruke;
- pobjeda ili poraz;
- netko je sjeo u tvoju sobu.
Zvukovi su WAV datoteke u shared/src/commonMain/composeResources/files/sounds/, po jedna za svaki Sound. Radi ih skripta python tools/make_sounds.py, kojoj trebaju numpy i ffmpeg (ili putanja do njega u FFMPEG). Skripta ih izrezuje iz snimaka u audio_assets/:
| Zvuk | Iz snimke |
|---|---|
turn |
nudge ring |
bid |
nudge ring dvaput |
warning |
reminder ring, tri udarca |
join |
prva dva udarca reminder ringa, kao zvono na vratima |
tick |
prvi klik sata, bez „tak“ |
card |
klizanje karte iz snimke karata |
deal |
tri brza klizanja, svako malo druge brzine |
trick |
isto klizanje, sporije i dublje, kao kad se karte pometu |
win, lose |
vesela i tužna melodija |
trump, hand |
nema snimke, pa ih skripta sintetizira (akord i dva zvona) |
Za svaki zvuk skripta radi isto:
- kod karata odreže brujanje ispod 900 Hz (klizanje je sve iznad 1 kHz), a glasni udarac iz te snimke ne koristi jer pojačan zvuči oštro;
- makne tišinu na početku, da zvuk krene čim se zatraži;
- kraj utiša postupno, bez naglog reza.
Na kraju izjednači glasnoću: najglasnijih 100 ms svakog zvuka, izmjereno kao što ih uho čuje (K-težinjenje, ITU-R BS.1770), dovodi na −20 LUFS. To je oko 6 dB tiše od prijašnjih sintetiziranih zvona. Vrh ostaje ispod −4 dBFS, a oštrim klikovima (sat) blagi limiter skrati samo vrh. Test SoundFilesTest provjerava da svaki Sound ima ispravnu datoteku.
Na Androidu se zvukovi puštaju preko SoundPool (app/.../AndroidSounds.kt), u pregledniku preko Web Audio (web/.../WebSounds.kt). Učitavaju se u pozadini nakon pokretanja (Sfx.load). Preglednik dopušta zvuk tek nakon prvog klika na stranici.
TableCues uspoređuje uzastopna stanja stola i odlučuje što zasvira. Radi izvan Compose kompozicije, pa se signal „tvoj red“ čuje i kad je kartica preglednika u pozadini.
Zvuk se uključuje i isključuje gumbom zvučnika na stolu ili u Postavkama, a izbor se pamti.
Online igra
- Igrač upiše ime i otvori sobu (dobije kod od 4 znaka, npr.
T2UT) ili uđe u postojeću s kodom. Poveznicahttps://bela.mariosem.es/?soba=KODotvara web s već upisanim kodom. - U čekaonici se vidi raspored za stolom; prije početka svatko može sjesti na prazno mjesto. Domaćin pokreće igru, a prazna mjesta igra računalo (u Androidu i webu prikazano robotom).
- Server vodi cijelu partiju (
engine) i svakom igraču šalje samo njegov pogled: svoje karte, za ostale samo broj karata. Tempo je isti kao lokalno (Pacing). - Kad veza pukne, igrač se vraća na svoje mjesto (kod sobe i token se pamte, pa radi i nakon zatvaranja aplikacije ili osvježavanja stranice). Ako ne stigne za 10 s, za njega igra računalo dok se ne vrati; nakon 10 minuta gubi mjesto. Sljedeća ruka kreće kad su svi spojeni igrači spremni.
- Svaki potez i zvanje imaju vremensko ograničenje od 30 s (
Protocol.TURN_TIME_MS,Timing.turnTime). Odbrojavanje se vidi kao prsten oko portreta igrača koji je na redu. Tvoje vlastito vrijeme vidiš na pločici „Ti“ dok igraš, a ispod ponude aduta dok zoveš. Kad vrijeme istekne, računalo odigra taj potez umjesto igrača.- Dva istekla poteza zaredom: računalo igra umjesto igrača bez čekanja dok on ne pritisne „Vraćam se“ (
ClientMessage.Here). Ako za stolom nema drugih ljudi, igra ga tada čeka. - Nakon ruke: sljedeća ruka kreće najkasnije za 30 s, i ako je netko ne potvrdi.
- Protiv računala: nema odbrojavanja.
- Dva istekla poteza zaredom: računalo igra umjesto igrača bez čekanja dok on ne pritisne „Vraćam se“ (
Ponovno pokretanje servera (nova verzija, restart računala) ne prekida partije. Server zapisuje otvorene sobe u $DATA_DIR/rooms.json: svakih nekoliko sekundi kad se nešto promijeni i još jednom kad se gasi (docker stop šalje SIGTERM). Pri pokretanju ih učita prije nego što primi prvu vezu. Klijenti se sami ponovno spoje i nastave s istim kartama i rezultatom; računalo ih čeka 30 s prije nego što odigra umjesto njih. Spremljene sobe starije od 10 minuta se ne učitavaju. Ako DATA_DIR nije postavljen (npr. gradlew :server:run), sobe žive samo u memoriji.
- Spremanje i učitavanje:
server/.../RoomStore.kt(datoteka),Rooms.kt(kada),Room.kt(snapshot,restore). Partija se sprema kao sjeme i popis poteza (GameRecord, isti zapis kao spremljena lokalna igra) i ponovno odigra pri učitavanju. - Ako se pravila u novoj verziji promijene tako da se stara partija ne može ponovno odigrati, soba ostaje, ali bez partije: igrači se vrate u čekaonicu i domaćin pokrene novu.
Soba nestaje kad je svi napuste, 10 minuta nakon što se posljednji igrač odspoji, ili nakon 3 sata u kojima nitko od igrača ništa nije odigrao ni kliknuo, čak i kad im je stranica otvorena (Timing.idleClose). Tada spojenim igračima javi da je soba zatvorena.
Zaštita od skripti (server/.../Limits.kt), po IP adresi:
- Pogađanje kodova: nakon 10 pogrešnih kodova adresa može pokušati još jedan kod u minuti. Dok je blokirana, ne dobiva odgovor ni za točan kod, pa joj pogađanje ne koristi. Povratak na svoje mjesto (token) nije ograničen. Taj povratak na nepostojeću sobu i povratak s krivim tokenom dobivaju isti odgovor, tako da ni preko toga ne može doznati koji su kodovi zauzeti.
- Otvaranje soba: 10 soba zaredom, zatim jedna svake 3 minute. Ukupno je dopušteno najviše 2000 otvorenih soba.
- Veze: najviše 32 istodobne veze s jedne adrese.
- Poruke: 40 poruka odjednom, zatim 10 u sekundi po vezi. Kad veza to prijeđe, server je prekine.
Server uzima adresu iz X-Forwarded-For samo kad veza dolazi s lokalne ili Docker mreže, odnosno od proxyja. Ako proxy ne šalje X-Forwarded-For, svi igrači izgledaju kao jedna adresa i dijele ograničenja. Server to jednom upozori u logu (Connections come from … without X-Forwarded-For).
Server, Docker i Gitea Actions
Jedna Docker slika (Dockerfile) gradi web i server (uz testove) i pokreće server koji poslužuje web na /, igru na /ws i /health. Gitea Actions (.gitea/workflows/release.yml, isto kao Keep) na svaki push na main gradi sliku, skenira je Trivyjem i objavljuje kao git.mariosem.es/msemes/bela:<sha> i :latest. Za objavu repozitorij treba tajnu REGISTRY_TOKEN (osobni token s write:package).
Postavljanje: docker compose pull && docker compose up -d s docker-compose.yml iz repozitorija. TLS i domenu bela.mariosem.es rješava vanjski ingress, koji mora propuštati WebSocket na /ws. Sobe se čuvaju na imenovanom volumenu bela-data (/data u kontejneru); umjesto njega može se montirati i mapa s hosta (./data:/data), bez obzira na to čija je. Kontejner se pokreće kao root samo zato da /data preda korisniku bela (uid 10001), a zatim server radi kao bela (docker-entrypoint.sh). Ako u composeu postaviš user: "1000:1000", server radi kao taj korisnik i /data mora biti zapisiva za njega. Ako spremanje ne uspije, server javi upozorenje u logu (Could not save the rooms…) i radi dalje, samo bez spremanja.
Izdanja i ažuriranje
- Izvorni kod: https://git.mariosem.es/msemes/Bela
- Izdanja (javno): https://git.mariosem.es/msemes/Bela-Release-Android. Svako izdanje ima tag
v<verzija>i APK pod istim imenombela.apk, pa ova poveznica uvijek vodi na najnoviji: https://git.mariosem.es/msemes/Bela-Release-Android/releases/download/latest/bela.apk. Na nju vodi i QR kod u Postavkama. - Verzija se računa iz broja commitova (kao kod Keepa):
versionCode= broj commitova,versionName= isti broj kao brojač (#13 →0.1.3). Web nosi isti broj.
Objava nove verzije (nakon commita i pusha):
powershell -File tools\build-release.ps1 -Notes "Što je novo"
powershell -File tools\build-release.ps1 -BuildOnly # samo potpisani APK, bez objave
Skripta pri prvom pokretanju stvara ključ za potpisivanje: bela-release.jks i keystore.properties u korijenu projekta. Git ih ignorira. Spremi ih na sigurno. Bez tog ključa instalirane aplikacije se više ne mogu ažurirati. Prijava na server ide preko BELA_GITEA_TOKEN, datoteke .gitea-token ili vjerodajnica koje git već ima.
U aplikaciji: Postavke → Ažuriranje provjerava najnovije izdanje, preuzima APK, provjerava SHA-256 i otvara sistemsku instalaciju (app/.../update/Updates.kt).
Ikona
icon.png u korijenu je ikona i logo. python tools/make_icon.py iz nje radi adaptivnu Android ikonu (sadržaj stane u krug, okolo je filc u boji ruba) i logo za početni ekran i Postavke. Ikone weba (favicon.png, icon-192.png…) su u web/src/wasmJsMain/resources/.
QR kod u Postavkama je unaprijed izračunat (shared/.../ui/QrMatrix.kt, web nema QR koder); gradlew :app:testDebugUnitTest ga provjerava ZXingom i ispisuje nove retke ako se poveznica promijeni.
Spremanje partije
Partija se sprema nakon svakog poteza kao seed i popis poteza (GameRecord), pa se nakon zatvaranja aplikacije vraća točno gdje je stala.