Z jednej hry viac hier: realmy, rulesety a refaktor, ktorý nesmie nič zmeniť

Do js/ui/app.js sa 26. októbra 2026 dostal ďalší režim. Kolónia, hra na šesťuholníkovej doske, ktorú opisuje samostatný článok, si v prvej etape vyžiadala zoznam funkcií, ktoré ju nesmú vidieť: analýza, obrázok hry, hudba, štatistiky, úspechy, skúsenosti. Pre každú z nich pribudla jedna podmienka typu !g.colony. Súbor mal pritom k 26. októbru 3 546 riadkov a na druh hry sa pýtal 41-krát cez mode === '...', 22-krát cez .puzzle, 16-krát cez .watch a 8-krát cez .colony (predtým .leap).

Každý ďalší režim by tento vzor zopakoval. Preto padlo 26. a 27. októbra moje rozhodnutie usporiadať hru inak: nie ako jednu hru s výnimkami, ale ako viacero hier, ktoré zdieľajú jeden profil. Tento článok je záznam toho rozhodnutia a prvých piatich krokov (M0 až M4).

Dve vrstvy a jedna tabuľka pojmov

Z môjho porovnania tvaru, ktorý hra naberá, s hrami, kde jeden titul ponúka niekoľko samostatných režimov, vzišli dve vrstvy a slovník, ktorý platí pre každý rozhovor, dokument aj riadok kódu:

Jeden ruleset môže mať viac realmov, a preto sú vrstvy oddelené. Kampaň je realm vlastný, ale beží na rovnakých pravidlách ako prvý:

Mená Sporgard a Radgard sú moja voľba z 27. októbra. Kľúčové je, že identifikátor sa s názvom nikdy nemení (rovnaké pravidlo ako pri premenovaní hry). Ruleset chains má pri tom nepríjemnú zrážku: modul reťazcov úspechov sa volá Chains a kľúče chain.* majú v kóde 1 602 zmienok v 21 súboroch. Id chains zostalo (moja voľba), a preto globály nového rulesetu sa nesmú volať Chains a jeho texty dostanú predponu realm.chains.*.

Rozdelenie nesie aj rozhodnutia o hernom obsahu, zatiaľ len v pláne (nič z toho ešte nie je postavené): level a minca sú po realmoch, hrdina, rozprávač a hlavný level sú globálne, Zlatý svet kociek sa má stať šatníkom Kastgardu a svety Kameň a Železo šatníkom kampane. Časti realmu (minca, šatník, minihry, hlavolamy, tutoriál) sú voliteľné; realm môže byť prázdny a režim bez obsahu sa nezobrazí. Realm teda nie je „hra navyše“, ale zoznam toho, čo má.

Test, čo je realm a čo ešte len režim

Aby sa z každého nápadu nestal realm, zapísal sa test (návrh, zatiaľ bez rozhodnutia). Kandidát je realm, ak spĺňa body 1 až 3:

1. má vlastnú rodinu pravidiel, ktorú obmedzený konfigurátor iného realmu nevyjadrí;
2. má vlastný konfigurátor;
3. má AI alebo riešič hlavolamov, aby bolo možné sledovanie hry, hlavolamy a arénu AI súperov.

Voliteľné sú obsah pre viac režimov a hĺbka na level a mincu. Kandidát, ktorý spĺňa len body 1 a 2, je režim alebo realm s malým počtom častí. Ďalšie dva moje nápady z 27. októbra sú hop (rodina hier so skákaním po doske: dáma, halma, solitér) a pexeso (hľadanie párov). Žiadny nie je rozhodnutý ani naplánovaný, ale oba sú užitočné ako myšlienkový test. Hop je rodina pravidiel definovaná dátami, kde každá hra je variant. Pexeso je opak: skrytá informácia, žiadna doska a AI, ktorej úroveň je dĺžka pamäte. Ak má zmluva medzi rulesetom a realmom platiť aj pre ňu, je to dobrá skúška.

Najzaujímavejšie na tejto vrstve je pravidlo konfigurátora: obsah realmu smie používať len funkcie, ktoré ponúka konfigurátor jeho rulesetu. Konfigurátor Kastgardu má 29 herných nastavení (Settings.GAME_KEYS; 7 základných, 13 pravidiel, 6 mapových a 3 o hráčoch). Veže, kasárne, truhlice, portály a schopnosti hrdinu v ňom nie sú, a sú teda kampane. Test je mechanický, nástroj tools/realms.js prečíta každú minihru, hlavolam a lekciu a vypíše funkcie, ktoré používa:

