Přejít k obsahu

Psittacus

Průvodce ukládáním herního postupu ve Flutteru s dřevěnou deskou sudoku v džungli

Téma: Návody

Ukládání postupu ve hře ve Flutteru: shared_preferences vs Hive vs Isar vs SQLite

Jak spolehlivě ukládat data herního postupu ve Flutteru: praktické srovnání shared_preferences, Hive, Isar a SQLite, verzování schématu a cloud.

Autor Maksymilian JackowskiHlavní herní vývojář

Publikováno 13 min

V neděli ráno otevřete e-mailovou schránku a najdete zprávu od zklamaného hráče. Včera aktualizoval vaši hru sudoku na nejnovější verzi. Hned po spuštění zjistil, že jeho série 214 dní bez přerušení nenávratně zmizela a rozehraná deska se vymazala.

Při kontrole kódu rychle odhalíte příčinu. Uložený soubor neměl číslo verze. Nové vydání hry očekávalo jinou datovou strukturu, takže parser při načítání tiše vrátil null. Z technického pohledu data nebyla smazána z disku, pouze byla pro novou verzi nečitelná. Pro hráče v tom však není žádný rozdíl: jeho mnohaměsíční úsilí je jednoduše pryč.

Správná správa herního stavu ve Flutteru (v dokumentaci a vyhledávačích často hledaná jako flutter game save data) vypadá na první pohled snadno. Tato představa však padá ve chvíli, kdy nedomyšlená aktualizace poškodí skutečná uživatelská data. V tomto průvodci porovnáme čtyři nejběžnější databázová řešení ve Flutteru: shared_preferences, Hive, Isar a SQLite. Ukážeme si, jaká data má smysl ukládat, co je lepší vynechat a jak zavést ověřený vzor obálky dat (save envelope) s bezpečnou migrací schématu výhradně dopředu. Všechny ukázky kódu jsou napsané v čistém Dartu, takže si je můžete ihned vyzkoušet v DartPadu.

Proč je trvalost dat herní funkcí a ne jen technickým detailem

V mnoha vývojářských návodech bývá ukládání dat odsouváno na okraj jako rutinní úkol mezi návrhem herní desky a vydáním aplikace v obchodě. Pro hráče je však spolehlivost uloženého postupu základní smlouvou s vývojářem. Logické hry, včetně klasického sudoku, stojí na kontinuitě: nedokončená deska z ranní cesty vlakem, každodenní vítězná série a statistiky shromažďované po mnoho měsíců budují vztah ke hře. Pokud hráč po aktualizaci o tyto výsledky přijde, cítí se podveden. Místo aby začínal od nuly, hru raději rovnou odinstaluje.

Spolehlivé ukládání přímo ovlivňuje udržení hráčů (retenci). Uživatel musí mít jistotu, že může telefon kdykoli zamknout nebo přepnout aplikaci, aniž by riskoval ztrátu zadaných čísel. Pokud se odchod ze hry v průběhu řešení stane loterií, lidé ji v krátkých volných chvílích přestanou spouštět. Stabilní mechanismus ukládání je jednou z nejlevnějších a nejúčinnějších investic do spokojenosti hráčů.

Čtyři technologie ukládání dat ve Flutteru

V praxi téměř každý mobilní projekt ve Flutteru spoléhá na jedno ze čtyř řešení. Každý z těchto nástrojů vznikl pro jiné účely a nabízí odlišné výhody i kompromisy.

shared_preferences je oficiální klíč-hodnota plugin od týmu Flutteru. Obaluje nativní systémová úložiště: NSUserDefaults v systémech iOS a macOS a Android SharedPreferences nebo modernější DataStore Preferences. Umožňuje ukládat základní datové typy: int, double, bool, String a List<String>. Od verze 2.3.0 přináší knihovna dvě nová rozhraní: SharedPreferencesAsync a SharedPreferencesWithCache, zatímco původní třída SharedPreferences je označena jako zastaralá. Je to skvělý nástroj pro ukládání hlasitosti, zvoleného motivu nebo jednoduchých přepínačů, ale vůbec se nehodí jako hlavní herní úložiště.

Hive je lehká databáze typu klíč-hodnota napsaná v čistém Dartu, inspirovaná architekturou Bitcask. Data se ukládají do takzvaných boxů, které mohou být typované i dynamické. Po otevření boxu probíhá čtení synchronně přímo ze struktur namapovaných v paměti RAM, což zajišťuje bleskový přístup. Ačkoli původní autor vývoj předal komunitě, projekt aktivně pokračuje v podobě oficiálního forku hive_ce. Hive představuje skvělou volbu pro malé a střední logické hry se strukturovanými daty.

