Ako je poskladaná hra Audamir: vrstvy, registrácia, jeden ťah a sedadlá

Hra Audamir začínala ako jedna hra s kockami a územiami. Dnes má štyri hry v dvoch realmoch: kocky a územia s kampaňou, ktorá na nich stavia, v Kastgarde a Kolónia s Čiarami v Rokgarde; k tomu ešte dva realmy, v ktorých hra zatiaľ nie je. Jednotlivé stavby majú vlastné články: o zmluve medzi realmom a hrou je Z jednej hry viac hier, o presune Kastgardu do vlastného priečinka Presun, ktorý nesmie nič zmeniť, o stavebnici dosiek Dve hry na jednej doske a o textoch a názvoch súborov Texty ako stromy (pripravovaný článok č. 38). Tento článok je mapa celku: ako sa to dnes drží pokope, kde sa jednotlivé kusy stretávajú a hlavne čo ich drží, aby zmena, ktorá porušuje pravidlá, zhodila kontrolu, a nie až hráča.

Odpovedá na otázku, ktorú sa dá pýtať aj pri cudzom projekte: ako je taká hra poskladaná, aby sa dalo pridávať režimy a svety bez prepisovania, a ako sa to stráži (nie len nakreslí)? Obrázky nie sú ilustrácie. Sú nakreslené z merania stromu hry (verzia 0.122.0, stav zo 6. novembra 2026) a z prečítaného kódu; kde je to len schéma, titulok pod obrázkom to hovorí. Podkladom bola schéma architektúry z 29. októbra. Je o týždeň staršia než hra, a preto je každé tvrdenie nižšie overené v dnešnom kóde; kde sa dnes od schémy líši, text to povie.

Smer pravidiel je moje rozhodnutie z 27. a 28. októbra 2026. Pri tomto článku sa čítal dnešný kód, spúšťali sa nástroje hry a skúšalo sa, čo zhodia.

Tri vrstvy a jedno pravidlo smeru

Štyri slová, ktoré sa nižšie opakujú. Balík je priečinok kódu so zoznamom svojich súborov (dnes deväť balíkov a 338 súborov js/). Realm je to, čo hráč vidí: karta na domovskej obrazovke, hub s dlaždicami, vlastná úroveň a vlastné mince. Hra je sada pravidiel s vlastnou doskou, AI a záznamom (v kóde „ruleset“): stacks, campaign, colony, chains. Jadro (core) je to, čo používajú všetci: generátor náhody, mriežka, profil, správca realmov a obal aplikácie.

Pravidlo smeru sa zmestí do vety: realm používa svoje hry, hra používa jadro, jadro nepoužíva nikoho. Hra nepoužíva svoj realm a realmy sa navzájom nepoužívajú; jediný výnimočný vzťah je hra, ktorá stavia na inej hre svojho realmu (campaign stavia na stacks).

V Kastgarde sú dve hry (stacks má 81 súborov, campaign 41) a v Rokgarde dve (colony 19 a chains 20, v hre sa volajú Kolónia a Čiary). Vitgard a Telgard majú po 12 súborov, z toho tri kódu a deväť textov. Hru nemajú, a preto ich hráč nevidí: domovská obrazovka a huby sa kreslia len pre realmy, ktoré majú aspoň jednu hru (DESIGN §104.3).

Druhá vec na obrázku je červená, a pravidlo „jadro nepozná hru“ dnes neplatí celé. Nástroj tools/packages.js počíta hranu vtedy, keď súbor používa globálnu hodnotu, ktorú definuje súbor iného balíka (hľadá mená v kóde bez komentárov a textov, mená v zozname modulov a súbory pomenované cez require alebo importScripts). Hrán je 1 370 a 95 z nich ide proti smeru, v 21 súboroch: 59 z jadra do stacks, 24 do campaign, 8 do ostatných balíkov a 4 zo stacks do campaign. Dôvod je v tom, čo jadro dnes je. Nie je to len knižnica (35 súborov v js/core/), ale aj obal aplikácie (44 súborov v js/ui/): samotný js/ui/app.js má 3 124 riadkov a 40 z tých hrán, celé js/ui/ 64. V js/data/ je ďalších 9 hrán a v samotnej knižnici 18, v šiestich súboroch. Typický prípad je modetable.js: tabuľka režimov sa načíta skôr než správca realmov, a preto musí vedieť, ktoré tabuľky režimov existujú.