Inventúra: 896 miest, ktoré sa pýtajú, aká hra beží

Prvý krok (dokument REALMS-R1.md, bez jedinej zmeny kódu) bol spočítať, kde sa kód na druhu hry pýta. Výsledok k 27. októbru:

• 732 riadkov v 86 súboroch js/ sa pýta, aká hra beží. Rozpadajú sa na 896 miest (rozhodnutí, blokov a stavov) v 114 súboroch.
• Mená tried: 179 miest sú rozhodnutia rulesetu, 166 režimu, 43 príznaky enginu (tie sa nemenia), 380 sú veci realmu, 54 globálne a 74 falošné zásahy.
• app.js má 280 miest. Podľa mapy riadkov je 34 % kampaň, 22 % obal aplikácie, 20 % Stacks^[3]. Kolónia a Watch nie sú bloky, ale kontroly príznakov (spolu 20 riadkov).
• **Zoznam režimov je v app.js napísaný päťkrát ručne**: pri showEnd, restartGame, tlačidlách „Hrať znova“ a „Späť“ a pri setEndButtons.
• Kolónia nie je nezávislá od Stacks. Volá len Rules.recolor a Engine.pushLog (10 a 4 riadky), no kvôli nim jej worker importuje deväť súborov enginu Stacks.
• Profil nevie uchovať, čo nepozná: 27 z 30 sond neznámych častí Profile.migrate zahodil a záloha s profile.v iným ako 1 sa obnovila ako prázdny profil a hlásila úspech.
• Na 157 súboroch a navrhnutom rozdelení do balíkov porušuje smer závislostí 141 zo 726 hrán.

Tie isté miesta podľa triedy ukazuje stĺpcový graf:

Posledné číslo je dôležité: zmluva realmov neznamená, že všetko hneď musí byť čisté. Zapíše sa zoznam výnimiek, ktorý sa smie len zmenšovať.

Zmluva: tri deklarácie a jedna formula

Inventúra ukázala, že medzi rulesetom a realmom treba tretiu tabuľku, pretože väčšina z 166 režimových miest nie je o realme ani o rulesete, ale o spôsobe hrania: aká je koncová karta, čo robí „Hrať znova“, aký má slot na uloženie.

Čo smie kód robiť, rozhoduje schopnosť (capability) podľa jednoduchej formuly: schopnosť vidí hru, ak ju ruleset vie (člen adaptéra), režim chce (jeho záznam) a realm ju má (jeho manifest). Napríklad analýza dohratej hry potrebuje záznam hry a hodnotu pozície (ruleset vie), režim musí záznam zanechať a realm musí analýzu uvádzať. Dnes je táto trojica jedna podmienka rozptýlená po kóde (!g.colony, g.watch, g.puzzle). Navrhnutých je 14 schopností, napríklad slot, record, replay, analysis, picture, music, watch, finish, stats, xp, achievements, daily, share, tutorial.

Celok drží správca realmov v jadre (js/core/realms.js). Nepozná žiadnu hru. Prečíta nastavenie buildu (ktoré realmy build obsahuje je nastavenie buildu, nie vlastnosť realmu), skontroluje závislosti, spustí realmy a komunikuje s každým cez malé API háčikov: start, stop, hub, saves a objekty daily a weekly. Realm vidí iba kontext ctx a spoločné funkcie jadra. Platí pravidlo s mojím potvrdením z 27. októbra: realmy na sebe nezávisia, jedinou výnimkou je Kampaň na Stacks. Čo majú dva realmy spoločné, ide do jadra, ale až keď vznikne druhý používateľ, aby sa jadro nezmenilo na odkladisko.

Päť krokov za jeden deň

Plán v dokumente rozdeľuje prácu na malé kroky, z ktorých každý je samostatná zmena, zlučuje sa sám a nesmie zmeniť žiadne pravidlo žiadnej hry. Prvých päť:

M0 sa robí prvý a osamote, pretože na ňom stojí neskoršie sľúbené „záloha prežije presun medzi edíciami“. Chyby sa najprv reprodukovali testami, ktoré na starom kóde zlyhali: importAll obnovil prázdny profil a povedal ok, ak mala záloha profile.v iné než 1, a loadProfile pri poškodenom texte nechal prvé uloženie prepísať originál prázdnym profilom. Oprava je malá: nový test Profile.isReadable, odmietnutie zálohy a kópia nečitateľného textu bajt po bajte do kľúča diceWars.profile.unreadable. Alternatíva, odmietnuť prepis pôvodného kľúča, sa zamietla: hráč by hral celé sedenie, ktoré sa nedá uložiť.

