Where your game progress lives

Game progress is local to the device on which you played. nxnative Easy on the Mac prepares the game; it does not receive the iPhone's progress automatically. There is no active cloud synchronization yet.

Mac

The default location for each game is:

~/Library/Application Support/nxnative/<TITLE ID>/
  save/                 committed account/game progress
  save_device/          separate device-wide progress, for games that use it
  temp/                 scratch files, not progress

For Metroid Dread, <TITLE ID> is 010093801237C000. In Finder choose Go → Go to Folder… and paste:

~/Library/Application Support/nxnative/010093801237C000/

The .app contains the engine and game data. Saves are outside it, so moving the app or preparing a new version does not move or replace these save folders. The Mac launcher chooses this directory by Title ID, not the .app filename. Advanced DM_SAVE environment overrides can change the default location.

iPhone and iPad

Each installed game has its own app container. The default paths inside it are:

Documents/
  save/                 committed account/game progress
  save_device/          present only when the game uses a separate device save
  romfs/                game content for a lightweight IPA; NOT your progress
  temp/                 scratch files; NOT your progress
  log.txt               diagnostics; NOT your progress

The container has an iOS-managed UUID; do not look for a fixed Mac filesystem path. To inspect the shared Documents folder, connect and unlock the device, trust your Mac, then use Finder → your iPhone/iPad → Files → the game. Finder shows the contents of Documents directly. Depending on iOS settings, the game may also appear under Files → On My iPhone/iPad.

An iPad and an iPhone have independent copies. Playing on one does not update the other. Signature expiry stops the app from launching but is not an instruction to remove its data: renew the same app rather than deleting it.

Updating without losing progress

Mac: close the game, build/open the new complete .app with the same Title ID. The existing save and save_device stay in Application Support.
iPhone/iPad: keep the same Apple signing account, team and effective bundle identifier. Install over the existing app. For changed game content, replace only romfs. Keep save and save_device. Do not uninstall the old app.
Switching the signing account or effective identifier can create a different app/container. A tool must not pretend that this preserves the original save. The integrated installer refuses identity changes it cannot preserve.

The preparation records nxnative-ios.json / nxnative-mac.json in the game folder are build metadata, not backups of your progress. An IPA is not a backup of the installed game's Documents. A launcher update is not a game-save backup.

Folders may not exist until the game has first run and saved. These are the game's own on-disk saves, not an emulator save state or unsaved RAM. Renewing a signature does not save an open game for you.

Manual copies and backups

First use the game's own Save option and close the game completely. Keep both committed folders, if both exist, as one dated backup. For example, store it outside the repository under your own game folder:

<your-game-folder>/backups/iPad/2026-10-27/save/
<your-game-folder>/backups/iPad/2026-10-27/save_device/

A missing save_device is normal for games that do not use it. Do not replace a real destination folder with an empty one. Keep the original backup and the current destination before trying a restore. Matching game/Title ID, version, DLC and account data matter; interchange between every game build or another emulator is not guaranteed.

Manual file copies are a way to retain the files, not a certified portable backup for every game. The engine can represent case-sensitive names with .dm-case-* physical aliases and an org.d2rmobile.guest-name extended attribute. A tool or archive format that drops that metadata can break those logical names. APFS-aware copies on a Mac should preserve extended attributes; do not assume Finder/AFC, Windows ZIP tools or a cloud-drive round trip preserves all of them. A future native export/import must explicitly carry the known alias metadata and validate restoration. We do not advertise the current API prototype as that exporter.

Do not back up live transaction directories such as save.work, save.new or their save_device counterparts. The engine commits each save root separately; copying during gameplay can mix two generations. romfs and console keys are not required to transfer progress and should not go into a future save service.

Touch-control profiles are separate

The four named control profiles are app preferences, keyed by DmPadProfiles.v2.<Title ID>, with separate 2D/3D layouts. They are not files in save. On iPhone/iPad they live in the app's preferences rather than shared Documents. Updating the same app keeps them; copying only save does not copy them to another device. Profile cloud sync/export is not implemented.

Future cloud sync

The API prototype has authenticated immutable snapshots, revision checks and revocable sharing. Native export/login/restore is not wired to the game. A safe implementation needs a stopped game, both committed roots, metadata-preserving packages, a local recovery backup and a durable restore journal. This is separate from Apple-ID signing and signature renewal.

Future portable server

No cloud host is selected. The API foundation is provider-independent: Python, HTTP, configurable OIDC identity and SQLite. Its consistent database backup can move snapshot history and ownership to another server. Configuration, backup and relocation. This does not activate in-game sync: native login and safe device snapshot/import flows are still pending.

Export from a trusted iPhone/iPad (1.11)

In Devices, choose Export saves for a recognized game, save and close it from the app switcher, confirm and select a new ZIP. Apple-account login is not required for this read on an already paired/trusted device. Show save ZIP reveals the result for manual sharing.

A separate read-only AFC capability exports only committed Documents/save and optional Documents/save_device. It excludes game content, working transactions, preferences and credentials. Inventories/sizes and a second SHA-256 read must remain stable before a private ZIP is atomically published without overwriting a backup. The package contains the same folder names plus nxnative-save-export.json with game identity/version, hashes and source times. There is no device write or restore operation in this module.

Observed running games stop export. If process inventory is unavailable, manual export requires the player's explicit closed-game acknowledgement. Symlinks, special files and .dm-case-* aliases are refused because AFC cannot preserve the engine's case-alias xattr; use a complete device backup for those cases. Limits are 512 MB and 8192 entries. A forced termination may leave a private partial temporary file, never a falsely successful final ZIP.

Manual sharing/restoration still needs matching game/version/format and a backup of the recipient's original files. Control presets are separate. This package is not yet connected to the provider-independent cloud API or its nxsave schema. There is no automatic import or universal emulator conversion claim.

7.5 KiB Raw Blame History