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 mods folder sets DM_ROMFS_OVERLAY for that game only (#557)

v0lumehi073d919b8ec3
diff --git a/README.de.md b/README.de.md
index ab8f4ddd..ec2c4c05 100644
--- a/README.de.md
+++ b/README.de.md
@@ -138,6 +138,11 @@ dieselben Zeilen in `Documents/env.txt` (`DM_FPS_TARGET=30` begrenzt die Bildrat
wählt den Handheld-Modus). Diese Datei gilt für jedes Spiel in der gemeinsamen App. Für eine Zeile, die zu einem
einzelnen Spiel gehört (zum Beispiel das `DM_ROMFS_OVERLAY` einer Mod), schreibe sie in
`Documents/games/<title ID>/env.txt`. Setzen beide Dateien denselben Schlüssel, gewinnt die Datei des Spiels.
+Eine Mod geht einfacher: Lege ihren Ordner in `Documents/games/<title ID>/mods/<Modname>/` ab (die RomFS-Dateien in
+einem Ordner `romfs/` darin oder im Ordner selbst). Die Shell setzt dann `DM_ROMFS_OVERLAY` nur für dieses Spiel.
+Bei mehreren Mods gewinnt die nach Namen erste, wo sie dieselbe Datei ersetzen. Ist derselbe Schlüssel mehrfach
+gesetzt, gilt diese Reihenfolge: die eigenen Einstellungen der Shell, die `env.txt` des Spiels, der Ordner `mods/`
+des Spiels, die gemeinsame `Documents/env.txt`.
**Spielstände und Logs.** Ein Mac-Spiel in einem Bibliotheksordner legt seine Spielstände und sein Log neben
der App ab (`log/<title ID>.log`). Sonst liegen sie in `~/Library/Application Support/nxnative/<title ID>/` und
diff --git a/README.fr.md b/README.fr.md
index 5b4c4a19..2b079097 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -134,6 +134,11 @@ l’iPhone, les mêmes lignes vont dans `Documents/env.txt` (`DM_FPS_TARGET=30`
économiser la batterie, `DM_OPMODE=0` choisit le mode portable). Ce fichier s’applique à tous les jeux de l’app
partagée. Pour une ligne qui concerne un seul jeu (le `DM_ROMFS_OVERLAY` d’un mod, par exemple), écrivez-la dans
`Documents/games/<title ID>/env.txt`. Quand les deux fichiers définissent une même clé, celui du jeu l’emporte.
+Un mod est plus simple : placez son dossier dans `Documents/games/<title ID>/mods/<nom du mod>/` (les fichiers RomFS
+dans un dossier `romfs/` à l’intérieur, ou dans le dossier lui-même). La coque définit alors `DM_ROMFS_OVERLAY`
+pour ce jeu seulement. Avec plusieurs mods, celui qui vient en premier par le nom l’emporte quand ils remplacent le
+même fichier. Quand une même clé est définie plusieurs fois, l’ordre est : les réglages propres de la coque, le
+`env.txt` du jeu, le dossier `mods/` du jeu, le `Documents/env.txt` partagé.
**Sauvegardes et journaux.** Un jeu Mac placé dans un dossier de bibliothèque garde ses sauvegardes et son journal
à côté de l’app (`log/<title ID>.log`). Sinon, ils se trouvent dans `~/Library/Application Support/nxnative/<title ID>/`
diff --git a/README.md b/README.md
index f82b24da..495f9018 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,11 @@ in `Documents/env.txt` (`DM_FPS_TARGET=30` caps the frame rate to save battery,
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.
+A mod is easier: put its folder in `Documents/games/<title ID>/mods/<mod name>/` (the RomFS files in a `romfs/`
+folder inside it, or in the folder itself). The shell then sets `DM_ROMFS_OVERLAY` for that game only. If there
+are several mods, the one first by name wins where they replace the same file. Where the same key is set twice,
+the order is: the shell's own settings, the game's `env.txt`, the game's `mods/` folder, the shared
+`Documents/env.txt`.
**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.sv.md b/README.sv.md
index 402c75b4..968389be 100644
--- a/README.sv.md
+++ b/README.sv.md
@@ -134,6 +134,10 @@ språkraden fanns behöver ett ombygge för att få den. På iPhone läggs samma
Den filen gäller alla spel i den delade appen. För en rad som hör till ett enda spel (till exempel en
mods `DM_ROMFS_OVERLAY`), skriv den i `Documents/games/<title ID>/env.txt`. Där båda filerna sätter samma
nyckel gäller spelets fil.
+En mod är enklare: lägg dess mapp i `Documents/games/<title ID>/mods/<modnamn>/` (RomFS-filerna i en mapp `romfs/`
+i den, eller i mappen själv). Skalet sätter då `DM_ROMFS_OVERLAY` bara för det spelet. Med flera mods gäller den
+som kommer först efter namn där de ersätter samma fil. Är samma nyckel satt flera gånger är ordningen: skalets egna
+inställningar, spelets `env.txt`, spelets mapp `mods/`, den delade `Documents/env.txt`.
**Sparfiler och loggar.** Ett Mac-spel i en biblioteksmapp har sina sparfiler och sin logg bredvid appen
(`log/<title ID>.log`). Annars ligger de i `~/Library/Application Support/nxnative/<title ID>/` och
diff --git a/README.zh-CN.md b/README.zh-CN.md
index cd446eec..25a9af46 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -113,6 +113,10 @@ App 会为它编译一次图形并记住。游戏数据(`romfs.img`)可以
一次才有该项。iPhone 上同样的行写在 `Documents/env.txt` 里(`DM_FPS_TARGET=30` 限帧省电,
`DM_OPMODE=0` 选掌机模式)。该文件对共享 App 里的每个游戏都生效。只属于某一个游戏的行(例如 mod 的
`DM_ROMFS_OVERLAY`)写在 `Documents/games/<title ID>/env.txt` 里。两个文件设置了同一个键时,以该游戏的文件为准。
+Mod 更简单:把它的文件夹放进 `Documents/games/<title ID>/mods/<mod 名>/`(RomFS 文件放在其中的 `romfs/`
+文件夹里,或直接放在该文件夹里)。之后 Shell 只为这个游戏设置 `DM_ROMFS_OVERLAY`。有多个 mod 时,替换同一文件的
+情况下按名称排在前面的生效。同一个键被多处设置时的优先顺序:Shell 自己的设置、该游戏的 `env.txt`、该游戏的
+`mods/` 文件夹、共享的 `Documents/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 f434d0f0..ba2a04a6 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` (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 |
+| `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`, with `DM_ROMFS_OVERLAY` from the game's `Documents/games/<title ID>/mods/` folder (`GameMods`, the Mac launcher's mod layout, only when a usable mod is there) between the game's file and the shared one), 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 b693f886..851404bd 100644
--- a/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
+++ b/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift
@@ -22,7 +22,9 @@ public struct EngineLaunchPlan: Equatable, Sendable {
/// `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.
+ /// environment (the player's settings, the paths above) wins over both. The game's own `mods/` folder sets
+ /// `DM_ROMFS_OVERLAY` (`GameMods`) when the game's env file does not, and it wins over the shared file. The order is: launch
+ /// environment, game env.txt, game mods folder, shared env.txt.
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
@@ -54,12 +56,18 @@ public struct EngineLaunchPlan: Equatable, Sendable {
var fromFile: [String] = []
let ownText = gameEnvFileText ?? fm.contents(atPath: gdir.appendingPathComponent("env.txt").path).flatMap { String(data: $0, encoding: .utf8) }
- for text in [ownText, envFileText] {
+ func apply(_ text: String?) {
for (key, value) in parseEnvFile(text ?? "") where env[key] == nil {
env[key] = value
fromFile.append(key)
}
}
+ apply(ownText)
+ if env["DM_ROMFS_OVERLAY"] == nil,
+ let overlay = GameMods.overlay(in: gdir.appendingPathComponent("mods", isDirectory: true), titleID: game.titleID, fm) {
+ env["DM_ROMFS_OVERLAY"] = overlay
+ }
+ apply(envFileText)
env["DM_ENV_FILE_KEYS"] = fromFile.joined(separator: " ")
return EngineLaunchPlan(
diff --git a/frontend-ios/Sources/ShellHost/GameMods.swift b/frontend-ios/Sources/ShellHost/GameMods.swift
new file mode 100644
index 00000000..4e0dc528
--- /dev/null
+++ b/frontend-ios/Sources/ShellHost/GameMods.swift
@@ -0,0 +1,32 @@
+import Foundation
+
+/// A game's mods (#557): folders in `Documents/games/<title ID>/mods/`, each holding RomFS files that replace the game's own
+/// (`DM_ROMFS_OVERLAY`, `hle_fs.c`). The layout is the Mac launcher's `GameMod` (`mods/<title ID>/<mod>`): the files are in
+/// `<mod>/romfs`, in an Atmosphere layout (`<mod>/atmosphere/contents/<title ID>/romfs`, `<mod>/contents/<title ID>/romfs`)
+/// or in the folder itself. A mod with only `exefs/` changes the game's code, which the rewriter does not take, so it is
+/// skipped. A name that starts with a dot is skipped too. The folder belongs to one game, so a mod never reaches another one.
+public enum GameMods {
+ /// The RomFS folder of each usable mod, in name order (Finder order).
+ public static func romfsFolders(in mods: URL, titleID: String, _ fm: FileManager = .default) -> [String] {
+ let names = ((try? fm.contentsOfDirectory(atPath: mods.path)) ?? []).filter { !$0.hasPrefix(".") }.sorted {
+ $0.localizedStandardCompare($1) == .orderedAscending
+ }
+ return names.compactMap { name in
+ var dir: ObjCBool = false
+ let mod = mods.appendingPathComponent(name)
+ guard fm.fileExists(atPath: mod.path, isDirectory: &dir), dir.boolValue else { return nil }
+ let candidates = ["romfs", "atmosphere/contents/\(titleID)/romfs", "contents/\(titleID)/romfs"].map { mod.appendingPathComponent($0).path }
+ if let found = candidates.first(where: { fm.fileExists(atPath: $0) }) { return found }
+ let top = ((try? fm.contentsOfDirectory(atPath: mod.path)) ?? []).filter { !$0.hasPrefix(".") }
+ let codeOnly = !top.isEmpty && top.allSatisfy { ["exefs", "atmosphere", "contents"].contains($0.lowercased()) }
+ return codeOnly || top.isEmpty ? nil : mod.path
+ }
+ }
+
+ /// The `DM_ROMFS_OVERLAY` value for the usable mods, or nil when the folder is missing or holds none. Where two mods
+ /// replace one file, the one first in name order wins (the host looks in the folders in order), as on the Mac.
+ public static func overlay(in mods: URL, titleID: String, _ fm: FileManager = .default) -> String? {
+ let folders = romfsFolders(in: mods, titleID: titleID, fm)
+ return folders.isEmpty ? nil : folders.joined(separator: ":")
+ }
+}
diff --git a/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift b/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift
index 71671aae..1123b812 100644
--- a/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift
+++ b/frontend-ios/Tests/ShellHostTests/EngineLaunchPlanTests.swift
@@ -142,6 +142,56 @@ import Testing
#expect(env["DM_TRACE"] == "1" && env["DM_ENV_FILE_KEYS"] == "DM_TRACE")
}
+ // MARK: the game's mods folder (#557)
+
+ @Test func modsFolderSetsTheOverlayOnlyWhenItExistsAndHoldsAUsableMod() throws {
+ let rig = try Rig()
+ #expect(rig.plan().environment["DM_ROMFS_OVERLAY"] == nil)
+ let mods = rig.gdir.appendingPathComponent("mods")
+ try rig.box.makeFolder(mods)
+ #expect(rig.plan().environment["DM_ROMFS_OVERLAY"] == nil, "an empty mods folder")
+ try rig.box.makeFolder(mods.appendingPathComponent("code/exefs"))
+ try rig.box.makeFolder(mods.appendingPathComponent(".hidden/romfs"))
+ try rig.box.write("x", to: mods.appendingPathComponent("loose-file.txt"))
+ #expect(rig.plan().environment["DM_ROMFS_OVERLAY"] == nil, "code only, hidden and plain files do not count")
+ try rig.box.makeFolder(mods.appendingPathComponent("b/romfs"))
+ try rig.box.makeFolder(mods.appendingPathComponent("a/atmosphere/contents/\(Fixtures.orbit)/romfs"))
+ try rig.box.write("x", to: mods.appendingPathComponent("c/data.bin"))
+ let env = rig.plan().environment
+ #expect(env["DM_ROMFS_OVERLAY"] == [mods.path + "/a/atmosphere/contents/\(Fixtures.orbit)/romfs", mods.path + "/b/romfs", mods.path + "/c"].joined(separator: ":"))
+ #expect(env["DM_ENV_FILE_KEYS"] == "", "the mods folder is not an env file")
+ }
+
+ @Test func modsOfOneGameDoNotReachAnother() throws {
+ let rig = try Rig()
+ try rig.box.makeFolder(rig.gdir.appendingPathComponent("mods/m/romfs"))
+ 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(rig.plan().environment["DM_ROMFS_OVERLAY"] == rig.gdir.path + "/mods/m/romfs")
+ }
+
+ @Test func overlayPrecedenceIsLaunchEnvironmentThenGameEnvFileThenModsThenSharedFile() throws {
+ let shared = "DM_ROMFS_OVERLAY=/shared\n"
+ // mods beat the shared file
+ var rig = try Rig()
+ try rig.box.makeFolder(rig.gdir.appendingPathComponent("mods/m/romfs"))
+ #expect(rig.plan(envFile: shared).environment["DM_ROMFS_OVERLAY"] == rig.gdir.path + "/mods/m/romfs")
+ #expect(rig.plan(envFile: shared).environment["DM_ENV_FILE_KEYS"] == "")
+ // the game's env file beats the mods folder
+ try rig.box.write("DM_ROMFS_OVERLAY=/own\n", to: rig.gdir.appendingPathComponent("env.txt"))
+ #expect(rig.plan(envFile: shared).environment["DM_ROMFS_OVERLAY"] == "/own")
+ // the launch environment beats the game's env file
+ rig = try Rig(environment: ["DM_ROMFS_OVERLAY": "/launch"])
+ try rig.box.makeFolder(rig.gdir.appendingPathComponent("mods/m/romfs"))
+ try rig.box.write("DM_ROMFS_OVERLAY=/own\n", to: rig.gdir.appendingPathComponent("env.txt"))
+ #expect(rig.plan(envFile: shared).environment["DM_ROMFS_OVERLAY"] == "/launch")
+ // without a mods folder the shared file still applies
+ let plain = try Rig()
+ #expect(plain.plan(envFile: shared).environment["DM_ROMFS_OVERLAY"] == "/shared")
+ }
+
@Test func argumentsExecutableAndLocations() throws {
let rig = try Rig()
let plan = rig.plan()