M2 patrí k tým krokom, ktoré sa na pohľad nezdajú ako práca. Desať testov alebo pomocných súborov pri inventúre zostalo zelených, hoci by už nič nestrážili, keď sa domovská obrazovka prepíše. Preto sa prvé pinuje: kým sa nič nezmení, zachytí sa, čo kód odpovedá dnes pre všetkých 18 spôsobov hrania. Ten istý zápis neskôr slúži ako kontrola, že tabuľka režimov dáva rovnaké odpovede.

M3 prešiel nezávislou revíziou, ktorú robil agent len na čítanie. Našla sedem chýb prvej verzie správcu, všetky sa opravili vo vlastnom commite a každú drží test, ktorý prešiel mutačným skúšaním. Typický príklad: vyhodená hodnota, ktorú String() nevie previesť na text, rozbila izoláciu zlyhania jedného realmu, takže zlyhanie jedného realmu mohlo strhnúť ostatné. Ďalšie: start a stop neboli bezpečné pri dvojitom volaní, pole s vlastnosťou toJSON prešlo ako čisté dáta a správca si pamätal výstup toJSON, nie to, čo sa skontrolovalo, a termín, ktorý sa nedal nastaviť, sa spustil hneď.

M4 prepisuje zdroj pravdy po jednej funkcii na commit. Zo štyroch prvých schopností (slot, stats, remarks, restart) sa každá vypočíta raz v begin() a uloží sa ku hre ako vlastnosť, ktorá sa neenumeruje, takže sa nedostane do kópie, JSON ani snímky. Tabuľka režimov potrebovala jedno nové pole, restart.start, pretože Restart a „Hrať znova“ spúšťajú v Kniežatstvách a v kampani rôzne hry. Jedna časť sa schválne nepremenila na pole tabuľky: stráž pre hru, v ktorej hrala AI. Ide o test metadát hry a nie vlastnosť režimu, lebo AI môže dohrať snímku aj dennej hry, minihry či misie, a čítanie z tabuľky by takú hru skórovalo a zapísalo. Tri piny napísané najprv na starý kód to chránia.

Ako sa dokazuje, že sa nič nezmenilo

Refaktor takéhoto rozsahu má jedinú pozitívnu požiadavku: žiadna hra sa nesmie správať ináč. Dôkaz sa skladá z viacerých vrstiev, všetky merané 27. októbra:

• node tools/baseline.js: všetkých 172 odtlačkov sedí.
• node tools/calibrate.js --verify: 18 meraní identických, 0 v rámci šumu, 0 zmenených (pred aj po).
• Zlaté záznamy (tools/replay.js --golden) zapísané znova sú bajt po bajte rovnaké; git diff súboru je prázdny.
• Record.RULES_VERSION (2) a Rules.GEN_VERSION sú nezmenené a žiaden z rules.js, engine.js, flow.js, ai.js, mods.js, scenario.js, objectives.js, puzzle.js a record.js nie je v rozdiele.
• Starý kód ako orákulum. Nová funkcia facts sa nesmie zapojiť, kým sa jej výsledok nezhoduje so starou cestou cez showEnd: test volá obe vedľa seba na 12 zlatých záznamoch a 32 hrách z 16 konfigurácií a porovnáva aj to najprísnejšie, profil: Profile.recordGame a Achievements.evaluate s argumentmi starej cesty a s argumentmi z facts nechávajú profily bajt po bajte rovnaké. Test navyše prehľadáva zdroj app.js, aby stará cesta nezastarla potichu.
• Testy správcu a tabuľky sa mutačne skúšali: zmenené pole záznamu, zmenený text karty, chýbajúca funkcia, preskočená požiadavka, neodstránený časovač, cyklus, ktorý sa neodmietol. Každá mutácia musela zlyhať na správnom teste.
• V paneli prehliadača s reálnymi klikmi sa prešli Kniežatstvá (výhra aj prehra), voľná hra, denná výzva, minihry, Puzzle Labs, misia kampane, Kolónia, Watch a lekcia „Vaša prvá hra“.

Plná sada po M4 mala 2 508 testov: 2 506 prešlo, 1 sa preskočil, 1 zlyhal. Zlyhal tests/rollwin.test.js („a move to make“) a zlyháva asi raz z tridsiatich spustení aj bez zmien (1 z 30 na čistom pracovnom strome, 1 z 12 v tomto behu). Nebol súčasťou zmeny a zostal nedotknutý.

Chyba, ktorú M4 sám našiel

