
Zapisywanie postępów w grze we Flutterze: shared_preferences vs Hive vs Isar vs SQLite
Jak przechowywać dane zapisu we Flutterze bez utraty postępów graczy. Porównanie shared_preferences, Hive, Isar i SQLite, wersjonowanie schematu i chmura.
Opublikowano 14 min
Na tej stronie
W niedzielny poranek otwierasz skrzynkę mailową i widzisz wiadomość od rozżalonego gracza. Wczoraj zaktualizował Twoje sudoku do najnowszej wersji. Zaraz po uruchomieniu gry odkrył, że jego passa 214 dni z rzędu bezpowrotnie zniknęła, a układ planszy rozwiązany w połowie zresetował się do zera.
Szybko sprawdzasz kod i odkrywasz przyczynę. Plik zapisu nie miał numeru wersji. Nowe wydanie gry oczekiwało innej struktury danych, więc parser po cichu zwrócił null. Z technicznego punktu widzenia dane nie zostały skasowane, a jedynie stały się nieczytelne dla nowego kodu. Dla gracza nie ma to jednak żadnego znaczenia: jego wielomiesięczny postęp po prostu przepadł.
Poprawne zarządzanie stanem i zapisem gry we Flutterze (w dokumentacji i tutorialach zagadnienie to często znajdziesz pod hasłem flutter game save data) wydaje się z pozoru banalne. Przekonanie to pryska w chwili, gdy pierwsza nieprzemyślana aktualizacja uszkadza dane graczy. W tym przewodniku porównujemy cztery najpopularniejsze technologie bazodanowe we Flutterze: shared_preferences, Hive, Isar oraz SQLite. Zobaczysz, które informacje warto utrwalać, co lepiej pominąć oraz jak wdrożyć sprawdzony wzorzec koperty danych (save envelope) z bezpieczną migracją schematu wyłącznie w przód. Wszystkie przykłady kodu przygotowaliśmy w czystym Darcie, więc możesz je od razu przetestować w DartPadzie.
Dlaczego trwałość danych to funkcja gry, a nie tylko techniczny detal
Większość poradników traktuje zapisywanie danych po macoszemu. Zwykle poświęca się mu kilka linijek kodu gdzieś między rysowaniem planszy a publikacją gry w sklepie. Dla graczy trwałość postępów to jednak fundament. Gry logiczne, w tym klasyczne sudoku, opierają się na ciągłości rozgrywki. Niedokończona plansza w drodze do pracy, codzienna seria zwycięstw czy statystyki zbierane miesiącami sprawiają, że użytkownicy regularnie wracają do zabawy. Jeżeli po aktualizacji gracz straci swoje osiągnięcia, poczuje się oszukany. Zamiast zaczynać wszystko od nowa, po prostu odinstaluje grę.
Niezawodny zapis bezpośrednio przekłada się na retencję. Użytkownik musi mieć stuprocentową pewność, że może w dowolnej chwili zablokować ekran telefonu lub przełączyć aplikację bez obawy o utratę wpisanych cyfr. Jeżeli wyjście z gry w trakcie partii przypomina loterię, ludzie przestają uruchamiać ją w krótkich wolnych chwilach. Solidny mechanizm zapisu to jeden z najtańszych i najbardziej opłacalnych elementów budujących zaufanie graczy.
Cztery technologie zapisu we Flutterze
W praktyce niemal każdy projekt mobilny we Flutterze korzysta z jednego z czterech mechanizmów utrwalania danych. Każde z tych narzędzi powstało z myślą o innych wyzwaniach i oferuje odmienny zestaw zalet oraz ograniczeń.
shared_preferences to oficjalny plugin klucz-wartość rozwijany przez zespół Fluttera. Stanowi nakładkę na natywne mechanizmy systemowe, takie jak NSUserDefaults w systemach iOS i macOS oraz Android SharedPreferences lub nowocześniejszy DataStore Preferences. Pozwala przechowywać podstawowe typy: int, double, bool, String oraz List<String>. Od wersji 2.3.0 biblioteka wprowadza dwa nowe interfejsy: SharedPreferencesAsync oraz SharedPreferencesWithCache, a stara klasa SharedPreferences została oznaczona jako przestarzała. To znakomite narzędzie do przechowywania poziomu głośności, wybranego motywu czy prostych flag, ale zupełnie nie nadaje się na główny magazyn stanu rozgrywki.
Hive to lekka baza klucz-wartość napisana w czystym Darcie, wzorowana na architekturze Bitcask. Dane przechowuje się w tzw. pudełkach (boxes), które mogą być typowane lub dynamiczne. Po otwarciu pudełka odczyty są natychmiastowe, ponieważ dane trafiają wprost do struktur zmapowanych w pamięci RAM. Choć autor pierwotnego pakietu przestał go rozwijać, społeczność aktywnie utrzymuje i rozwija oficjalny fork hive_ce. Hive to świetny wybór do małych i średnich gier logicznych, które potrzebują szybkiego dostępu do ustrukturyzowanych danych.
Isar to nowoczesna baza NoSQL stworzona przez tego samego programistę, który zapoczątkował Hive. Oferuje zaawansowane filtrowanie, indeksy, relacje między obiektami i pełne transakcje ACID. Wersja 3 jest dojrzała i stabilna. Prace nad Isar 4 trwają jednak od wielu miesięcy, a tempo rozwoju wyraźnie zwolniło. Zanim wybierzesz tę bazę do nowego projektu, sprawdź aktywność w repozytorium Isar na GitHubie i upewnij się, że taki stan projektu Ci odpowiada.
SQLite, używany we Flutterze zazwyczaj przez wtyczkę sqflite lub wygodną nakładkę drift, to sprawdzony relacyjny standard. Zapewnia pełną zgodność z ACID, dekady stabilności oraz obsługę trybu WAL (Write-Ahead Logging), który gwarantuje szybkie i bezpieczne odczyty równoległe. Baza poradzi sobie z tysiącami ukończonych partii sudoku, szczegółową historią każdego ruchu i złożonymi statystykami. Ceną za te możliwości jest większa ilość kodu: musisz zdefiniować tabele, przygotować zapytania i samodzielnie zarządzać migracjami schematu.
Zestawienie technologii
| Narzędzie | Trudność wdrożenia | Szybkość odczytu i zapisu | Optymalny rozmiar danych | Najlepsze zastosowanie |
|---|---|---|---|---|
| shared_preferences | Banalna | Szybka dla pojedynczych kluczy | Do kilkunastu KB | Ustawienia dźwięku, motyw, flagi samouczka |
| Hive | Niska | Błyskawiczna (dane w RAM) | Do kilku MB na pudełko | Główny plik zapisu casualowej gry logicznej |
| Isar | Średnia | Bardzo szybka z indeksami | Od kilku do kilkudziesięciu MB | Złożone modele wymagające relacji i filtrów |
| SQLite (sqflite / drift) | Średnia do wyższej | Wysoka stabilność, ACID, WAL | Dowolny rozmiar przy dobrych indeksach | Historia gier, dokładne statystyki, wiele tabel |

