The save rules the JWorld team uses so progress survives with no login: the save format, version numbers, recovering a broken save, and moving between devices with a save code.
Most JWorld games start with no sign-up and no login. For an idle game, though, progress is everything. If a save vanishes after a few days of play, that player rarely comes back.
With no accounts we cannot park the save on a server either. So progress lives on the device, and we stack several rules to make sure that save never breaks. This dev note walks through them. The details come from the save code of Dokkaebi Tavern and Hanseong Case Files, plus our internal GAME_DEV_PLAYBOOK.md.
A save is one JSON value
A Dokkaebi Tavern save looks like this:
`` { "v": 7, "savedAt": 1763500000000, "state": { ... } } ``
vis the format version. The tavern is on 7 today.savedAtis the time of the save. It is used to work out what you earned while away.stateis the whole game state.
The rules code knows nothing about screens or storage. Two functions do the translation: serialize turns the state into text, readSave turns text back into a state. That is why the same code runs whether the storage is a browser or an app.
Reading never trusts the data
A stored save can go odd at any time. An older build may have written it, or it may have been cut short. So every value is checked on the way in.
| If the loader finds | It does this |
|---|---|
| A value that is not a number, or is negative | Replaces it with the new-game default |
| A dish or guest id it does not know | Drops it |
| The same id twice | Keeps one |
A date not shaped like YYYY-MM-DD | Treats it as empty and builds today's |
| A pass with no valid end date | Treats it as no pass |
| A save from before new dishes were added | Appends the new dish slots |
One broken field never stops the whole game. Only that field falls back to its default.
The version number does two jobs
Each time the format changes, we raise SAVE_VERSION. The tavern has gone from 1 to 7. The number does two things.
It converts old saves. Version 6, for example, added the step counter for the first minutes (intro) and total play time. A version 5 save is read as "tutorial done, experienced player", so someone who has played for a while is never walked through the tutorial again.
It stops old builds from overwriting new saves. When the loader reads a save whose v is higher than the build's own, the result is newer. The game then stops saving and shows a "this save is newer" screen. That is why version 7 was bumped: the 30-day ledger pass had just been added, and an older build in another tab, writing a save without the pass, would erase something the player paid for.
This really can happen with two browser tabs open, or an old build left in a portal cache. So on the web the game re-reads the stored version right before every write. Portal storage is slower to read, so there the check runs at most once a minute, and always when the page is hidden or closing.
A broken save is set aside, not erased
If the JSON itself is unreadable, the game has to start fresh. Overwriting the bad text would throw away any chance of recovery, so the tavern first copies it into a separate slot, jumak.save.bak.
Hanseong Case Files goes one step further. Before each write it keeps the previous good save in .bak, and reading follows a fixed order:
- Read the main save.
- If that fails, read
.bak. - If that fails too, start fresh and show a notice that the save could not be read.
Every storage call is wrapped in try/catch. In places where storage is blocked, such as private mode, the game keeps running; it just cannot remember.
When saving happens
Too few save points and closing the tab loses progress. Too many and the device slows down. Hanseong saves when you place a word, when a verdict comes in and when you open a card, and it merges several events inside one second into a single write (a debounce). It also always saves when the page is hidden (visibilitychange) and when you leave it (pagehide).
The tavern adds one detail. While the page is hidden the game is paused, so the save is stamped with the moment it stopped. Even if the tab is closed and reopened days later, time away is counted from that moment, capped at 4 hours (OFFLINE_CAP_SECONDS).
Each channel stores differently
The same game ships on the web, Google Play and Toss. An adapter decides where the save lives, and game code only calls get and set.
| Channel | Where it is stored | Why |
|---|---|---|
| Web | localStorage | Simplest. If blocked, writes are skipped quietly |
| Google Play app | Capacitor Preferences | Capacitor's docs warn the OS may clear WebView storage when disk is low, so we use the app's own data instead |
| Toss | Toss SDK storage | localStorage is off-limits there. The user key is prefixed, so two accounts on one phone keep separate records |
| ONE store | localStorage | The game is closed within 0.5 seconds, so a synchronous write is used |
App builds also hold a copy in memory, so a failed write does not end the session.
Changing devices: the save code
With no account, a new phone is a problem. Hanseong Case Files solves it with a save code. In Settings, "Export a save code" turns progress into text. On the other device, "Import a save code" takes that text and carries on. It is for moving from the web to Google Play or Toss.
The rules we kept when building the code:
- It is compressed. A first letter of
zmeans deflated,jmeans the plain fallback for a WebView that cannot compress. - A check value (HMAC) is appended. A hand-edited code fails on import.
- Purchases are not in the code. They come back from the store. Bought hint charges and ad rewards also stay on the device, so nobody can mint them by editing or replaying a code.
- The import warns first: this device's progress is replaced by the code's.
Without a server, that is about the safest way to move a save.
Summary
- A save is
{v, savedAt, state}. The rules code does not know about storage; adapters choose it. - Reading checks every value. Only the broken field goes back to its default.
- Change the format, raise the version. An old build that meets a newer save stops saving.
- A broken save goes to
.bak; Hanseong also keeps the last good save there. - Always save when the page is hidden or being left.
- To change devices, use a save code with no purchases in it.
You can try Settings → Export a save code yourself in Hanseong Case Files.
Written by the JWorld team from our game design documents and measured play data, with AI tools helping with the writing.