Pri M4 sa objavil zaujímavý test: tests/mode-table.test.js pre sledovanú hru zlyhával asi raz z desiatich (4 zo 40 spustení, jedno po druhom, bez záťaže). Príčina nebola v záťaži. Pri sledovanej hre nie je hráč, ktorý by mal pevné hody, takže Flow losuje náhodnú soľ hodov. Mapa je pevná podľa semienka, no hra trvala 13 až 29 kôl (138 až vyše 600 virtuálnych sekúnd, medián 343), kým test čakal 600 virtuálnych sekúnd. Strana režimu dostala pevnú soľ a po oprave 40 spustení bez zlyhania. Viac o testoch, ktoré zlyhávajú raz z desiatich, je v článku o chybách týždňa.

Čo zostáva

Ukončené sú M0 až M4 z desiatich krokov (M0 až M9). Zostáva domovská obrazovka čítajúca karty realmov (M6), označenie obsahu realmom (M7), rozdelenie zmiešaných súborov ako settings.js, profile.js, store.js (M8) a fyzický presun súborov do balíkov, ktorý je len git mv (M9). Zostáva aj 154 riadkov v app.js: príznaky sledovanej hry, jediné skutočné vetvenie rulesetu pri výbere toku hry, príznaky hlavolamu v engine (tie ostávajú), celá kampaň a niekoľko súborov, ktoré sa nepreniesli, pretože ich testy volajú hry bez schopností. Ďalej príde fáza R2 (druhá etapa Kolónie už na registri), potom level, minca a šatník po realmoch, questy a nakoniec realm Kampaň a edície. Na webe zatiaľ platí rozhodnutie, že Kampaň je vypnutá.

Dokument pomenúva riziká, ktoré sa nezmenili: povrch API správcu (rastie háčik po háčiku, kým z neho nie je „boží objekt“), jadro ako odkladisko, malý počet hlavolamov v Kastgarde a to, že obal facts môže niekde nezodpovedať starej ceste. Každé má v dokumente odporúčanie. Všetkých desať otázok z časti 4 dostalo 27. októbra moje potvrdenie v pôvodnej podobe.

Čo si z toho odnášam

• Inventúra pred zmluvou. Čísla z kapitoly o realmoch (41, 22, 16 a 8 riadkov) boli pri prepočte správne, ale „38, 20 a 18 ďalších súborov“ započítavali aj deväť jazykových katalógov. Skutočné kódové súbory boli 29, 11 a 8. Číslo bez opisu, čo sa počítalo, vedie k nesprávnemu odhadu práce.
• Dôkaz sa píše skôr než zmena. Pin najprv na starý kód, potom prepis, potom ten istý pin. Piny M2 umožnili, aby každý z ďalších krokov bol „zelený“ aj „identický“.
• Tabuľka, ktorá nepozná výnimku, nie je hotová. Stráž pre hru dohranú AI skončila ako test metadát, lebo tabuľka by o nej povedala nepravdu. Dôležité bolo, že to odhalili piny napísané vopred, a nie až neskoršia chyba v hre.
• Flaky test je zvyčajne informácia. Zlyhanie raz z desiatich nebolo šum: bola v ňom náhodná soľ hodov, ktorá predĺžila hru nad čas, ktorý test čakal.
• Obmedzenie rozsahu pomáha. Správca realmov nesmie poznať názov žiadnej hry (test prehľadáva jeho kód na mená hier). Obmedzenie, ktoré sa dá otestovať, drží dlhšie než dohoda.

Po 27. októbri: od registra k balíkom

Tabuľka realmov vyššie je stav z 27. októbra a od nej sa veľa zmenilo: Kampaň už nie je realm, ale sekcia Kastgardu, mená Sporgard a Radgard odpadli a doskové hry majú jeden realm, Taflgard^[4]. Tento oddiel dopĺňa stav z 31. októbra 2026 (verzia 0.65.6); dátumy a verzie sú z git log hry.

Tabuľka režimov namiesto správcu. Na uložené hry sa správca realmov pýtať nemohol: manifest vyžaduje ruleset, ruleset vyžaduje Slots a 95 súborov testov a nástrojov načíta Profile bez manifestu. Dáta režimov preto prešli do troch súborov bez závislostí a číta ich modul ModeTable (DESIGN §55.2). Značky z M7 nesie 18 minihier, 28 hlavolamov a 90 reťazcov úspechov (§57.1).