Isar je moderní NoSQL databáze od stejného tvůrce, která nabízí pokročilé dotazy, indexy, relace mezi objekty a plné ACID transakce. Verze 3 je zralá a stabilní. Práce na Isar 4 však trvají již dlouho a tempo vývoje znatelně polevilo. Než se pro Isar rozhodnete u nového projektu, zkontrolujte aktivitu v repozitáři na GitHubu a posuďte stav podpory.

SQLite, ve Flutteru nejčastěji používaná přes balíček sqflite nebo knihovnu drift, představuje osvědčený relační standard. Poskytuje plnou shodu s ACID, desítky let prověřenou stabilitu a podporu režimu WAL (Write-Ahead Logging) pro rychlé paralelní čtení. Bez obtíží zvládne tisíce dokončených partií sudoku s detailním záznamem každého tahu. Cenou za tyto možnosti je nutnost psát schémata, SQL dotazy a spravovat migrace tabulek.

Srovnání technologií

NástrojNáročnost zavedeníRychlost čtení a zápisuOptimální velikost datNejlepší využití
shared_preferencesTriviálníRychlé pro jednotlivé hodnotyDo několika KBNastavení zvuku, motiv vzhledu, příznaky
HiveNízkáBlesková (přímo v RAM)Do několika MB na boxHlavní soubor uložení logické hry
IsarStředníVelmi rychlá s indexyOd několika do desítek MBSložité modely s relacemi a filtry
SQLite (sqflite / drift)Střední až vyššíVysoká spolehlivost, ACID, WALLibovolná při správných indexechHistorie tahů, detailní statistiky, mnoho tabulek

Vizuální srovnání úložných řešení ve Flutteru jako dřevěných truhel různé velikosti

Při výběru se vždy řiďte nejvíce zatěžujícím scénářem, nikoli první rozehranou hrou. Samotný stav jedné desky sudoku zabírá zlomek kilobajtu. Pokud však po roce hráč nasbírá tisíc vyřešených hlavolamů s přesným časem každého tahu, objem dat výrazně naroste. Zvolte nástroj, který si poradí i po měsících intenzivního hraní.

Co ukládat na disk a co raději vynechat

Nejrychlejší operace na disku je ta, kterou vůbec nemusíte provádět. Před psaním kódu si přesně ujasněte, co skutečně vyžaduje trvalé uložení.

Co se vyplatí ukládat:

  • Stav rozehrané desky. U sudoku: identifikátor zadání, počáteční čísla (nebo seed generátoru), aktuální tahy hráče, poznámky tužkou a počet tahů. Herní čas ukládejte jako celkový počet milisekund (elapsedMs), nikoli jako živý objekt DateTime. Vyhnete se tak chybám při změně časového pásma nebo po dlouhém uspání telefonu.
  • Uživatelská nastavení. Hlasitost zvuků a hudby, vibrace (haptika), vybraný grafický motiv a úroveň obtížnosti.
  • Statistiky a série výher. Počet vyhraných her, průměrné a nejlepší časy a aktuální denní série s datem poslední započítané výhry. Konkrétní datum umožní sérii ověřit i po výpadku; samotné číslo jako streak = 12 vám při pochybnostech nic neřekne.
  • Příznaky postupu. Informace o dokončení tutoriálu nebo zobrazení výzvy k ohodnocení hry.

Co na disk nepatří:

  • Odvoditelná data. Seznam kandidátů (možných čísel pro danou buňku sudoku) spočítáte z aktuální desky během zlomku milisekundy. Ukládat takové hodnoty zbytečně zvětšuje soubor a přináší riziko chyb při aktualizaci logiky nápověd.
  • Dočasný stav uživatelského rozhraní. Pozice posunu v nabídce, otevřená vyskakovací okna nebo fáze animací patří do prezentační vrstvy. Po opětovném spuštění by mělo rozhraní začínat z čistého stavu.
  • Ukládání celé desky po každém jednotlivém dotyku. Postup ukládejte v rozumných okamžicích: po sérii tahů, při pozastavení hry nebo při přechodu aplikace na pozadí. JSON se sudoku je sice malý, ale stovky zápisů za minutu zbytečně zatěžují paměť flash.
  • Nekontrolovaný systémový čas ze zařízení. Hráči občas mění čas v telefonu, aby obešli časové limity. Místní čas používejte pouze pro zobrazení na displeji. Pro herní logiku a ověřování sérií se spolehněte na monotónní časovače nebo časová razítka ze serveru.

