mirror of
https://github.com/tangerineturtle1/NX2navi.git
synced 2026-11-21 10:09:59 -04:00
Let players export their save into one zip for a bug report and import a save someone shared, in the launcher and in the game's menu.
The launcher's home has a Saves screen: Export Save writes NX2navi-save-<date>_<time>.zip into Downloads (or a chosen folder) with a manifest, the save the game would load next and, for a bug report, the game's latest log and nx2navi.ini, never a key file; Import a Save checks a zip's manifest, game, paths and CRCs, backs the current save up into the saves folder and replaces it while the game is not running. The game's Game tab has the same exports and an import that waits in profile/save-import and becomes the save at the next start, since the running game would write its progress back over a save replaced under it. The zip code (runtime/save_zip.c) and the import at start are checked without game files by tests/save_zip_check.py and tests/save_share_check.py; the launcher side by its test suite. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -7,9 +7,14 @@ no account yet; the import makes one as the game would. Saves are committed thro
|
||||
a finished commit (ready-<n>) is newer than save/<account>: an import clears that folder, so the game loads the
|
||||
imported save.
|
||||
|
||||
<game>/saves is the player's side. Import Saves takes a save put there first (its files, or the folder that holds
|
||||
them); otherwise the player picks a folder. Before the save is replaced it is copied to saves/backup <time>, and a
|
||||
save taken from saves/ moves to saves/imported <time>, so nothing is lost and nothing is imported twice.
|
||||
<game>/saves is the player's side. Import Saves takes a save put there first (a shared save's zip, its files, or the
|
||||
folder that holds them); otherwise the player picks a zip or a folder. Before the save is replaced it is copied to
|
||||
saves/backup <time>, and a save taken from saves/ moves to saves/imported <time>, so nothing is lost and nothing is
|
||||
imported twice.
|
||||
|
||||
A shared save is one zip (export_save, import_zip; section "sharing a save" below): a player attaches it to a bug
|
||||
report, and whoever fixes it imports it to reach the same place in the game. The game's settings menu exports and
|
||||
imports the same zip; its import waits in <game>/profile/save-import for the game's next start.
|
||||
|
||||
A save folder can come from a Switch save backup (the save's files), an emulator (nested folders named by user and
|
||||
title ids, gone down while each holds only one folder), another NX2navi game folder or its profile folder (the
|
||||
@@ -19,11 +24,15 @@ A whole save is account.sav, option.sav and the folders slot_00 to slot_05, each
|
||||
folder with progress.sav at its top is one slot: it replaces that slot (the slot named by its folder, else slot_00) and
|
||||
the rest of the current save stays, as the game reads progress.sav only inside a slot folder.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shutil
|
||||
import stat
|
||||
import tempfile
|
||||
import time
|
||||
import zipfile
|
||||
import zlib
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
@@ -40,13 +49,14 @@ def _rmtree(path):
|
||||
|
||||
README = '''NX2navi saves folder
|
||||
|
||||
To import a save, put it here and select Import Saves in the NX2navi launcher (next to Game Folder):
|
||||
To import a save, put it here and select Saves, then Import a Save, in the NX2navi launcher:
|
||||
- a save someone shared: the NX2navi-save-....zip that NX2navi exported
|
||||
- the files of a Switch save backup, or the folder that holds them
|
||||
- one save slot (a folder such as slot_00): only that slot is replaced
|
||||
- an emulator's save folder for the game
|
||||
- the profile folder (or the whole game folder) of another NX2navi install
|
||||
|
||||
You can also select Import Saves and choose the folder instead.
|
||||
You can also select Import a Save and choose the zip or the folder instead.
|
||||
|
||||
Before a save is imported, the game's current save is copied here into a folder named "backup" and the date. An
|
||||
imported save moves into a folder named "imported" and the date. The game itself keeps its save in profile\\save.
|
||||
@@ -71,7 +81,11 @@ def ensure_saves_dir(game):
|
||||
d = saves_dir(game)
|
||||
d.mkdir(parents=True, exist_ok=True)
|
||||
readme = d / 'README.txt'
|
||||
if not readme.is_file():
|
||||
try:
|
||||
current = readme.read_text(encoding='utf-8')
|
||||
except (OSError, ValueError):
|
||||
current = None
|
||||
if current != README: # missing, or an older launcher's
|
||||
readme.write_text(README, encoding='utf-8', newline='\r\n')
|
||||
return d
|
||||
|
||||
@@ -139,7 +153,8 @@ def _one_slot(src):
|
||||
|
||||
|
||||
def waiting(game):
|
||||
"""(source, names to leave out) of a save put into <game>/saves, or (None, ())."""
|
||||
"""(source, names to leave out) of a save put into <game>/saves, or (None, ()). A zip there (export_save's) comes
|
||||
first, the newest one; its source is the zip file."""
|
||||
d = saves_dir(game)
|
||||
if not d.is_dir():
|
||||
return None, ()
|
||||
@@ -147,6 +162,9 @@ def waiting(game):
|
||||
entries = _entries(d, skip)
|
||||
if not entries:
|
||||
return None, ()
|
||||
zips = [e for e in entries if e.is_file() and e.suffix.lower() == '.zip']
|
||||
if zips:
|
||||
return max(zips, key=lambda e: e.stat().st_mtime), ()
|
||||
if len(entries) == 1 and entries[0].is_dir():
|
||||
return find_save(entries[0])
|
||||
return (d, tuple(sorted(skip))) if any(e.is_file() or _has_file(e) for e in entries) else (None, ())
|
||||
@@ -202,23 +220,64 @@ def game_running(game):
|
||||
return running(game)
|
||||
|
||||
|
||||
def pending_import(game):
|
||||
"""The save the game's menu took from a shared zip and left in <game>/profile/save-import for its next start
|
||||
(runtime/fs_host.c import_pending), or None."""
|
||||
p = Path(game) / 'profile' / PENDING
|
||||
return p if p.is_dir() else None
|
||||
|
||||
|
||||
def import_save(game, folder=None, log=print):
|
||||
"""Make the save in folder (None: the one waiting in <game>/saves) the game's save. Returns {'files', 'source',
|
||||
'backup'}; backup is the folder the replaced save went to, or None when there was none."""
|
||||
"""Make the save in folder (None: the one waiting in <game>/saves) the game's save. folder may also be a zip of
|
||||
export_save (import_zip). Returns {'files', 'source', 'backup', 'slot'}; backup is the folder the replaced save
|
||||
went to, or None when there was none."""
|
||||
game = Path(game)
|
||||
if folder is not None and Path(folder).resolve() == saves_dir(game).resolve():
|
||||
folder = None # the saves folder itself, picked in the dialog: what waits in it, as the button takes it
|
||||
if folder is not None and Path(folder).is_file():
|
||||
return import_zip(game, folder, log=log)
|
||||
from_saves = folder is None
|
||||
src, skip = waiting(game) if from_saves else find_save(folder)
|
||||
if src is None:
|
||||
raise SaveError('the saves folder holds no save' if from_saves else f'{folder} holds no save files')
|
||||
stamp = time.strftime('%Y-%m-%d %H.%M.%S')
|
||||
if Path(src).is_file(): # a shared save's zip put into saves/: it moves out once imported, as a folder does
|
||||
r = import_zip(game, src, log=log, stamp=stamp)
|
||||
_put_away(game, [Path(src).name], stamp)
|
||||
return r
|
||||
prof = (game / 'profile').resolve()
|
||||
if Path(src).resolve() == prof or prof in Path(src).resolve().parents:
|
||||
raise SaveError('that is the game\'s own save')
|
||||
files = _files(src, set(skip))
|
||||
slot = _one_slot(src)
|
||||
account, backup = _replace(game, src, files, slot, stamp, log)
|
||||
if from_saves: # what was put into saves/ moves out whole, so the next import does not take any of it again
|
||||
saves = saves_dir(game)
|
||||
if Path(src) == saves:
|
||||
top = sorted({rel.parts[0] for rel in files})
|
||||
else: # the save sits in a folder that was put there (a game folder, an emulator's id folders)
|
||||
top = [Path(src).relative_to(saves).parts[0]]
|
||||
_put_away(game, top, stamp)
|
||||
log(f'saves: imported {len(files)} files from {src} into {account / slot if slot else account}' +
|
||||
(f'; the old save is in {backup}' if backup else ''))
|
||||
return {'files': len(files), 'source': Path(src), 'backup': backup, 'slot': slot}
|
||||
|
||||
|
||||
def _put_away(game, names, stamp):
|
||||
"""Move names (in <game>/saves) into saves/imported <stamp>."""
|
||||
saves = saves_dir(game)
|
||||
done = _fresh(saves, f'imported {stamp}')
|
||||
done.mkdir()
|
||||
for name in names:
|
||||
shutil.move(str(saves / name), str(done / name))
|
||||
|
||||
|
||||
def _replace(game, src, files, slot, stamp, log):
|
||||
"""Copy the files of src (relative paths) into the game's save: the whole save, or with slot only that slot folder
|
||||
and the rest of the current save kept. The save the game would load now goes to saves/backup <stamp> first.
|
||||
Returns (account folder, backup folder or None)."""
|
||||
account = account_dir(game)
|
||||
saves = ensure_saves_dir(game)
|
||||
stamp = time.strftime('%Y-%m-%d %H.%M.%S')
|
||||
backup = None
|
||||
current = _newest(game, account)
|
||||
if current is not None and _has_file(current):
|
||||
@@ -228,7 +287,6 @@ def import_save(game, folder=None, log=print):
|
||||
tx.mkdir(parents=True, exist_ok=True)
|
||||
stage = tx / 'import'
|
||||
shutil.rmtree(stage, ignore_errors=True)
|
||||
slot = _one_slot(src)
|
||||
if slot and current is not None: # the rest of the save stays; a slot's files left at the top by mistake do not
|
||||
shutil.copytree(current, stage, ignore=lambda d, _names: SLOT_FILES if Path(d) == Path(current) else ())
|
||||
_rmtree(stage / slot)
|
||||
@@ -279,15 +337,188 @@ def import_save(game, folder=None, log=print):
|
||||
raise
|
||||
if gone is not None:
|
||||
_rmtree(gone)
|
||||
if from_saves: # what was put into saves/ moves out whole, so the next import does not take any of it again
|
||||
done = _fresh(saves, f'imported {stamp}')
|
||||
done.mkdir()
|
||||
if Path(src) == saves:
|
||||
top = sorted({rel.parts[0] for rel in files})
|
||||
else: # the save sits in a folder that was put there (a game folder, an emulator's id folders)
|
||||
top = [Path(src).relative_to(saves).parts[0]]
|
||||
for name in top:
|
||||
shutil.move(str(saves / name), str(done / name))
|
||||
log(f'saves: imported {len(files)} files from {src} into {account / slot if slot else account}' +
|
||||
# A save the game's menu took for its next start would replace this one then: this import is the newer choice.
|
||||
for name in (PENDING, PENDING + '.part'):
|
||||
if (game / 'profile' / name).exists():
|
||||
log(f'saves: the save import the game\'s menu left for its next start ({name}) is dropped; '
|
||||
'this import replaces it')
|
||||
_rmtree(game / 'profile' / name)
|
||||
return account, backup
|
||||
|
||||
|
||||
# ---- sharing a save: one zip with the save and a manifest (export_save, import_zip)
|
||||
#
|
||||
# NX2navi-save-<date>_<time>[-bug-report].zip:
|
||||
# manifest.json FORMAT, FORMAT_VERSION, the game's title id and version, the NX2navi version, the export time
|
||||
# save/... the save's files as the game keeps them (account.sav, option.sav, slot_00/progress.sav, ...)
|
||||
# bug-report/... with bug_report: the game's latest log and nx2navi.ini; an import leaves them out
|
||||
# The game's own menu writes and reads the same zip (runtime/save_share.c), with the same manifest keys.
|
||||
|
||||
FORMAT, FORMAT_VERSION = 'nx2navi-save', 1
|
||||
MANIFEST, SAVE_DIR, REPORT_DIR = 'manifest.json', 'save/', 'bug-report/'
|
||||
GAME, GAME_VERSION = 'The Legend of Zelda: Ocarina of Time', '1.1.1'
|
||||
PENDING = 'save-import' # profile/save-import: what the game's menu took from a zip, imported at the game's next start
|
||||
ZIP_MAX_FILES, ZIP_MAX_BYTES = 4000, 256 << 20
|
||||
SAVE_FILE = re.compile(r'^(account\.sav|option\.sav|slot_\d\d/progress\.sav)$') # what makes a folder this game's save
|
||||
|
||||
|
||||
def _title_hex():
|
||||
from .gamefiles import TITLE_ID
|
||||
return f'{TITLE_ID:016x}'
|
||||
|
||||
|
||||
def _key_file(rel):
|
||||
"""Key files never go into a zip, wherever a stray one was copied (a save folder taken from another tool)."""
|
||||
n = Path(rel).name.lower()
|
||||
return n.endswith('.keys') or n.endswith('.keys.txt')
|
||||
|
||||
|
||||
def default_export_dir():
|
||||
"""The player's Downloads folder (where Windows keeps it), else the Desktop, else the home folder."""
|
||||
from .winsys import known_folder
|
||||
for p in (known_folder('downloads'), Path.home() / 'Downloads', known_folder('desktop'), Path.home() / 'Desktop'):
|
||||
if p and Path(p).is_dir():
|
||||
return Path(p)
|
||||
return Path.home()
|
||||
|
||||
|
||||
def _fresh_file(folder, stem, suffix):
|
||||
"""folder/<stem><suffix>, or "<stem> (2)<suffix>" and so on when that is taken."""
|
||||
p, n = folder / f'{stem}{suffix}', 2
|
||||
while p.exists():
|
||||
p, n = folder / f'{stem} ({n}){suffix}', n + 1
|
||||
return p
|
||||
|
||||
|
||||
def export_save(game, dest=None, bug_report=False, version='', log=print):
|
||||
"""Write the save the game would load now into one zip in dest (default_export_dir when None), for a bug report
|
||||
or another player. bug_report adds the game's latest log and nx2navi.ini. Never a key file. Returns {'path',
|
||||
'files', 'extras'} (extras: the names of the bug report files that were there)."""
|
||||
game = Path(game)
|
||||
if not (game / 'profile' / 'account.uid').is_file():
|
||||
raise SaveError('the game has no save yet: play until it saves, then export')
|
||||
account = account_dir(game)
|
||||
dest = Path(dest) if dest else default_export_dir()
|
||||
dest.mkdir(parents=True, exist_ok=True)
|
||||
stem = time.strftime('NX2navi-save-%Y-%m-%d_%H-%M-%S') + ('-bug-report' if bug_report else '')
|
||||
extras = [f for f in (game / 'logs' / 'nx2navi.log', game / 'nx2navi.ini') if bug_report and f.is_file()]
|
||||
for attempt in range(3):
|
||||
# a running game may swap a commit in while its files are read (runtime/fs_host.c swap_in): read again
|
||||
current = _newest(game, account)
|
||||
if current is None or not _has_file(current):
|
||||
raise SaveError('the game has no save yet: play until it saves, then export')
|
||||
files = [rel for rel in _files(current, set()) if not _key_file(rel)]
|
||||
out = _fresh_file(dest, stem, '.zip')
|
||||
tmp = out.with_name(out.name + '.part')
|
||||
manifest = {'format': FORMAT, 'format_version': FORMAT_VERSION, 'game': GAME, 'title_id': _title_hex(),
|
||||
'game_version': GAME_VERSION, 'nx2navi': version,
|
||||
'exported': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()), 'exported_by': 'launcher',
|
||||
'files': len(files), 'bug_report': bool(bug_report)}
|
||||
try:
|
||||
with zipfile.ZipFile(tmp, 'w', zipfile.ZIP_DEFLATED) as z:
|
||||
z.writestr(MANIFEST, json.dumps(manifest, indent=1) + '\n')
|
||||
for rel in files:
|
||||
z.write(current / rel, SAVE_DIR + rel.as_posix())
|
||||
for f in extras:
|
||||
z.write(f, REPORT_DIR + f.name)
|
||||
os.replace(tmp, out)
|
||||
except FileNotFoundError:
|
||||
tmp.unlink(missing_ok=True)
|
||||
if attempt == 2:
|
||||
raise
|
||||
time.sleep(0.2)
|
||||
continue
|
||||
except BaseException:
|
||||
tmp.unlink(missing_ok=True)
|
||||
raise
|
||||
log(f'saves: exported {len(files)} files from {current} to {out}' +
|
||||
(f' with {", ".join(f.name for f in extras)}' if extras else ''))
|
||||
return {'path': out, 'files': len(files), 'extras': [f.name for f in extras]}
|
||||
|
||||
|
||||
def _member_path(name):
|
||||
"""The relative path of a zip member below save/, or SaveError when it could land outside the save."""
|
||||
parts = name.split('/')
|
||||
if '\\' in name or name.startswith('/') or any(p in ('', '.', '..') for p in parts) or ':' in name:
|
||||
raise SaveError(f'it holds a file outside the save ({SAVE_DIR}{name})')
|
||||
return Path(*parts)
|
||||
|
||||
|
||||
def check_manifest(m):
|
||||
"""SaveError unless m is the manifest of an NX2navi save of this game that this version can read."""
|
||||
if not isinstance(m, dict) or m.get('format') != FORMAT:
|
||||
raise SaveError(f'its {MANIFEST} is not an NX2navi save manifest')
|
||||
v = m.get('format_version')
|
||||
if type(v) is not int or v < 1:
|
||||
raise SaveError(f'its {MANIFEST} has no format version')
|
||||
if v > FORMAT_VERSION:
|
||||
raise SaveError(f'it was made by a newer NX2navi ({m.get("nx2navi") or "format " + str(v)}): update NX2navi '
|
||||
'first')
|
||||
if str(m.get('title_id', '')).lower() != _title_hex():
|
||||
raise SaveError(f'it is a save of another game ({m.get("game") or m.get("title_id") or "not named"})')
|
||||
|
||||
|
||||
def read_zip(path):
|
||||
"""The manifest of a zip of export_save and its save files as [(ZipInfo, relative Path)], checked: the manifest
|
||||
(check_manifest), every path inside the save, no links, at most ZIP_MAX_FILES files and ZIP_MAX_BYTES, and among
|
||||
them the files of this game's save (SAVE_FILE). SaveError otherwise."""
|
||||
name = Path(path).name
|
||||
try:
|
||||
z = zipfile.ZipFile(path)
|
||||
except (zipfile.BadZipFile, OSError) as e:
|
||||
raise SaveError(f'{name} cannot be read as a zip file ({e})') from None
|
||||
with z:
|
||||
try:
|
||||
info = z.getinfo(MANIFEST)
|
||||
except KeyError:
|
||||
raise SaveError(f'{name} is not a save exported by NX2navi (it has no {MANIFEST}); to import a save '
|
||||
'folder, unpack the zip and choose the folder') from None
|
||||
try:
|
||||
if info.file_size > 1 << 16:
|
||||
raise ValueError('too large')
|
||||
m = json.loads(z.read(info).decode('utf-8'))
|
||||
except (ValueError, zipfile.BadZipFile, OSError, EOFError, zlib.error) as e:
|
||||
raise SaveError(f'the {MANIFEST} of {name} cannot be read ({e})') from None
|
||||
check_manifest(m)
|
||||
members, total = [], 0
|
||||
for info in z.infolist():
|
||||
if not info.filename.startswith(SAVE_DIR) or info.is_dir():
|
||||
continue # the manifest, bug report files
|
||||
rel = _member_path(info.filename[len(SAVE_DIR):])
|
||||
if (info.external_attr >> 16) & 0o170000 == 0o120000:
|
||||
raise SaveError(f'it holds a link ({info.filename})')
|
||||
if _key_file(rel):
|
||||
continue
|
||||
total += info.file_size
|
||||
members.append((info, rel))
|
||||
if len(members) > ZIP_MAX_FILES or total > ZIP_MAX_BYTES:
|
||||
raise SaveError(f'it holds more than a save ({len(members)} files, {total / 1e6:.0f} MB so far)')
|
||||
if not any(SAVE_FILE.match(rel.as_posix()) for _, rel in members):
|
||||
raise SaveError(f'it holds no save of {GAME}' if members else 'it holds no save files')
|
||||
return m, members
|
||||
|
||||
|
||||
def import_zip(game, path, log=print, stamp=None):
|
||||
"""Make the save in a zip of export_save the game's save (a whole save: every slot), backed up first as
|
||||
import_save does. Returns import_save's dict with the zip's manifest under 'manifest'."""
|
||||
game = Path(game)
|
||||
m, members = read_zip(path)
|
||||
stage = Path(tempfile.mkdtemp(prefix='nx2navi-save-'))
|
||||
try:
|
||||
try:
|
||||
with zipfile.ZipFile(path) as z:
|
||||
for info, rel in members:
|
||||
out = stage / rel
|
||||
out.parent.mkdir(parents=True, exist_ok=True)
|
||||
with z.open(info) as f, open(out, 'wb') as g: # the CRC is checked as the member is read
|
||||
shutil.copyfileobj(f, g)
|
||||
except (zipfile.BadZipFile, EOFError, zlib.error) as e:
|
||||
raise SaveError(f'{Path(path).name} is damaged ({e})') from None
|
||||
files = [rel for _, rel in members]
|
||||
account, backup = _replace(game, stage, files, None, stamp or time.strftime('%Y-%m-%d %H.%M.%S'), log)
|
||||
finally:
|
||||
_rmtree(stage)
|
||||
log(f'saves: imported {len(files)} files from {path} (exported {m.get("exported", "?")} by NX2navi '
|
||||
f'{m.get("nx2navi") or "?"}, game {m.get("game_version", "?")}) into {account}' +
|
||||
(f'; the old save is in {backup}' if backup else ''))
|
||||
return {'files': len(files), 'source': Path(src), 'backup': backup, 'slot': slot}
|
||||
return {'files': len(files), 'source': Path(path), 'backup': backup, 'slot': None, 'manifest': m}
|
||||
|
||||
Reference in New Issue
Block a user