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: a game's own env.txt wins over the shared one (#557)

v0lumehifdc75d947a57
diff --git a/README.md b/README.md
index bc265fe8..ad85c9dc 100644
--- a/README.md
+++ b/README.md
@@ -127,7 +127,9 @@ options. For anything the sheet lacks, write an `env.txt` of `KEY=VALUE` lines (
wins and survives rebuilds; `<App>.app/Contents/Resources/dm/env.txt` is the app's own. A Mac app
built before the language row existed needs one rebuild to get it. On the iPhone, the same lines go
in `Documents/env.txt` (`DM_FPS_TARGET=30` caps the frame rate to save battery, `DM_OPMODE=0` picks
-handheld mode).
+handheld mode). That file applies to every game in the shared app. For a line that belongs to one game
+(a mod's `DM_ROMFS_OVERLAY`, for example), write it in `Documents/games/<title ID>/env.txt`. Where both
+files set a key, the game's file wins.
**Saves and logs.** A Mac game in a library folder keeps its saves and its log beside the app
(`log/<title ID>.log`); otherwise they are in `~/Library/Application Support/nxnative/<title ID>/` and
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 88c5e1f2..f1ecb170 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -107,7 +107,8 @@ App 会为它编译一次图形并记住。游戏数据(`romfs.img`)可以
`~/Library/Application Support/nxnative/<title ID>/env.txt` 优先,重新构建后仍在;
`<App>.app/Contents/Resources/dm/env.txt` 是 App 自带的。在加入语言选项之前构建的 Mac App 需要重新构建
一次才有该项。iPhone 上同样的行写在 `Documents/env.txt` 里(`DM_FPS_TARGET=30` 限帧省电,
-`DM_OPMODE=0` 选掌机模式)。
+`DM_OPMODE=0` 选掌机模式)。该文件对共享 App 里的每个游戏都生效。只属于某一个游戏的行(例如 mod 的
+`DM_ROMFS_OVERLAY`)写在 `Documents/games/<title ID>/env.txt` 里。两个文件设置了同一个键时,以该游戏的文件为准。
**存档和日志。** 放在游戏库文件夹里的 Mac 游戏,存档和日志在 App 旁边(`log/<title ID>.log`);否则在
`~/Library/Application Support/nxnative/<title ID>/` 和 `~/Library/Logs/nxnative/<title ID>.log`。
diff --git a/frontend-ios/README.md b/frontend-ios/README.md
index ac224696..039109e8 100644
--- a/frontend-ios/README.md
+++ b/frontend-ios/README.md
@@ -55,7 +55,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`: 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 env file keys that nothing else set, 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 |
+| `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 |
| `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/EngineLaunchPlan.swift b/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
index b2373889..b693f886 100644
--- a/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
+++ b/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
@@ -20,7 +20,10 @@ public struct EngineLaunchPlan: Equatable, Sendable {
/// The save and temp folders.
public var foldersToCreate: [URL]
- public static func make(game: LaunchableGame, appResources: URL, documents: URL, envFileText: String?,
+ /// `envFileText` is the shared `Documents/env.txt`. `gameEnvFileText` is the game's own `Documents/games/<title ID>/env.txt`
+ /// (#557), read from `game.appFolder` when it is nil. A key in the game's file wins over the shared file, and the launch
+ /// environment (the player's settings, the paths above) wins over both.
+ public static func make(game: LaunchableGame, appResources: URL, documents: URL, envFileText: String?, gameEnvFileText: String? = nil,
fileManager fm: FileManager = .default) -> EngineLaunchPlan {
let manifest = game.manifest, fw = game.frameworkURL, gdir = game.appFolder
func isDirectory(_ url: URL) -> Bool {
@@ -50,9 +53,12 @@ public struct EngineLaunchPlan: Equatable, Sendable {
for (key, value) in game.environment { env[key] = value }
var fromFile: [String] = []
- for (key, value) in parseEnvFile(envFileText ?? "") where env[key] == nil {
- env[key] = value
- fromFile.append(key)
+ let ownText = gameEnvFileText ?? fm.contents(atPath: gdir.appendingPathComponent("env.txt").path).flatMap { String(data: $0, encoding: .utf8) }
+ for text in [ownText, envFileText] {
+ for (key, value) in parseEnvFile(text ?? "") where env[key] == nil {
+ env[key] = value
+ fromFile.append(key)
+ }
}
env["DM_ENV_FILE_KEYS"] = fromFile.joined(separator: " ")
diff --git a/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift b/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift
index 022f9c78..71671aae 100644
--- a/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift
+++ b/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift
@@ -112,6 +112,36 @@ import Testing
#expect(env["DM_ENV_FILE_KEYS"] == "DM_TRACE DM_OTHER")
}
+ /// #557: a mod's `DM_ROMFS_OVERLAY` in the shared file reached every game. The game's own file stays with the game.
+ @Test func gameEnvFileWinsOverTheSharedOneAndIsReadFromTheGamesFolder() throws {
+ let rig = try Rig(environment: ["DM_LANG": "de"])
+ try FileManager.default.createDirectory(at: rig.gdir, withIntermediateDirectories: true)
+ try "# this game\nDM_ROMFS_OVERLAY=/mods/orbit\nDM_TRACE=9\nDM_LANG=fr\nDM_SAVE=/elsewhere\n".write(to: rig.gdir.appendingPathComponent("env.txt"), atomically: true, encoding: .utf8)
+ let env = rig.plan(envFile: "DM_ROMFS_OVERLAY=/mods/other\nDM_TRACE=1\nDM_OTHER=3\n").environment
+ #expect(env["DM_ROMFS_OVERLAY"] == "/mods/orbit")
+ #expect(env["DM_TRACE"] == "9")
+ #expect(env["DM_OTHER"] == "3", "the shared file still applies to what the game's file does not set")
+ #expect(env["DM_LANG"] == "de" && env["DM_SAVE"] == rig.gdir.path + "/save", "the launch environment wins over both files")
+ #expect(env["DM_ENV_FILE_KEYS"] == "DM_ROMFS_OVERLAY DM_TRACE DM_OTHER")
+ }
+
+ @Test func anotherGameDoesNotSeeTheFirstGamesEnvFile() throws {
+ let rig = try Rig()
+ try FileManager.default.createDirectory(at: rig.gdir, withIntermediateDirectories: true)
+ try "DM_ROMFS_OVERLAY=/mods/orbit\n".write(to: rig.gdir.appendingPathComponent("env.txt"), atomically: true, encoding: .utf8)
+ var other = rig.game
+ other.appFolder = rig.box.documents.appendingPathComponent("games/0100000000000000", isDirectory: true)
+ let env = EngineLaunchPlan.make(game: other, appResources: rig.box.resources, documents: rig.box.documents, envFileText: nil).environment
+ #expect(env["DM_ROMFS_OVERLAY"] == nil)
+ #expect(env["DM_ENV_FILE_KEYS"] == "")
+ }
+
+ @Test func withoutAGameEnvFileOnlyTheSharedOneApplies() throws {
+ let rig = try Rig()
+ let env = rig.plan(envFile: "DM_TRACE=1\n").environment
+ #expect(env["DM_TRACE"] == "1" && env["DM_ENV_FILE_KEYS"] == "DM_TRACE")
+ }
+
@Test func argumentsExecutableAndLocations() throws {
let rig = try Rig()
let plan = rig.plan()