Následující ukázka představuje datovou třídu pro stav sudoku. Všechna pole reprezentují výhradně výchozí stav, volby hráče nebo kumulované čítače. Kód je v čistém Dartu a funguje přímo v DartPadu:

class SudokuSave {
  SudokuSave({
    required this.puzzleSeed,
    required this.entries,
    required this.pencilMarks,
    required this.elapsedMs,
    required this.hintsUsed,
  });

  factory SudokuSave.fresh(String seed) => SudokuSave(
        puzzleSeed: seed,
        entries: List.filled(81, 0),
        pencilMarks: const {},
        elapsedMs: 0,
        hintsUsed: 0,
      );

  final String puzzleSeed;           // Givens regenerate from the seed.
  final List<int> entries;           // 81 cells, 0 means empty.
  final Map<int, Set<int>> pencilMarks;
  final int elapsedMs;               // Accumulated time in milliseconds.
  final int hintsUsed;

  Map<String, Object?> toJson() => {
        'puzzleSeed': puzzleSeed,
        'entries': entries,
        'pencilMarks': {
          for (final e in pencilMarks.entries)
            '${e.key}': e.value.toList(),
        },
        'elapsedMs': elapsedMs,
        'hintsUsed': hintsUsed,
      };
}

Vzor obálky uložení: ochrana před poškozením dat

Ať už zvolíte Hive, SQLite nebo obyčejný JSON soubor, nikdy neukládejte herní stav přímo jako holý objekt. Vždy jej zabalte do vzoru obálky (SaveEnvelope). Tři základní metadata vás ochrání před většinou problémů v produkci: číslo verze schématu, časové razítko v UTC a identifikátor zařízení. Následující kód ukazuje strukturu v čistém Dartu:

class SaveEnvelope {
  SaveEnvelope({
    required this.schemaVersion,
    required this.savedAtUtc,
    required this.deviceId,
    required this.payload,
  });

  static const int currentVersion = 1;

  final int schemaVersion;
  final DateTime savedAtUtc;
  final String deviceId;
  final Map<String, Object?> payload;

  Map<String, Object?> toJson() => {
        'schemaVersion': schemaVersion,
        'savedAtUtc': savedAtUtc.toIso8601String(),
        'deviceId': deviceId,
        'payload': payload,
      };

  static SaveEnvelope? fromJson(Map<String, Object?> json) {
    final version = json['schemaVersion'];
    if (version is! int || version > currentVersion) {
      // Either corrupted, or written by a newer build. Do not guess.
      return null;
    }
    final savedAt = DateTime.tryParse('${json['savedAtUtc']}');
    if (savedAt == null) return null;
    final payload = json['payload'];
    if (payload is! Map<String, Object?>) return null;
    return SaveEnvelope(
      schemaVersion: version,
      savedAtUtc: savedAt,
      deviceId: '${json['deviceId']}',
      payload: payload,
    );
  }
}

Všimněte si ochranné podmínky v metodě fromJson. Pokud má uložený soubor verzi novější, než jakou podporuje aktuálně spuštěná aplikace, loader jej okamžitě odmítne. Starší verze hry tak nepřepíše novější soubor a nepoškodí neznámá pole. Místo pádu můžete hráči zobrazit srozumitelnou zprávu s žádostí o aktualizaci hry v obchodě.

Verzování schématu a migrace výhradně dopředu

Migrace dat by se měly skládat z krátkých, jednoúčelových funkcí. Každá z nich musí posunout verzi schématu přesně o jeden krok. Místo psaní obří funkce, která převádí jakýkoli historický formát na nejnovější, spojte jednotlivé kroky do řetězce:

Map<String, Object?> migrateSave(Map<String, Object?> raw) {
  var version = raw['schemaVersion'];
  if (version is! int) return raw; // Legacy file with no version: treat as v0.
  var data = raw;
  while (version < SaveEnvelope.currentVersion) {
    data = switch (version) {
      0 => _v0ToV1(data),
      1 => _v1ToV2(data),
      _ => data,
    };
    version = data['schemaVersion'] as int;
  }
  return data;
}