Złota zasada: dobieraj technologię pod kątem najbardziej obciążonego scenariusza, a nie pierwszej uruchomionej planszy. Stan aktywnej gry w sudoku to ułamek kilobajta. Jeśli jednak po roku gracz uzbiera tysiąc rozwiązanych łamigłówek z historią ruchów i czasem reakcji na każdą komórkę, objętość danych wyraźnie wzrośnie. Wybierz narzędzie, które poradzi sobie z danymi użytkownika także po wielu miesiącach intensywnego grania.
Co warto zapisywać, a co lepiej pominąć
Najszybsza operacja na dysku to ta, której wcale nie trzeba wykonywać. Zanim zaczniesz pisać kod, precyzyjnie określ, co naprawdę musi wylądować w pamięci trwałej.
Co warto zapisywać:
- Stan bieżącej planszy. W grze sudoku będą to: identyfikator łamigłówki, cyfry początkowe (lub seed generatora), aktualne ruchy gracza, notatki ołówkiem oraz licznik ruchów. Czas gry zapisuj jako liczbę milisekund (np.
elapsedMs), a nie jako obiektDateTime. Dzięki temu stoper nie zgłupieje, gdy gracz zmieni strefę czasową albo zablokuje telefon na kilka godzin. - Ustawienia gracza. Poziom głośności muzyki i efektów, wibracje (haptyka), wybrany motyw graficzny oraz preferencje trudności.
- Statystyki i serie zwycięstw. Liczba wygranych, średnie czasy, najlepsze wyniki oraz aktualna dzienna passa wraz z datą ostatniej zaliczonej gry. Konkretna data pozwala precyzyjnie ustalić, czy seria trwa nadal. Zwykła liczba w stylu
streak = 12nic Ci nie powie, jeśli po awarii trzeba będzie zweryfikować stan konta gracza. - Flagi postępu. Oznaczenie ukończenia samouczka, odebrane nagrody czy informacja o wyświetleniu prośby o ocenę gry.
Czego nie należy zapisywać:
- Danych, które łatwo przeliczyć. Listę kandydatów (cyfr pasujących do komórki w sudoku) wyliczysz w ułamku milisekundy bezpośrednio z aktualnego stanu planszy. Zapisywanie takich wartości na dysku tylko powiększa plik i stwarza ryzyko błędów przy zmianie algorytmów podpowiedzi.
- Tymczasowego stanu interfejsu. Pozycja przewijania menu, otwarte okienka pop-up czy aktualna klatka animacji to stan widoku, a nie postęp rozgrywki. Po ponownym uruchomieniu gry interfejs powinien wystartować z czystego, logicznego miejsca.
- Zrzutów całej planszy po każdym pojedynczym dotknięciu ekranu. Zapisuj postęp w logicznych momentach: po wykonaniu serii ruchów, po wciśnięciu pauzy lub gdy aplikacja przechodzi do pracy w tle. Plansza sudoku w formacie JSON jest wprawdzie lekka, ale setki operacji zapisu na minutę niepotrzebnie obciążają procesor i pamięć flash telefonu.
- Czasu pobieranego wprost z zegara urządzenia. Gracze często przestawiają zegarek w telefonie, żeby zresetować liczniki energii lub odblokować dzienne wyzwania. Czas lokalny urządzenia stosuj wyłącznie do wyświetlania godziny w interfejsie. Wszelką logikę rozgrywki i passy opieraj na zegarach monotonicznych lub znacznikach czasu z serwera.
Poniższy przykład przedstawia strukturę stanu planszy sudoku. Wszystkie pola reprezentują wyłącznie stan pierwotny, decyzje gracza lub skumulowane liczniki. To czysty kod w Darcie, który bez przeszkód uruchomisz w DartPadzie:
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,
};
}
Wzorzec koperty zapisu: bezpieczny kontener na stan gry
Bez względu na to, czy wybierzesz Hive, SQLite czy zwykły plik JSON, nigdy nie zapisuj stanu gry bezpośrednio jako surowego obiektu. Zawsze opakuj go we wzorzec koperty (SaveEnvelope). Trzy podstawowe metadane uchronią Cię przed większością problemów produkcyjnych: numer wersji schematu, sygnatura czasowa w UTC oraz identyfikator urządzenia. Poniższy kod to czysty Dart, który możesz wkleić do DartPada i od razu przetestować:
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,
);
}
}
Zwróć uwagę na warunek ochronny w metodzie fromJson. Jeżeli plik zapisu ma wersję nowszą niż ta obsługiwana przez aktualnie zainstalowaną aplikację, loader od razu go odrzuca. Dzięki temu starsza wersja gry nie nadpisze nowszego pliku i nie zniszczy nieznanych pól. Zamiast tego możesz po prostu pokazać graczowi komunikat z prośbą o pobranie aktualizacji ze sklepu.
Wersjonowanie schematu i migracje wyłącznie w przód
Migracje danych powinny opierać się na krótkich, wyspecjalizowanych funkcjach. Każda z nich musi odpowiadać za dokładnie jeden krok wersji. Nie próbuj pisać wielkich funkcji przekształcających dowolny stary format w najnowszy. Dużo bezpieczniej jest łączyć małe migracje w łańcuch:
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(),
};
Trzy sprawdzone zasady chroniące zapisy na produkcji:
- Rozwijaj schemat addytywnie. Zamiast zmieniać nazwy istniejących pól lub je kasować, dodawaj nowe właściwości z rozsądnymi wartościami domyślnymi. Starsze wersje kodu spokojnie zignorują nieznane nowe pola, ale natychmiast wyłożą się, gdy zabraknie klucza, którego oczekują.
- Sprawdzaj migracje na prawdziwych plikach. Zapisz w testach jednostkowych autentyczne pliki JSON z każdej wydanej wcześniej wersji aplikacji. Generowanie sztucznych obiektów w kodzie testów ułatwia przeoczenie subtelnych błędów serializacji.
- Dbaj o atomowy zapis plików. Przy ręcznym zapisie do pliku najpierw zrzuć dane do pliku tymczasowego, wymuś fizyczny zapis na dysku (flush), a potem podmień plik docelowy za pomocą operacji rename. Dzięki temu nagłe wyłączenie telefonu w trakcie zapisu pozostawi na dysku albo poprzedni nienaruszony plik, albo kompletny nowy. Nigdy nie skończysz z uszkodzonym, urwanym w połowie zapisem. W bazach takich jak SQLite atomowość masz zagwarantowaną dzięki transakcjom.

