Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

iOS shell: keep the game data out of the iCloud backup (#618)

v0lumehie37d0bd0b600
diff --git a/frontend-ios/README.md b/frontend-ios/README.md
index 1cc405f1..bd37d3fb 100644
--- a/frontend-ios/README.md
+++ b/frontend-ios/README.md
@@ -56,6 +56,7 @@ The caller returns changed values through `games`. The views keep no second copy
| `GameCatalogue` | Scans `Games/<title ID>/`: `game.manifest.json` (schema 1, `GameManifest`), `launcher.json` (`LauncherProfile`, `docs/launcher.schema.json`, also read from `<framework>/<manifest.launcher>`), the manifest's `.framework` folder, optional `banner.<ext>` and `icon.<ext>`. A bundle that cannot be read stays in the list as broken with a readable reason (manifest missing, damaged or of another schema, framework missing, settings list damaged, folder and title ID disagree). | `docs/launcher-c-plan.md`, Manifest and Discovery |
| `GameCatalogue` (frameworks) | In the shell app the games are the embedded frameworks: `scan(root:)` also reads every `<Name>.framework` folder (pass `Bundle.main.privateFrameworksURL`). A framework without `game.manifest.json` is skipped silently. Otherwise the entry's ID is the manifest's `title_id` (the folder name without `.framework` when the manifest cannot be read), and `directory` and `frameworkURL` are the framework folder. `launcher.json` comes from `<manifest.launcher>`, else the framework's top level, and `banner.<ext>` and `icon.<ext>` from inside the framework. A manifest whose `framework` differs from the folder name is broken (Game files damaged). Of two frameworks with one title ID the first by name is kept and the second is broken, listed under its folder name. `CatalogueEntry.frameworkURL` is a stored property set by both readers. | `docs/launcher-c-plan.md`, Manifest |
| `EngineLaunchPlan` | A pure value from a `LaunchableGame`, the app's `Resources` and `Documents` folders and the text of `Documents/env.txt` (and the game's own `Documents/games/<title ID>/env.txt`, which it reads itself and which wins over the shared one, #557): the environment the real launcher applies with `setenv` (`DM_PROFILE`, `DM_ROMFS`, `DM_SAVE`, `DM_TEMP`, `DM_NVN_SHMAP`, `DM_MSL_DIR`, `DM_PSO_BUNDLE`, `DM_AOC_DIR`, `DM_CHEATS`, `DM_FONT_DIR`, `DM_SAVE_SYNC`, `DM_LAUNCHER=0`, the player's settings, then the keys of the two env files that nothing else set, the game's file first, listed in `DM_ENV_FILE_KEYS`), the `dm_main` arguments (`dmhost`, `<framework>/dm`, the manifest's modules), the framework executable, the image marker, the log URL and the save and temp folders, which only `createFolders()` creates. `parseEnvFile(_:)` reads the `KEY=VALUE` lines. | `boot_env` in `dm/ios/Sources/main.m`, `docs/launcher-c-plan.md`, Environment at game start |
+| `BackupExclusion` | Marks the game data in `Documents/games/<title ID>/` and the single-game names in `Documents` (`romfs*`, `aoc`, `temp`) with `isExcludedFromBackup`, so the backup does not hold many GB (#618). Saves (`save*`) and small text files stay in the backup. Runs when the shell starts, so it also marks what an earlier version left, and `EngineLaunchPlan.createFolders()` marks `temp`. | `boot_env` in `dm/ios/Sources/main.m` |
| `GameStateResolver` | Broken first, then needs app update (the manifest's `chain` differs from `HostEnvironment.chain`, or `min_os` is above the running OS), then needs game data, else playable. | the plan's playable, needsData, needsFramework and broken |
| `DataLocator` | The picked location first, then `Documents/games/<title ID>/`, each accepted only with a non-empty `romfs.img` or the manifest's `romfs_marker` (also under `romfs/`). A picked folder that lost its data falls through to the app folder. | `romfs_locate` in `dm/ios/Sources/main.m`, patch 0003's layout |
| `GameSettingsStore` | One `UserDefaults` suite per game (`dev.nx2apple.shell.game.<title ID>`), keys `launcher.<VAR>` holding strings. Only a value that differs from the tested default is stored, a saved value the game no longer offers reads as the default, and Reset forgets every saved choice. `SettingsPresenter` draws sections in the list's order and hides sub-settings (`needs`). | `dm/ios/Sources/LauncherSettings.swift` |
diff --git a/frontend-ios/Sources/ShellHost/BackupExclusion.swift b/frontend-ios/Sources/ShellHost/BackupExclusion.swift
new file mode 100644
index 00000000..107c13e4
--- /dev/null
+++ b/frontend-ios/Sources/ShellHost/BackupExclusion.swift
@@ -0,0 +1,68 @@
+import Foundation
+
+/// Keeps the game files out of the iCloud and device backup (#618). `Documents` is backed up unless a file or folder is marked, and a
+/// game's data (`romfs.img`, add-on content, shader caches, scratch files) is many GB, so the backup passed 5 GB and the phone asked for
+/// more iCloud space. The game data can always be sent again from the Mac, so it does not belong in the backup.
+///
+/// The saves stay in the backup. They are small (a few MB for a game), they cannot be made again, and a player who gets a new phone
+/// from a backup wants them. Every entry of a game's folder whose name starts with `save` is left alone (`GameDeletion.isSave`, the same
+/// rule that decides what deleting a game may remove), and so are small plain files (`env.txt`, `profile.tsv`, `log.txt`, settings
+/// text). Everything else in `Documents/games/<title ID>/` is marked, and so are the old single-game names at the top of `Documents`
+/// (`romfs*`, `aoc`, `temp`, which `dm/ios/Sources/main.m` marks for the one-game app). A framework is part of the app bundle, which
+/// is never backed up, and the engine's own caches are in `Library/Caches`, which is not either, so nothing else needs a mark.
+///
+/// Marking a folder covers everything inside it, and marking is one `setResourceValues` call, so `apply` is cheap and safe to run on
+/// every start: an entry that is marked already is not written again.
+public enum BackupExclusion {
+ /// A file in a game's folder up to this size counts as a setting, not as game data, and stays in the backup.
+ public static let smallFileLimit = 1_000_000
+
+ public static func isExcluded(_ url: URL) -> Bool {
+ (try? url.resourceValues(forKeys: [.isExcludedFromBackupKey]).isExcludedFromBackup) ?? false
+ }
+
+ /// Marks one entry. Returns true when it changed (it was not marked before), false when it was marked already or could not be.
+ @discardableResult
+ public static func exclude(_ url: URL) -> Bool {
+ guard !isExcluded(url) else { return false }
+ var target = url
+ var values = URLResourceValues()
+ values.isExcludedFromBackup = true
+ return (try? target.setResourceValues(values)) != nil
+ }
+
+ /// Whether `name` in a game's folder is game data (to mark) and not a save or a small setting file.
+ static func isGameData(_ url: URL, fileManager fm: FileManager) -> Bool {
+ if GameDeletion.isSave(url.lastPathComponent) { return false }
+ let values = try? url.resourceValues(forKeys: [.isDirectoryKey, .fileSizeKey])
+ if values?.isDirectory == true { return true }
+ return (values?.fileSize ?? Int.max) > smallFileLimit
+ }
+
+ /// The entries of one game's folder that are game data.
+ public static func gameData(in folder: URL, fileManager fm: FileManager = .default) -> [URL] {
+ let urls = (try? fm.contentsOfDirectory(at: folder, includingPropertiesForKeys: nil)) ?? []
+ return urls.filter { isGameData($0, fileManager: fm) }.sorted { $0.path < $1.path }
+ }
+
+ /// The old single-game names at the top of `Documents`: a RomFS image or tree in any letter case, `aoc` and `temp`.
+ static func isLegacyTopLevelData(_ name: String) -> Bool {
+ let lower = name.lowercased()
+ return lower.hasPrefix("romfs") || lower == "aoc" || lower == "temp"
+ }
+
+ /// Marks the game data under `appDataRoot` (`Documents/games`) and the single-game names in `Documents`. Returns what was newly
+ /// marked. Does nothing for a folder that does not exist, and never touches a save.
+ @discardableResult
+ public static func apply(appDataRoot: URL, fileManager fm: FileManager = .default) -> [URL] {
+ var changed: [URL] = []
+ let games = (try? fm.contentsOfDirectory(at: appDataRoot, includingPropertiesForKeys: [.isDirectoryKey])) ?? []
+ for folder in games where (try? folder.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true {
+ for url in gameData(in: folder, fileManager: fm) where exclude(url) { changed.append(url) }
+ }
+ let documents = appDataRoot.deletingLastPathComponent()
+ for url in (try? fm.contentsOfDirectory(at: documents, includingPropertiesForKeys: nil)) ?? []
+ where isLegacyTopLevelData(url.lastPathComponent) && exclude(url) { changed.append(url) }
+ return changed
+ }
+}
diff --git a/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift b/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
index 0e78c74a..092fcf64 100644
--- a/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
+++ b/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
@@ -81,9 +81,13 @@ public struct EngineLaunchPlan: Equatable, Sendable {
foldersToCreate: [save, temp])
}
- /// Creates the save and temp folders (and their parents) when they are missing.
+ /// Creates the save and temp folders (and their parents) when they are missing. The temp folder is kept out of the backup, the
+ /// save folder stays in it (`BackupExclusion`, #618).
public func createFolders(fileManager fm: FileManager = .default) throws {
- for url in foldersToCreate { try fm.createDirectory(at: url, withIntermediateDirectories: true) }
+ for url in foldersToCreate {
+ try fm.createDirectory(at: url, withIntermediateDirectories: true)
+ if !GameDeletion.isSave(url.lastPathComponent) { BackupExclusion.exclude(url) }
+ }
}
/// `KEY=VALUE` lines in order: `#` starts a comment line, blank lines and lines without `=` or with an empty key
diff --git a/frontend-ios/Sources/ShellHost/ShellHostModel.swift b/frontend-ios/Sources/ShellHost/ShellHostModel.swift
index f8a81fe8..eca0b530 100644
--- a/frontend-ios/Sources/ShellHost/ShellHostModel.swift
+++ b/frontend-ios/Sources/ShellHost/ShellHostModel.swift
@@ -91,6 +91,9 @@ public struct ShellHostConfig: Sendable {
shellCloud = BookmarkStore(defaults: shellSettings.defaults, key: ShellSettingsStore.cloudSavesKey)
shellChoices = Self.choices(of: shellSettings)
globalPadMap = shellSettings.padMap
+ // Game files stay out of the iCloud backup (#618), also what an earlier version put there. Off the main actor, it lists folders.
+ let dataRoot = config.appDataRoot
+ Task.detached(priority: .utility) { BackupExclusion.apply(appDataRoot: dataRoot) }
reload()
defaultsObserver = NotificationCenter.default.addObserver(forName: UserDefaults.didChangeNotification, object: nil, queue: .main) { [weak self] _ in
MainActor.assumeIsolated { self?.defaultsDidChange() }
diff --git a/frontend-ios/Tests/ShellHostTests/BackupExclusionTests.swift b/frontend-ios/Tests/ShellHostTests/BackupExclusionTests.swift
new file mode 100644
index 00000000..811fd4ed
--- /dev/null
+++ b/frontend-ios/Tests/ShellHostTests/BackupExclusionTests.swift
@@ -0,0 +1,69 @@
+import Foundation
+import Testing
+@testable import ShellHost
+
+/// #618: the game files are many GB and `Documents` is in the iCloud backup, so the backup passed 5 GB. Game data is marked, saves are not.
+@MainActor @Suite struct BackupExclusionTests {
+ private func filled(_ box: Sandbox) throws -> URL {
+ let dir = try box.giveAppData()
+ try Data(count: BackupExclusion.smallFileLimit + 1).write(to: dir.appendingPathComponent("romfs.img"))
+ for file in ["aoc/0.img", "pso/cache.bin", "temp/t.bin", "save/0/file.bin", "save_device/0/file.bin", "save.work/0/file.bin", "env.txt", "log.txt"] {
+ try box.write("x", to: dir.appendingPathComponent(file))
+ }
+ return dir
+ }
+ private func excluded(_ dir: URL, _ name: String) -> Bool { BackupExclusion.isExcluded(dir.appendingPathComponent(name)) }
+
+ @Test func gameDataIsMarkedAndSavesAndSettingsAreNot() throws {
+ let box = try Sandbox()
+ let dir = try filled(box)
+ BackupExclusion.apply(appDataRoot: box.appData)
+ for name in ["romfs", "romfs.img", "aoc", "pso", "temp"] { #expect(excluded(dir, name), "\(name) is game data") }
+ for name in ["save", "save_device", "save.work", "env.txt", "log.txt"] { #expect(!excluded(dir, name), "\(name) stays in the backup") }
+ #expect(!BackupExclusion.isExcluded(box.appData), "the games folder itself is not marked, it would hide the saves")
+ }
+
+ @Test func theOldSingleGameNamesInDocumentsAreMarked() throws {
+ let box = try Sandbox()
+ let documents = box.appData.deletingLastPathComponent()
+ for name in ["romfs", "ROMFS.img", "aoc", "temp"] { try box.write("x", to: documents.appendingPathComponent(name + "/f")) }
+ try box.write("x", to: documents.appendingPathComponent("log.txt"))
+ BackupExclusion.apply(appDataRoot: box.appData)
+ for name in ["romfs", "ROMFS.img", "aoc", "temp"] { #expect(BackupExclusion.isExcluded(documents.appendingPathComponent(name)), Comment(rawValue: name)) }
+ #expect(!BackupExclusion.isExcluded(documents.appendingPathComponent("log.txt")))
+ }
+
+ /// What an earlier version put there is marked on the first start after the update, and a second run changes nothing.
+ @Test func existingDataIsMarkedOnceAndTheSecondRunChangesNothing() throws {
+ let box = try Sandbox()
+ let dir = try filled(box)
+ #expect(!excluded(dir, "romfs.img"))
+ let first = BackupExclusion.apply(appDataRoot: box.appData)
+ #expect(first.count == 5)
+ #expect(BackupExclusion.apply(appDataRoot: box.appData).isEmpty)
+ try box.write("x", to: dir.appendingPathComponent("added/new.bin"))
+ #expect(BackupExclusion.apply(appDataRoot: box.appData).map(\.lastPathComponent) == ["added"], "game data that comes later is marked too")
+ }
+
+ @Test func aMissingFolderIsNoError() {
+ let nowhere = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString + "/Documents/games")
+ #expect(BackupExclusion.apply(appDataRoot: nowhere).isEmpty)
+ }
+
+ @Test func theShellMarksTheDataWhenItStarts() async throws {
+ let box = try Sandbox()
+ let dir = try filled(box)
+ _ = ShellHostModel(config: box.config())
+ for _ in 0..<100 where !excluded(dir, "romfs.img") { try await Task.sleep(nanoseconds: 50_000_000) }
+ #expect(excluded(dir, "romfs.img") && !excluded(dir, "save"))
+ }
+
+ @Test func foldersTheLaunchCreatesKeepTempOutAndSaveIn() throws {
+ let box = try Sandbox()
+ let dir = box.appData.appendingPathComponent("0100000000000001", isDirectory: true)
+ let plan = EngineLaunchPlan(environment: [:], arguments: [], frameworkExecutable: dir, imageMarker: "", logURL: dir,
+ workingDirectory: dir, foldersToCreate: [dir.appendingPathComponent("save"), dir.appendingPathComponent("temp")])
+ try plan.createFolders()
+ #expect(excluded(dir, "temp") && !excluded(dir, "save"))
+ }
+}