Preto stráž smeru nie je jedno tvrdé „nič“, ale dve pravidlá. Sedem z deviatich balíkov (obe Rokgardove hry a jeho realm, Vitgard, Telgard, realm Kastgard a campaign) je čistých: akákoľvek hrana proti smeru zhodí kontrolu. Dva (core a stacks) majú západku: tabuľka v súbore tools/packages-table.json zapisuje pre každý súbor, koľko hrán proti smeru smie mať. Viac nesmie, menej sa dá zapísať (--lower-ratchet) a vtedy číslo už nevzrastie. Obe pravidlá sa dali skúsiť na kópii stromu hry (git archive, hra sa nemenila). Do game.js v Kolónii pribudol riadok, ktorý siaha na Rules zo stacks:

$ node tools/packages.js --check
direction: 1371 edges between the files of js/,
  96 break the rule (…)
  FAIL rokgard/colony -> kastgard/stacks:
    js/realms/rokgard/games/colony/core/game.js
    -> js/realms/kastgard/games/stacks/core/rules.js
    (Rules)
rokgard/colony: does NOT pass (…)
packages:check found a problem in 1 place.
(kód ukončenia 1; riadky sú zalomené a skrátené)

Do súboru jadra, ktorý už jednu hranu má (js/core/phase.js), pribudlo meno z engine kociek. Čistý balík by zlyhal hneď; tu zlyhala západka:

ratchet: 1 problem
  - ratchet: js/core/phase.js has 2 edges that
    break the direction, the table allows 1
    (…/stacks/core/ai.js, …/stacks/core/engine.js)
packages:check found a problem in 1 place.
(kód ukončenia 1; riadky sú zalomené a skrátené)

Prečo to nie je len dekorácia, ukazuje ďalší obrázok: čo sa so západkou stalo, kým kód rástol.

Prvý zápis bol 120 hrán (29. októbra). Kým počet súborov vzrástol z 187 na 338, hrany klesli na 105 (31. októbra, kampaň odišla z obalu aplikácie), na 94 (1. novembra, štatistiky sa presunuli z jadra do balíka Kastgardu) a štvrtého novembra sa zvýšili o jednu, keď sa zlúčila výzva stránky (js/ui/app.js 39 → 40). Zvýšenie je zapísané v tabuľke, takže je v histórii. Pravidlo sa dá poľaviť, ale len viditeľne.

Registrácia pri štarte: čisté dáta a jeden správca