Pięć pułapek technicznych, które zaskakują programistów
1. shared_preferences nie gwarantuje natychmiastowego zapisu na dysk. Dokumentacja pakietu wprost ostrzega, że dane mogą być zapisywane na dysku asynchronicznie i nie ma pewności, że zapis przetrwa nagłe ubicie procesu aplikacji. Z tego powodu nie wolno trzymać tam krytycznych danych gry. Jeśli gracz straci ustawienie jasności ekranu, nic wielkiego się nie stanie. Jeśli jednak wyparuje jego passa 200 dni w sudoku, na pewno wystawi negatywną ocenę. Na Androidzie warto przejść na nowsze API SharedPreferencesAsync, które zapisuje dane za pośrednictwem biblioteki DataStore Preferences zamiast starych plików XML.
2. Asynchroniczny zapis na Androidzie i spadki wydajności. Androidowa metoda apply() natychmiast wraca do kodu, ale fizyczny zrzut danych na nośnik odkłada w czasie. W niekorzystnych warunkach system wykonuje ten zrzut dopiero podczas kolejnego zimnego startu aplikacji, co zauważalnie wydłuża czas jej ładowania. Przy zapisie kilku flag różnica jest niezauważalna, ale przy setkach operacji w trakcie jednej sesji aplikacja zacznie zwalniać.
3. Świetne wyniki Hive w testach wynikają z pamięci podręcznej. Większość internetowych benchmarków Hive mierzy odczyty z już otwartego pudełka trzymanego w pamięci RAM. Choć tak właśnie powinno się z Hive korzystać, testy te nie mówią nic o czasie zimnego startu ani o wydajności ciągłego zapisu na nośnik flash. Pamiętaj też o kwestii utrzymania biblioteki: oryginalny pakiet przestał być aktywnie rozwijany, dlatego w nowych projektach należy używać forka hive_ce.
4. Przedłużający się rozwój Isara to realne ryzyko. Prace nad Isar 4 trwają od dłuższego czasu, a biblioteka wciąż nie ma finalnego wydania. Wybór silnika bazy danych w grze mobilnej to decyzja na lata, ponieważ gracze potrafią wracać do łamigłówek przez bardzo długi czas. Zanim zdecydujesz się na Isara, sprawdź aktywność repozytorium na GitHubie oraz otwarte zgłoszenia błędów. Warto też oddzielić warstwę bazy danych od logiki gry, by w razie potrzeby móc zmienić magazyn danych bez przepisywania całego projektu.
5. Serializacja dużego JSON-a na głównym wątku przycina animacje. Wywołanie jsonEncode dla rozbudowanego stanu gry wykonuje się na głównym wątku Fluttera (UI isolate) - tym samym, który odpowiada za płynne rysowanie klatek i obsługę dotyku. Serializowanie dużych danych na słabszych telefonach po każdym ruchu potrafi wyraźnie przyciąć grę. Ciężką serializację warto przenieść do osobnego wątku roboczego za pomocą funkcji compute() albo ograniczyć zapis wyłącznie do kluczowych momentów. Więcej o optymalnej persystencji dowiesz się z oficjalnego przewodnika Flutter cookbook.
Jak przygotować architekturę pod synchronizację w chmurze
Na początku projektu rzadko buduje się własny backend. Warto jednak od razu zaplanować strukturę danych tak, aby dodanie synchronizacji z chmurą za kilka miesięcy było prostą integracją, a nie powodem do pisania gry od nowa.
Wzorzec koperty rozwiązuje większość problemów. Poniższe nawyki pozwolą Ci bezboleśnie podpiąć synchronizację w przyszłości:
- Zawsze zachowuj
schemaVersion,deviceIdorazsavedAtUtc. Wszelkie mechanizmy rozwiązywania konfliktów opierają się na metadanych. Bez numeru wersji nie połączysz stanów po aktualizacji gry na jednym z urządzeń. Bez sygnatury czasowej nie ustalisz chronologii zdarzeń, a bez identyfikatora urządzenia nie wykryjesz, które urządzenie wygenerowało błędy. - Scalaj dane pole po polu, zamiast nadpisywać cały plik. Wyobraź sobie gracza, który rozwiązał trudną planszę sudoku offline na tablecie, a godzinę później zagrał krótką partyjkę na telefonie. Jeżeli system synchronizacji oprzesz na prostej zasadzie ‘nowszy plik zastępuje starszy’, jedno z tych osiągnięć bezpowrotnie przepadnie. Scalanie danych na poziomie konkretnych pól pozwala zachować zarówno rozwiązaną planszę, jak i postępy z telefonu.
- Pamiętaj o limitach pojedynczego zapisu w chmurze. Usługi takie jak Google Play Games Services nakładają sztywne limity na rozmiar pojedynczego slotu zapisu (często jest to maksymalnie 3 MB). To ogromna przestrzeń na same dane gry i statystyki, o ile nie zaczniesz upychać w pliku zapisu zrzutów ekranu czy nieskompresowanych logów. Lekki format zapisu sprawia, że limit nigdy nie stanie się problemem.
- Nigdy nie ufaj lokalnemu zegarowi telefonu przy ustalaniu kolejności zmian. Użytkownicy często przestawiają zegarki w telefonach. Lokalny czas (
savedAtUtc) traktuj jako informację pomocniczą do wyświetlenia w interfejsie. Przy rozstrzyganiu konfliktów w chmurze zawsze polegaj na sygnaturach czasowych nadawanych przez Twój serwer. - Synchronizacja musi chronić lokalne postępy gracza. Pierwsze logowanie do chmury nigdy nie może po cichu wyczyścić wielomiesięcznej historii zapisanej na telefonie. W razie wątpliwości lepiej połączyć dane z obu źródeł lub wprost zapytać gracza, który stan chce zachować.

