Saving and recovery¶
Save formats can change between development builds. Back up the whole save directory before upgrading, including hidden files. Close every game/server using that world before making the backup.
Save locations¶
- Linux:
$XDG_DATA_HOME/termcraft/saves, or~/.local/share/termcraft/saves. - macOS:
~/Library/Application Support/termcraft/saves. - Windows:
%APPDATA%\termcraft\saves.
TERMCRAFT_SAVE_DIR overrides the location. Classic survival uses the save root;
named worlds and Lantern Run use worlds/world-ID/. The default shared world
uses multiplayer/default/. Named co-op servers use their named world directory.
The saved view lives in view.json; co-op reconnect profiles live under clients/.
A world contains terrain files, player/server records, metadata and possibly a
hidden .world-checkpoint/ directory. Keep them together. A .session.lock
prevents two processes from writing the same world. Close a local game before
hosting that world.
Compatibility¶
The current build writes native checkpoint version 12, server version 5 and chunk version 3, with network protocol 23. Native loaders accept the older native formats through version 11; server loaders accept versions 1–4, and chunk loaders import versions 1–2. Placed furnace contents live in their chunks. All co-op participants need matching builds. Older executables may reject saves written by newer builds.
Saved terrain and player edits are preserved. New terrain, villages and ore layouts appear in fresh chunks. Weather, world clocks, entities and encounters resume from saved state; the world does not advance while offline. In-flight Ender Pearls and their impact effects are transient. They are not saved, so loading a checkpoint cannot teleport a different or reconnected player.
Interrupted saves¶
Autosave uses a recoverable world checkpoint. If a write is interrupted, the next checked startup rolls the world back to the last completed save. Progress since that save can be lost. A failed recovery is reported and its files are preserved; corrupt data is not silently replaced by new terrain.
After a crash, verify the previous owner has stopped. Remove only its stale
.session.lock if necessary, then reopen with the matching build. Do not delete
.world-checkpoint/ to force a load. Resolve storage-space or permission errors
and retry. Keep an independent backup; process-crash recovery does not guarantee
survival of disk or power failures.
Emergency copies¶
A fatal native-loop error attempts to write termcraft-recovery-<random> in the
system temporary directory. The terminal reports its absolute path after cleanup.
Copy it somewhere durable before temporary files are cleared.
This is a partial emergency copy, not a full-world backup. It includes the
currently loaded chunks in the current dimension, player progression, seed/recipe
and valid metadata, with RECOVERY.txt describing the limits. Unloaded terrain
and terrain in other dimensions are absent. Saved entities cannot recreate that
missing terrain. Preserve the original world and recover into a separate copy.
Recovering into a copy¶
- Close the game/server and any other save owner. Retain the complete terminal
error and the reported
termcraft-recovery-...path. Copy that temporary directory somewhere durable before the OS cleans it. - Locate the original world directory: the save root for classic play,
worlds/world-IDfor a named world, ormultiplayer/defaultfor the default shared world. Make a complete backup, then a second copy for recovery. Work only on the second copy. Native recovery is not a multiplayer backup. If the copy has.session.lock, verify its original owner is gone before removing the copy's stale lock. Leave the original and backup untouched. - Before overlaying anything, open the second copy with the matching build and quit normally, allowing its pending checkpoint to roll back. Otherwise startup could roll your newly overlaid emergency files back too. If recovery fails, preserve the copy and error; do not delete its journal to force entry.
- Read
RECOVERY.txtand inspect which dimension/chunks were captured. Overlay only the recovered chunk/progression/seed and metadata files that you intend to restore. Keep the copy's unloaded chunks and other dimensions. Do not copy leases or reconnect identities. - Open the overlaid world as a standalone copy with the matching build:
sh
TERMCRAFT_SAVE_DIR=/absolute/path/to/recovered-world ./termcraft
recovered-world must directly contain player_progression.bin, chunk files
and (for a generated world) world.json. The checked loader reads this recipe
from the root. Do not point this command at the parent worlds directory.
6. Check position, inventory/crafting/armor, nearby builds/storage, weather,
dimension travel and save/reopen. If loading reports corruption, preserve the
offending file and error; do not replace it with new terrain. Resolve the
underlying storage problem before returning to normal play.
Recovery combines files from different points in time. Inspect neighboring chunks and progression carefully; it cannot restore a whole-world transaction or missing terrain/entity history from before the last checkpoint. A successful open is not proof of consistency.