Map<String, Object?> _v0ToV1(Map<String, Object?> data) => {
      ...data,
      'schemaVersion': 1,
      'deviceId': data['deviceId'] ?? 'legacy-device',
    };

Map<String, Object?> _v1ToV2(Map<String, Object?> data) => {
      ...data,
      'schemaVersion': 2,
      'savedAtUtc': data['savedAtUtc'] ??
          DateTime.fromMillisecondsSinceEpoch(0, isUtc: true)
              .toIso8601String(),
    };

Tři osvědčené zásady pro bezpečný provoz:

  • Rozšiřujte schéma aditivně. Místo přejmenování existujících polí nebo jejich mazání přidávejte nové vlastnosti s rozumnými výchozími hodnotami. Starší verze kódu neznámé klíče bez problémů ignorují, ale při chybějícím očekávaném poli aplikace selže.
  • Testujte migrace na reálných souborech. Uložte si v jednotkových testech skutečné ukázkové soubory ze všech dříve vydaných verzí. Ruční vytváření umělých struktur v kódu testů často přehlédne jemné chyby při serializaci.
  • Zapisujte soubory atomicky. Při přímém zápisu na disk nejprve uložte data do dočasného souboru, vynuťte zápis z vyrovnávací paměti (flush) a poté cílový soubor nahraďte pomocí přejmenování (rename). Při náhlém vypnutí telefonu vám na disku zůstane buď původní neporušený soubor, nebo kompletní nový, nikdy však neúplný torzo. V relačních databázích jako SQLite máte atomicitu zajištěnou díky transakcím.

Postupná migrace databázového schématu dopředu znázorněná jako kamenné schody

Pět technických pastí, které zaskočí vývojáře

1. shared_preferences nezaručuje okamžitý zápis na disk. Oficální dokumentace otevřeně upozorňuje, že zápisy mohou probíhat asynchronně na pozadí a neexistuje záruka, že data přežijí okamžité ukončení procesu aplikace. Z tohoto důvodu tam kritická herní data nepatří. Pokud se ztratí hodnota hlasitosti, nic hrozného se nestane; pokud však zmizí série 200 dní v sudoku, hráč hru opustí. Na Androidu přejděte na novější rozhraní SharedPreferencesAsync, které ukládá data přes DataStore Preferences místo zastaralých XML souborů.

2. Asynchronní zápis na Androidu a zpoždění při spouštění. Metoda apply() v systému Android ihned vrací řízení, ale fyzický zápis na disk odkládá. V nepříznivých podmínkách systém tento zápis provede až při dalším studeném startu aplikace, což znatelně prodlužuje její načítání. U několika málo hodnot to nepoznáte, ale při desítkách zápisů během jedné relace začne hra zpomalovat.

3. Skvělé výsledky Hive v testech vycházejí z paměti RAM. Většina internetových benchmarků měří čtení z již otevřeného boxu uloženého v paměti RAM. Ačkoli se Hive takto má používat, tyto testy neříkají nic o délce studeného startu ani o propustnosti trvalého zápisu na flash úložiště. Počítejte s časem inicializace při prvním spuštění po aktualizaci. Pamatujte také, že původní balíček již není aktivně vyvíjen, proto v nových projektech sáhněte po forku hive_ce.

4. Dlouhý vývojový cyklus Isaru jako technologické riziko. Práce na verzi Isar 4 probíhají velmi dlouho bez finálního vydání. Databáze v mobilní hře představuje závazek na několik let, protože hráči se k logickým hrám vracejí dlouhodobě. Před nasazením prozkoumejte repozitář Isar na GitHubu a seznam hlášených chyb. Udržujte datové modely oddělené od samotné databáze, abyste ji v případě potřeby mohli vyměnit.

5. Serializace velkého JSONu na hlavním vlákně způsobuje záseky. Volání jsonEncode pro rozsáhlý herní stav probíhá na hlavním vlákně Flutteru (UI isolate) - tedy na stejném vlákně, které vykresluje snímky a zpracovává gesta. Provádění této operace po každém tahu může na slabších telefonech viditelně trhat obraz. Náročnou serializaci přesuňte do samostatného pracovního vlákna pomocí funkce compute() nebo ukládejte pouze v klíčových okamžicích. Více praktických tipů najdete v oficálním návodu Flutter cookbook o perzistenci dat.

Příprava architektury na cloudovou synchronizaci