Sprawdzone konfiguracje dla gry w sudoku
Dobór narzędzi zależy od skali gry i tego, ile informacji chcesz zbierać:
- Zestaw pragmatyczny (domyślny):
SharedPreferencesAsyncdo prostych opcji plushive_cedla głównego pliku ze stanem gry. To lekki, szybki zestaw, z którym testy jednostkowe działają błyskawicznie, a gra uruchamia się bez żadnych opóźnień. - Zestaw analityczny: biblioteka
driftoparta na SQLite. Znakomity wybór, gdy chcesz zapisywać historię każdej partii sudoku, tworzyć rozbudowane statystyki czasowe i pozwalać graczom na filtrowanie wyników. Relacyjna baza danych z indeksami w pełni uzasadnia swój nakład konfiguracyjny przy takich wymaganiach. - Zestaw minimalistyczny: pojedynczy plik JSON zapisywany w katalogu aplikacji za pomocą wtyczki
path_providerz atomową podmianą pliku (rename). Jeśli Twoja gra ma tylko jedno aktywne sudoku i podstawowe ustawienia, zwykły plik JSON w zupełności wystarczy. Nie ma sensu dodawać bazy danych tylko po to, by projekt wyglądał na bardziej zaawansowany.
Podsumowanie: lista kontrolna przed wypuszczeniem gry
Przed opublikowaniem gry lub wysłaniem aktualizacji do sklepu upewnij się, że Twój kod spełnia te warunki:
- Każdy zapis zawiera pola
schemaVersion,savedAtUtcorazdeviceId. - Loader odrzuca pliki nowsze niż wersja aplikacji, chroniąc graczy przed uszkodzeniem danych.
- Zapis do plików odbywa się w sposób atomowy (plik tymczasowy plus rename albo transakcja w bazie).
- Proste opcje trafiają do
shared_preferences, a postępy do magazynu o gwarantowanej trwałości. - W testach jednostkowych masz zapisane przykładowe pliki z poprzednich wersji schematu.
- Serializacja danych nie blokuje głównego wątku UI podczas rozgrywki.
- Znasz przewidywany rozmiar danych po roku intensywnego grania przez użytkownika.
Sprawnie działający zapis stanu gry to coś, czego gracze na co dzień nie zauważają, ale natychmiast zapamiętają, gdy zawiedzie. Zadbaj o wersjonowanie schematu i atomowy zapis od pierwszego dnia, a Twoje sudoku bez problemu zachowa passy i postępy graczy przez długie lata.
Warto przeczytać
Polydocu - sudoku w formie przygody
Dziewięć cyfr, wyprawa przez dżunglę, papuga Poly i brak sztucznych blokad. Zapisz się na listę oczekujących, a wyślemy Ci powiadomienie o premierze.
Jeden e-mail przy premierze, bez spamu.