Keď sa stránka načíta, každý balík zapíše čisté dáta a funkcie; nič sa ešte nespúšťa. Je to manifest realmu (meno, hry, režimy, dlaždice, úroveň a minca), adaptér hry (jeden zmrazený objekt, ktorý ukazuje na kód hry: ako sa začína, aký má cyklus, záznam, AI a fakty hotovej partie), sekcia (hra, ktorá stavia na inej) a obsah, ktorý hra pridáva do spoločných zoznamov: minihry, hlavolamy, lekcie a tipy. Obrázok ukazuje, čo kto zapisuje; je to vyhľadanie volaní Realms.register(, Rulesets.register( a ďalších v súboroch balíkov.

Skutočný príklad je Rokgard. Jeho manifest vymenúva hry, ktoré realm hrá, adaptér každej hry sa zaregistruje na konci jej súboru ruleset.js a režim je jeden záznam tabuľky v modes.js (úryvky sú skrátené a zalomené):

// js/realms/rokgard/data/realm.js (skrátené)
const manifest = {
  id: 'rokgard', name: 'Rokgard',
  rulesets: ['colony', 'chains'],
  // …
};
Realms.register(manifest, api);

// js/realms/rokgard/games/colony/core/ruleset.js
return Rulesets.register(adapter);

// js/realms/rokgard/data/modes.js: Colony (skrátené)
{
  id: 'colony', ruleset: 'colony', tile: 'colony',
  slot: 'colony', counts: ['history', 'realms'],
  end: { branch: 'colony', card: 'colony' },
  again: 'colony-again', back: 'colony-setup',
  restart: { how: 'confirm', start: 'same-setup' },
  hud: { tips: false, narrator: false, quips: false },
},

Správca realmov (js/core/realms.js, 998 riadkov) potom prečíta zostavu (Build.realms; zostava napríklad môže vynechať sekciu kampane), skontroluje manifesty a to, čo si realmy navzájom pripájajú (requires, extends), zoradí ich podľa závislostí a zavolá start(ctx). Realm vidí len ctx (svoju časť profilu, generátor, texty, zvuk), nikdy iný realm. Ak pri jednom realme nastane výnimka alebo vyprší čas, zlyhá len on a ostatné bežia. A hlavne nepozná žiadnu hru: test prečíta jeho kód bez komentárov a zhodí zmenu, ktorá by v ňom pomenovala realm, hru alebo modul hry.

Obrazovky sa potom kreslia z registrov: domovská obrazovka robí kartu z každého realmu, ktorý má hru, hub dlaždice z tabuľky jeho režimov, zoznam rozohraných hier je zoznam slotov režimov (Kniežatstvá^[1], Kmene, voľná hra, denná výzva a ďalšie) a okná štatistík, pravidiel či nastavení sa zostavujú z toho, čo realm registruje (pages).

Sľub „nový režim nepotrebuje riadok v obale“ platí len napoly. Režim je riadok tabuľky (slot, koncová karta, tlačidlá „znova“ a „späť“, čo smie ukázať HUD) a obrazovky tabuľku čítajú, takže režim, ktorý hrá rovnakú hru ako ostatné, je len dáta. Riadok režimu Kolónia však pomenúva obslužné funkcie (colony-again, colony-setup) a tie definuje obal (napríklad 'chains-again': () => ChainsView.again() v js/ui/app.js). Nová hra sa obalu dotkne vždy. Tabuľka v DESIGN §104.5 z 31. októbra vymenúva 20 registračných miest a 13 z nich je v súboroch, ktoré upravuje každá hra (napríklad index.html, sw.js, riadok realmu v modetable.js, riadky v js/ui/app.js). Dnes to vidno aj hrubým počítaním: Čiary stoja v index.html na 13 riadkoch (obrazovka a desať skriptov), v sw.js na 5, v tools/compat.html na 4 a v style.css na 8. Pri stavbe Čiar to bolo 91 riadkov v 14 súboroch obalu (DESIGN §80.6). Registrácia ich teda zmenšila, nie zrušila.

Jeden ťah od ťuknutia po obraz

Cesta jedného ťahu v hre s kockami, pri jednom ťuknutí na políčko. Vľavo ide vstup dole, vpravo obraz hore.

Vstup ide dole. Dotyk alebo klik zachytí BoardInput (140 riadkov, js/ui/board-input.js). Rozozná ťuknutie od ťahania (do šiestich pixelov je to ťuknutie), od štípnutia dvoma prstami i od kolieska a pošle udalosť tap s číslom políčka. Nevie, aká hra beží: posiela ju ovládaču hry, ktorého mu dá obal. V hre s kockami je ním Interaction.tap (js/ui/interaction.js). Ten vie, že sa najprv vyberie útočník a potom cieľ, a že na dotyku sa podľa nastavenia potvrdzuje druhým ťuknutím. Potom zavolá Flow.humanAttack(from, to). Flow ťah overí pravidlami (políčko musí patriť sedadlu 0 a útok musí byť dovolený), zapíše ho do záznamu a vykoná: hod kociek sa vypočíta zo stavu hry a Engine.resolveAttack z neho urobí nový stav. Kolónia a Čiary majú vlastný ovládač (ColonyView, ChainsView) a vlastný cyklus hry, ktorý odpovedá tým istým menám, takže spoločné časti obrazovky (stavový riadok, tlačidlá) nevedia, ktorý z nich beží.

Obraz ide hore. Keď útok skončí, Flow zavolá háčiky obalu (onAttackEnd, onState) a obal prekreslí. Pohľad dosky robí StacksBoard.view(game, ui) (122 riadkov, js/realms/kastgard/games/stacks/ui/board.js): popis jednej chvíle dosky, teda čo je na ktorom políčku (vlastník, stoh kociek, terén), aké šance sa ukážu na hranách a ktoré políčka ešte vezmú kocku. Je čistý a len číta; test ho spustí nad zmrazenou kópiou hry v každom stave zbierky scén, ktoré sa kreslia, a porovná, či sa hra nezmenila. Vykresľovač js/ui/board.js (577 riadkov) ten popis nakreslí. Nevolá pravidlá a nečíta hru. Kolónia a Čiary majú vlastný popis dosky, vykresľovač je spoločný.

Stav je funkcia troch vecí. Partia je nastavenie, číslo hry (seed) a rozhodnutia. Preto záznam formátu 2 (Záznam partie, ktorý sa prehrá (pripravovaný článok č. 51)) nemusí uložiť nič iné než rozhodnutia každého sedadla a Replay.run ho z nich zahrá znova: mapa vznikne zo seedu a Flow hrá s rozhodnutiami zo záznamu. Z hry vychádza prúd udalostí (start, útok s cestou z jedného políčka na druhé, round, over). Prehrávač záznamu ich číta cez BoardEvents (338 riadkov, js/core/board-events.js: slová act a set, teda kto čo urobil a ako sa zmenil obsah políčok). Obraz partie, hudba a analýza ich čítajú priamo z prúdu Replay. Nikto z nich hru nemení; rozprávač tiež len pozoruje (Prvé tri minúty a prvé týždne).

Koniec partie je zatiaľ rozdelený na dva spôsoby. Adaptér hry vie vydať facts(game, ctx): výsledok, dĺžku, sedadlo človeka, úroveň AI a skóre. recordBoard v js/ui/app.js z nich urobí riadok histórie, skúsenosti, mince a úspechy realmu, ale len pre Kolóniu a Čiary. Hra s kockami má vlastnú cestu v showEnd. Jej facts existuje a test ju porovnáva so starou cestou (na dvanástich zlatých záznamoch a 32 partiách z 16 nastavení aj bajt po bajte profil, DESIGN §53.3 z 27. októbra), no nič ho nečíta.

Sedadlá: kto odpovedá na otázku „aký je tvoj ťah“

Každé sedadlo za stolom odpovedá cyklu hry na tú istú otázku: aký je tvoj ťah? Odpoveď sa líši len tým, kto ju dáva.

Človek odpovie ťuknutím: cez dvere Flow.humanAttack (a ich súrodencov: presun kociek, rozloženie kociek, koniec ťahu). Cyklus hry na to čaká. AI v Kastgarde odpovie funkciou. Flow má mozog pre sedadlá, ktoré nie sú človek, a ten je zmluva s dvoma funkciami, attack(game, player, k, rng) a place(…). Bežný mozog Bots.brain volá AI.choose(game, player, …) v hlavnom vlákne stránky; úroveň (1 až 3) a osobnosť sedadla si berie zo stavu hry. AI v Kolónii a v Čiarach odpovedá funkciou choose(game, player, level). Pohľad ju posiela workeru (worker/bot.js) ako snímku stavu a dostane ťah späť, lebo hľadanie úrovne 3 trvá až sekundu (v Čiarach na veľkej doske) a worker nechá stránku živú; ak worker zlyhá, zahrá sa najjednoduchší legálny ťah.

Ďalšie dva „mozgy“ nie sú AI hry, ale tá istá otázka. Pri prehrávaní záznamu dostane Flow skript, ktorý číta rozhodnutia zo záznamu, a žiadna AI sa nespýta. Nech dohrá AI nechá AI hrať cez tie isté dvere ako človeka (Flow.autoHuman), takže partia je tá istá hra s tými istými hodmi. Režimy teda menia, kto kde sedí, a nie pravidlá.

Poctivo k tomu patrí, že sedadlo je dnes skôr smer než hotová abstrakcia. Cyklus hry má jeden mozog pre všetky sedadlá, ktoré nie sú človek, nie samostatný ovládač pre každé sedadlo, a človek je vždy sedadlo 0 (humanAttack pozerá, či je políčko vlastníka 0). Režim Sledovať hru preto musí vypnúť štyri miesta, kde kód počíta so sedadlom 0 ako s človekom (hlavička watch.js). Skutočné druhé ľudské sedadlo by sa bez zásahu do cyklu hry nezaobišlo.

Vzdialené sedadlá, aréna a hra s priateľmi sú plán. ROADMAP kapitola 4 (miestnosti s kódom, AI za chýbajúcich) hovorí „nothing is built“, docs/ARENA.md je koncept z 23. októbra, ktorý je „not approved and not started“, a v js/ nie je sieťový kód (hľadanie WebSocket, RTCPeerConnection a EventSource tam nič nenašlo; nálezy sú len v nástrojoch hry, napríklad na kontrolu v prehliadači). Postavené je to, čo by sa na také sedadlo hodilo: záznam s rozhodnutiami každého sedadla a prehrávanie, ktoré overí partiu od cudzieho hráča bez AI. To je podľa mňa základ, nie sieť, a stav plánov nie je sľub.

Čo to drží pokope

Obrázky by boli len kresba, keby ich nikto nestrážil. Pri tomto projekte sú to testy a nástroje, ktoré zhodia zmenu, ktorá porušuje pravidlo; skúšky sú z kópie stromu hry:

Dve odpovede v tabuľke majú dôležitú vlastnosť: hovoria, ako to opraviť. Súbor s nevhodným názvom dostane vetu „premenuj ho podľa toho, na čo slúži, bez mena balíka (role Kolónie v core/ sú game, ai, flow, setup, ruleset, events)“. Test v koreni tests/ dostane „polož ho do priečinka balíka, ktorého správanie dokazuje, alebo do tests/tools/ pre nástroj“. Podľa mňa je to dôvod, prečo sa takáto stráž nevypne pri prvom meškaní: pravidlo, ktoré len zhodí build a nepovie, čo robiť, sa obchádza.

Test čistoty board-events.js ukazuje tretí druh stráže, nie smer hrán, ale charakter súboru. Súbor board-events.js musí byť čistá funkcia, takže jeho kód (bez komentárov a textov) nesmie obsahovať document, window, localStorage, Date, Math.random, fetch ani require(, a nesmie pomenovať hru ani jej ťah (dice, colony, attack a ďalšie). Čistota jadra bez DOM nie je len želanie: tie isté súbory beží hra v prehliadači, v testoch bez prehliadača a vo workeri.

Testy ležia tam, kde kód: test súboru js/<priečinok>/x.js je v zrkadle tests/<priečinok balíka>/<priečinok>/x.test.js. Nástroj tests-layout.js hlási 352 súborov testov (250 testov balíkov a 102 testov nástrojov). Test čistého balíka smie pomenovať len súbory jadra a svojho balíka, s jednou zapísanou výnimkou: test Kolónie potrebuje skutočnú hru s kockami, aby dokázal, že obe hry odmietnu snímku tej druhej. Všetkých testov je 4 609; plný verify.js na čistom strome prešiel (4 608 prešlo, 1 preskočený, 1 890 sekúnd), čo opisuje článok o pečiatke (pripravovaný článok č. 37).

Čo sa pri stavbe ukázalo inak a čo je dlh

Pri stavbe sa architektúra od návrhu odchýlila a práve tie odchýlky sú poučné. Štyri sa našli už počas práce. Prvá: jadro nie je čisté, má 95 hrán nahor (vyššie). Druhá: Kastgard sa fyzicky presunul do js/realms/kastgard/ až 31. októbra (028), no id realmu v kóde zostalo stacks, lebo id sa nemení, keď sa mení meno (tak to hovorí hlavička manifestu). Premenovalo sa až 6. novembra 2026 na kastgard a hlavička má od vtedy jednu zapísanú výnimku. Prepísalo sa len to, čo si hráč uložil pod starým id: predpona úspechov (stacks_… na kastgard_…) a rozloženie domovskej obrazovky, raz, pri štarte hry; čas aj poradie úspechov ostali. Id hry, jej pravidiel a balíka kastgard/stacks ani kľúče textov hry sa nezmenili. Dokázalo sa to na dátach starého kódu: 51 profilov, 1 193 kľúčov, 357 prechodov a 13 rozložení vyšlo po prepise rovnako, okrem premenovaného id. Opačným smerom to neplatí: starý kód nové dáta načíta, no nepozná nové ids, takže by znova odomkol úspechy a vyplatil Zlaté kocky; na starý kód sa preto po publikácii nevracia. Tretia: mená a postavenie sa menili. Realm hier na doske sa volal Sporgard, potom Taflgard a od 31. októbra Rokgard, kampaň bola najprv realm, potom sekcia a od 31. októbra hra, ktorá stavia na inej hre, hoci sa v kóde stále pripája volaním Realms.registerSection (028, Dve premenovania za jeden deň (pripravovaný článok č. 44)). Štvrtá: jedno jadro textov pre všetkých sa rozdelilo na stromy v balíkoch, aby nový realm nemusel písať do cudzích súborov (038).

Piata sa našla až pri čítaní kódu pre tento článok. Zmluva hovorí, že správca realmov vie od realmu žiadať hub, saves, daily a weekly. Hľadanie v js/ ukázalo, že tie hooky volajú len testy: dlaždice, rozohrané hry a denná výzva sa čítajú z tabuľky režimov a z obalu. Zmluva je v kóde, otestovaná a čaká na volajúceho.

Dnešný stav častí z návrhu v jednej tabuľke (hra 0.122.0, 6. 11. 2026):

Dlh má teda päť pomenovaných kusov: 95 hrán proti smeru (z toho 40 v app.js), facts pre hru s kockami, hooky bez volajúceho, spoločné miesta pri novej hre a súprava na hľadanie pre AI dosiek. Všetky sú v dokumentoch hry; žiadny nie je sľub, že sa spraví.

Čo si z toho odnášam

• Pravidlo bez západky je prianie. „Jadro nepozná hru“ je pekná veta, ale hodnotu má až s tabuľkou, ktorá povie, že dnes 95 hrán platí a viac nebude. Číslo sa dá znížiť a zvýšenie je viditeľné v histórii.
• Schéma sa starne rýchlejšie než kód. Návrh z 29. októbra mal po týždni zastarané stavy (krok B3 „nezlúčené“, udalosti „plánované“, profil po realmoch „beží“), dve nepravdivé tvrdenia (že jadro nepozná hru a že rozohrané hry a výzvy čítajú obrazovky od správcu realmov) a jedno prehnané (že každé sedadlo má ovládač svojho druhu). Preto sa obrázky kreslia z nástroja, nie z hlavy, a majú dátum.
• Registrácia zmenšuje spoločné miesta, nezruší ich. Z 20 registračných miest je 13 v súboroch, ktoré upravuje každá hra. Pravda je užitočnejšia než veta „bez zásahu do obalu“.
• Sedadlo je smer, nie hotová vec. Cyklus hry má jeden mozog a človeka na sedadle 0. Sieť by ho zmenila tak, ako ho zmenil režim Sledovať hru.
• Stráž má povedať, ako to opraviť. Správa, ktorá nepovie postup, sa po čase obchádza; tie z tabuľky ho hovoria.
• Čo je plán, má byť čiarkované. V obrázkoch aj v texte sa plán a stav oddeľujú: rozdiel, ktorý hráča, čitateľa aj vývojára najviac mýli.

Zdroje a poznámky

• Stav a dáta: hra Audamir 0.122.0 (6. 11. 2026); hra sa len čítala. Návrh z 29. 10. 2026 je v dokumentoch hry (docs/mockups/architecture.html).
• Balíky, hrany a riadky: node tools/packages.js --check (338 súborov, 1 370 hrán, 95 proti smeru v 21 súboroch), tools/packages-table.json a história západky v jej commitoch; testy podľa testDirs tabuľky.
• Registrácia, ťah a sedadlá: hľadanie volaní register v súboroch balíkov, js/ui/board-input.js, js/core/board-events.js, flow.js a bots.js; DESIGN §53.3, §80.6, §104.3 a §104.5.