Na začátku projektu zřídka stavíte vlastní backend. Vyplatí se však navrhnout datovou strukturu tak, aby přidání cloudové synchronizace za několik měsíců představovalo jednoduché napojení a ne důvod k přepracování celé hry.

Vzor obálky řeší většinu potíží. Následující pravidla vám v budoucnu ušetří spoustu práce:

  • Vždy uchovávejte schemaVersion, deviceId a savedAtUtc. Veškeré mechanismy řešení konfliktů se opírají o metadata. Bez čísla verze nespojíte data po aktualizaci hry na jednom ze zařízení. Bez časového razítka neurčíte chronologii a bez identifikátoru zařízení nezjistíte, odkud chyby pocházejí.
  • Slučujte data pole po poli místo přepisování celého souboru. Představte si hráče, který vyřešil sudoku offline na tabletu a o hodinu později odehrál krátkou partii na telefonu. Pokud synchronizaci postavíte na pravidle ‘novější soubor nahradí starší’, jeden z těchto postupů se nenávratně smaže. Slučování na úrovni jednotlivých polí zachová jak vyluštěnou desku, tak tahy z telefonu.
  • Hlídejte limity velikosti u cloudových služeb. Služby jako Google Play Games Services stanovují limity na velikost jednoho slotu uložení (často maximálně 3 MB). To je obrovský prostor pro čistá herní data, pokud do souboru nezačnete ukládat snímky obrazovky nebo nekomprimované logy.
  • Při určování pořadí nikdy nevěřte místnímu času v telefonu. Uživatelé si často mění systémový čas. Místní čas (savedAtUtc) berte jako doplňkovou informaci pro zobrazení v rozhraní. Pro autoritativní pořadí změn v cloudu vždy spoléhejte na časová razítka ze serveru.
  • Synchronizace musí chránit místní historii hráče. První přihlášení ke cloudu nesmí nikdy tiše přepsat dlouhou historii uloženou v telefonu. Při pochybnostech je bezpečnější data zkombinovat nebo se hráče přímo zeptat, který stav si přeje zachovat.

Cloudová synchronizace herních dat zobrazená jako lampiony nesoucí destičky sudoku

Doporučené konfigurace pro hru sudoku

Volba nástrojů závisí na rozsahu hry a množství ukládaných dat:

  • Pragmatická výchozí sestava: SharedPreferencesAsync pro jednoduchá nastavení v kombinaci s hive_ce pro hlavní soubor se stavem hry. Jedná se o lehké a rychlé řešení, se kterým jednotkové testy běží okamžitě a hra startuje bez prodlevy.
  • Analytická sestava: Knihovna drift postavená na SQLite. Skvělá volba, pokud chcete uchovávat historii každé partie sudoku, vytvářet detailní časové přehledy a umožnit hráčům filtrování výsledků.
  • Minimalistická sestava: Jeden verzovaný soubor JSON ukládaný do složky aplikace přes plugin path_provider s atomickým přejmenováním souboru. Pro jednoduchou hru s jednou aktivní partií je to zcela dostatečné řešení.

Kontrolní seznam před vydáním hry

Před publikováním hry nebo nahráním aktualizace do obchodu si zkontrolujte tyto body:

  • Každé uložení obsahuje pole schemaVersion, savedAtUtc a deviceId.
  • Loader odmítá soubory novější než verze aplikace, čímž chrání data před poškozením.
  • Zápis do souborů probíhá atomicky (dočasný soubor s přejmenováním nebo transakce v databázi).
  • Běžné volby jsou v shared_preferences, herní postup v odolném úložišti.
  • V testech máte uložené vzorové soubory z předchozích verzí schématu.
  • Serializace dat neblokuje hlavní vlákno UI během hraní.
  • Ověřili jste velikost dat po měsících intenzivního hraní.

Spolehlivé ukládání herního postupu je systém, kterého si hráči všimnou až ve chvíli, kdy selže. Věnujte pozornost verzování schématu a atomickému zápisu od prvního dne, a vaše sudoku bezpečně uchová herní série a postup hráčů po dlouhé roky.

Doporučené čtení

Polydocu - sudoku v podobě dobrodružství

Devět číslic, výprava džunglí, papoušek Poly a žádné umělé překážky. Zapište se na seznam čekatelů a pošleme vám zprávu v den vydání.

Připojit se k čekatelům

Jeden e-mail v den vydání, žádný spam.

Další tři zápisky ze stejného bloku, vybrané podle tématu, nikoli algoritmem.

Všechny články