A finger sliding a card up the page could be taken by the browser for scrolling, the bounce or pull-to-refresh (or a long press for selecting text), which cancels the drag and the card goes back into the hand. The page now hands every touch to the app (touch-action: none, overscroll-behavior: none, no selection or callout). 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.