Balíky a Taflgard. Kolónia ako prvá dostala vlastný priečinok (9 súborov) a presun odhalil pascu bez chybovej hlášky: worker štyri priečinky hlboko čítal jazykové súbory z cesty, ktorá platila len pre js/worker/, a hra by sa potichu vrátila k hlavnému vláknu. Cestu si worker teraz zistí zo self.location (§60.5). Po rozhodnutí z 28. októbra sa Kolónia presunula do js/realms/taflgard/games/colony/ a staré id karty colony sa číta ako taflgard (§61). Kampaň sa stala sekciou: dátový záznam registrovaný vlastným súborom, bez karty, s blokom v hube Kastgardu (§62). Druhá hra cárstva, Čiary, dostala 31. októbra konfigurátor a jeho dĺžka radu sa obmedzila na najviac 5; dôvod je v článku o dĺžke radu.

Testy a nástroje. Beh node tools/test.js --changed vyberie zo 186 testových súborov len tie, ktoré zmena zasiahne: pri pravidlách Kolónie 24 súborov za 49 s zo 296 s celej sady, pri rng.js, ktorý používa každá hra, 177 súborov a 95 % času (§73.3, 30. 10.). Pred zlúčením beží celá sada; dnes má 251 testových súborov (find tests -name '*.test.js', 31. 10. 2026).

Presun Kastgardu. Kastgard sa dal presunúť až po tools/paths.js, lebo 74 nástrojov pomenúva asi 640 súborov hry a cesty k nim skladá päť rôznych spôsobov (§94.1). Presun (§95) má tri časti: realm (4 súbory), hru Stacks (67) a hru Kampaň (20). Hráč nevidí nič. Pri práci sa našlo, čo rozbor nevedel: zápis tabuľky balíkov zabúdal polia, ktoré nepoznal, takže tools/move.js by z desiatich závislostí Kampane na Stacks urobil porušenia pravidla. Celá sada prešla dvakrát za sebou: 3 268 testov, 3 267 prešlo, jeden sa preskakuje.

Tri realmy v pláne. Analýza docs/SOLO-AND-HINTS.md (31. 10., sekcie 4.2 a 4.3) navrhuje popri Kastgarde a Taflgarde tretí realm pre hry bez súpera, pracovne logic: matematické hlavolamy. Podľa mojej odpovede z 31. októbra ide o úlohy na doske s číslami, ktoré s kladením a posúvaním figúrok nemajú nič spoločné, preto patria do vlastného realmu. Kostra realmu má stáť ako Taflgard, teda 3 súbory. Nič z toho nie je postavené a meno realmu nie je rozhodnuté.

Čo ostáva. Jadro stále pozná Kastgard: 65 závislostí do Stacks z 12 súborov a 45 do Kampane z 13 (krok M8b). Čaká obsah registrovaný hrou a všeobecné huby (K7, K8) a rozdelenie katalógov textov po balíkoch, ktorého prvý krok (Taflgard, 6 commitov) ešte nie je zlúčený. Domovská obrazovka ešte ukazuje točiacu sa kocku s Golden Dice v každom realme (moje pozorovanie z 31. októbra; kroky R3c1 a R3e), Zbierka nie je rozdelená a Talenty s Trofejami nie sú presunuté do Kampane (R5). Presun Kastgardu rozoberá osobitný článok, level, mince a úspechy po realmoch ďalší.

Zdroje a poznámky

• Pojmy a inventúra: docs/ROADMAP.md kapitola 26 (tabuľka pojmov, rozhodnutia 1 až 12, zrážka mena Chains) a docs/REALMS-R1.md časť 0 (896 miest v 114 súboroch; triedy 179, 166, 43, 380, 54 a 74) a časť 2 (zmluva).
• Kroky M0 až M4 (verzie 0.50.16 až 0.50.26): docs/DESIGN.md §52 až §54; test tests/store-unreadable-profile.test.js pre M0; nezávislá revízia M3 je v §53.
• Balíky a presun Kastgardu: docs/DESIGN.md §60 až §62 a §94 až §95; node tools/packages.js --check (31. 10. 2026): 983 závislostí, 120 porušení smeru v 22 súboroch.
• Počty obsahu: node tools/realms.js --check (27. 10. 2026).
• Testy: docs/DESIGN.md §95.4 (31. 10. 2026): 3 268 testov, 3 267 prešlo, jeden preskočený.
• Čo sa nepodarilo overiť: čísla z dokumentov sa po 27. októbri neopakovali a celá sada testov ani ťažké nástroje sa nespúšťali. Neoverené je, čo natiahlo js/ui/app.js z 3 546 na 3 867 riadkov, obsah rozpracovaných textových katalógov a točiaca sa kocka na domovskej obrazovke (moje pozorovanie z 31. októbra, v prehliadači nikto nepozeral).