Skip to content

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

15.3 KB
Raw Blame
import Foundation

/// A game that comes as a folder of its files instead of NSP or XCI packages (LNPANDY/NX2Apple#512, #445). Switch 2 games come
/// this way. The engine builds such a folder with `scripts/pack_dump.py`, called by `build_ipa_from_nsp.py` when it is given the
/// folder, and needs no `prod.keys` for it: the files are not encrypted. The layout, as pack_dump.py reads it:
///
///     <folder>/base/exefs/        main, main.npdm, sdk, rtld, subsdk*
///     <folder>/base/romfs/
///     <folder>/updates/<version>/exefs/, romfs/    optional, the version as a decimal number, the patched RomFS
///     <folder>/dlc/<DLC title ID>/<n>/romfs/      optional, the DLC title ID in hex
///
/// The rules here are pack_dump.py's `is_dump` and `scan`, and build_ipa_from_nsp.py's `dump_folder`, so the launcher refuses
/// what the script would refuse, and names the missing piece instead of "no NSP in this folder". Reads only names, and the
/// first bytes of main.npdm: never the game's data.
///
/// The same game can come as one NUP container (a `.nup` file, https://github.com/a55uka/nup, SPEC v1): base, updates and DLC
/// as the same trees in one file, not encrypted either. The engine reads one from seedds/nxnative 423a674 (`scripts/pack_nup.py`),
/// given the file or a folder that holds it. The launcher reads only its header and package table (`readNUP`).
package enum GameFolder {
    /// What a game folder holds.
    package struct Contents: Equatable {
        package let folder: String
        /// The program ID in base/exefs/main.npdm, which the script takes as the title ID.
        package let titleID: UInt64
        /// The update folders by version, oldest first.
        package let updates: [(version: Int, path: String)]
        /// The DLC folders (dlc/<title ID>) with their title IDs, sorted by title ID.
        package let dlc: [(titleID: UInt64, path: String)]
        /// The NUP file the game is in, nil for a folder of files.
        package var nup: String? = nil

        package var titleIDHex: String { String(format: "%016llX", titleID) }
        package var basePath: String { nup ?? folder + "/base" }
        /// What the script is given: the NUP file, else the folder.
        package var scriptInput: String { nup ?? folder }
        /// The title ID is known (a NUP whose package table names none leaves it to the script, from the code in the container).
        package var hasTitleID: Bool { titleID != 0 }
        /// The script packs the newest update (the version to pack defaults to the newest in the folder).
        package var newestUpdate: (version: Int, path: String)? { updates.last }

        package static func == (a: Self, b: Self) -> Bool {
            a.folder == b.folder && a.titleID == b.titleID && a.nup == b.nup
                && a.updates.map(\.version) == b.updates.map(\.version) && a.updates.map(\.path) == b.updates.map(\.path)
                && a.dlc.map(\.titleID) == b.dlc.map(\.titleID) && a.dlc.map(\.path) == b.dlc.map(\.path)
        }
    }

    /// Why a folder that is meant as a game folder cannot be built.
    package enum Problem: Error, Equatable {
        /// `base/exefs/main.npdm`, or a RomFS (`base/romfs`, or one in `updates/<version>/`), is not there. The piece is named.
        case missing(String)
        /// `exefs/` and `romfs/` sit in the folder itself: they belong in a folder named `base`.
        case noBaseFolder
        /// main.npdm is not an NPDM, or has no ACI0 section with a program ID.
        case unreadableNPDM
        /// The program ID is not a base game's (its low 12 bits are not zero).
        case notBaseTitle(UInt64)
        /// A game package sits beside the folders: the script would build the package and ignore the folders.
        case packageBeside(String)
        /// A folder under dlc/ whose name is not a title ID in hex.
        case dlcName(String)
        /// A folder under dlc/ whose title ID is not add-on content of this game.
        case notDLC(String, UInt64)
        /// A DLC folder without exactly one `<n>/romfs` (or `romfs`) folder: the name and how many there were.
        case dlcRomFS(String, Int)
        /// The file is not a NUP of format version 1: its name.
        case notNUP(String)
        /// The NUP is shorter or longer than its header says (copied or downloaded in part): its name.
        case nupPartial(String)
        /// More than one NUP in the folder: how many. The script takes one game per folder.
        case severalNUPs(Int)
    }

    /// Packages that make the script take the folder as a folder of packages.
    private static let packages: Set<String> = ["nsp", "xci", "nsz", "xcz"]

    /// The NUP files at the top of a folder (build_ipa_from_nsp.py `nup_file` looks there only), by name.
    package static func nupFiles(in folder: String) -> [String] {
        ((try? FileManager.default.contentsOfDirectory(atPath: folder)) ?? []).filter {
            !$0.hasPrefix("._") && ($0 as NSString).pathExtension.lowercased() == "nup" && isFile(folder + "/" + $0)
        }.sorted()
    }

    /// Whether the path is meant as a game folder or a NUP: a `.nup` file, a folder with a `.nup` at its top, a folder with
    /// `base/exefs/main.npdm`, or `exefs/main.npdm` with no `base/` (the files one level too high). Cheap: the folder picker asks
    /// this before it walks a folder that may hold 80,000 files.
    package static func isCandidate(_ path: String) -> Bool {
        let fm = FileManager.default
        if (path as NSString).pathExtension.lowercased() == "nup" && isFile(path) { return true }
        if isFile(path + "/base/exefs/main.npdm") || !nupFiles(in: path).isEmpty { return true }
        return isFile(path + "/exefs/main.npdm") && !fm.fileExists(atPath: path + "/base")
    }

    /// What the folder holds, or the first reason it cannot be built, in the order the script finds them.
    package static func scan(_ folder: String) -> Result<Contents, Problem> {
        if (folder as NSString).pathExtension.lowercased() == "nup" && isFile(folder) { return readNUP(folder) }
        let fm = FileManager.default
        func isDir(_ p: String) -> Bool { var d: ObjCBool = false; return fm.fileExists(atPath: p, isDirectory: &d) && d.boolValue }
        func dirs(_ p: String) -> [String] {
            ((try? fm.contentsOfDirectory(atPath: p)) ?? []).filter { !$0.hasPrefix(".") && isDir(p + "/" + $0) }.sorted()
        }
        let top = ((try? fm.contentsOfDirectory(atPath: folder)) ?? []).sorted()
        if let pkg = top.first(where: { !$0.hasPrefix("._") && packages.contains(($0 as NSString).pathExtension.lowercased()) && isFile(folder + "/" + $0) }) {
            return .failure(.packageBeside(pkg))
        }
        // A NUP in the folder is what the script builds, before any folders beside it
        let nups = nupFiles(in: folder)
        if nups.count > 1 { return .failure(.severalNUPs(nups.count)) }
        if let nup = nups.first { return readNUP(folder + "/" + nup) }
        let npdm = folder + "/base/exefs/main.npdm"
        if !isFile(npdm) {
            if isFile(folder + "/exefs/main.npdm") && !fm.fileExists(atPath: folder + "/base") { return .failure(.noBaseFolder) }
            return .failure(.missing("base/exefs/main.npdm"))
        }
        let versions = isDir(folder + "/updates") ? dirs(folder + "/updates").filter { !$0.isEmpty && $0.allSatisfy(\.isASCIIDigit) } : []
        // A newer engine takes a folder whose base has no RomFS when an update has one (pack_dump.py at seedds/nxnative 641d148).
        guard isDir(folder + "/base/romfs") || versions.contains(where: { isDir(folder + "/updates/" + $0 + "/romfs") }) else {
            return .failure(.missing("base/romfs"))
        }
        guard let data = fm.contents(atPath: npdm), let app = programID(npdm: data) else { return .failure(.unreadableNPDM) }
        if app & 0xFFF != 0 { return .failure(.notBaseTitle(app)) }
        let updates = versions.compactMap { v in Int(v).map { (version: $0, path: folder + "/updates/" + v) } }.sorted { $0.version < $1.version }
        var dlc: [(titleID: UInt64, path: String)] = []
        for name in isDir(folder + "/dlc") ? dirs(folder + "/dlc") : [] {
            let path = folder + "/dlc/" + name
            guard name.count <= 16, let tid = UInt64(name, radix: 16) else { return .failure(.dlcName(name)) }
            guard tid > app + 0x1000, tid - app - 0x1000 <= 2000 else { return .failure(.notDLC(name, tid)) }
            let numbered = dirs(path).filter { isDir(path + "/" + $0 + "/romfs") }
            let count = numbered.isEmpty ? (isDir(path + "/romfs") ? 1 : 0) : numbered.count
            guard count == 1 else { return .failure(.dlcRomFS(name, count)) }
            dlc.append((titleID: tid, path: path))
        }
        return .success(Contents(folder: folder, titleID: app, updates: updates, dlc: dlc.sorted { $0.titleID < $1.titleID }))
    }

    /// A NUP's title ID, updates and DLC from its header and package table (SPEC v1, pack_nup.py `Nup` and `scan`). The title ID
    /// is the base package's, else an update's with the low 12 bits cleared (a base may be an empty placeholder, Pokémon Pokopia),
    /// else 0: the script then reads it from the code. Checks the magic, the version and the file size, not the SHA-256s (the
    /// script checks every file it reads).
    package static func readNUP(_ path: String) -> Result<Contents, Problem> {
        let name = (path as NSString).lastPathComponent
        guard let h = FileHandle(forReadingAtPath: path) else { return .failure(.notNUP(name)) }
        defer { try? h.close() }
        func u(_ b: [UInt8], _ o: Int, _ n: Int) -> UInt64 { (0..<n).reduce(UInt64(0)) { $0 | UInt64(b[o + $1]) << (8 * UInt64($1)) } }
        let head = [UInt8](h.readData(ofLength: 0x80))
        guard head.count == 0x80, head[0..<3].elementsEqual("NUP".utf8), head[3] == 1 else { return .failure(.notNUP(name)) }
        let size = (try? FileManager.default.attributesOfItem(atPath: path))?[.size] as? UInt64 ?? 0
        if u(head, 0x40, 8) != size { return .failure(.nupPartial(name)) }
        let toc = u(head, 0x08, 8), count = Int(u(head, 0x48, 4))
        guard count > 0, count < 100_000, toc + 0x30 + UInt64(count) * 0x40 <= size else { return .failure(.notNUP(name)) }
        try? h.seek(toOffset: toc)
        let table = [UInt8](h.readData(ofLength: 0x30 + count * 0x40))
        guard table.count == 0x30 + count * 0x40, table[0..<4].elementsEqual([0x54, 0x4F, 0x43, 0x01]) else { return .failure(.notNUP(name)) }
        var base: UInt64 = 0, updates: [(version: Int, path: String)] = [], addons: [UInt64] = [], updateTitle: UInt64 = 0
        for i in 0..<count {
            let o = 0x30 + i * 0x40, tid = u(table, o, 8), version = Int(u(table, o + 20, 4))
            switch table[o + 24] {
            case 0: base = tid
            case 1: updates.append((version: version, path: path)); if updateTitle == 0 { updateTitle = tid & ~0xFFF }
            case 2: addons.append(tid)
            default: break
            }
        }
        let app = base != 0 && base & 0xFFF == 0 ? base : updateTitle
        return .success(Contents(folder: (path as NSString).deletingLastPathComponent, titleID: app,
                                 updates: updates.sorted { $0.version < $1.version }, dlc: addons.sorted().map { (titleID: $0, path: path) }, nup: path))
    }

    /// The ACI0 program ID of an NPDM (pack_dump.py `program_id`): the ACI0 offset and size at 0x70, the ID at ACI0 + 0x10.
    package static func programID(npdm d: Data) -> UInt64? {
        let b = [UInt8](d)
        func u32(_ o: Int) -> Int? { o + 4 <= b.count ? Int(b[o]) | Int(b[o + 1]) << 8 | Int(b[o + 2]) << 16 | Int(b[o + 3]) << 24 : nil }
        guard b.count >= 0x78, b[0..<4].elementsEqual("META".utf8), let off = u32(0x70), let size = u32(0x74),
              size >= 0x18, off + 0x18 <= b.count, b[off..<off + 4].elementsEqual("ACI0".utf8) else { return nil }
        return (0..<8).reduce(UInt64(0)) { $0 | UInt64(b[off + 0x10 + $1]) << (8 * UInt64($1)) }
    }

    /// Whether the engine builds game folders: it has `scripts/pack_dump.py` (seedds/nxnative 99947471, in the pin since v1.0.1).
    package static func engineBuildsFolders(_ engineRoot: String) -> Bool {
        !engineRoot.isEmpty && FileManager.default.fileExists(atPath: engineRoot + "/scripts/pack_dump.py")
    }

    /// Whether the engine builds NUP files: it has `scripts/pack_nup.py` (seedds/nxnative 423a674, in the pin from 641d148).
    package static func engineBuildsNUPs(_ engineRoot: String) -> Bool {
        !engineRoot.isEmpty && FileManager.default.fileExists(atPath: engineRoot + "/scripts/pack_nup.py")
    }

    /// Whether the engine has a profile for the game: `dm/games/<title ID>/game.tsv`. An engine that surveys a game without one
    /// (`engineSurveysWithoutProfile`) does not need it to build a NUP or a game folder.
    package static func engineHasProfile(_ titleID: UInt64, engineRoot: String) -> Bool {
        !engineRoot.isEmpty && FileManager.default.fileExists(atPath: engineRoot + "/dm/games/" + String(format: "%016llX", titleID) + "/game.tsv")
    }

    /// Whether the engine builds a NUP or a game folder of a game with no profile, from a provisional profile it makes by a survey:
    /// `scripts/build_ipa_from_nsp.py` has `survey_nup` and `survey_dump` (seedds/nxnative 056e41fe, PR #1295). An older engine packs
    /// a game folder only for a game with a profile.
    package static func engineSurveysWithoutProfile(_ engineRoot: String) -> Bool {
        guard !engineRoot.isEmpty, let data = FileManager.default.contents(atPath: engineRoot + "/scripts/build_ipa_from_nsp.py") else { return false }
        return data.range(of: Data("def survey_nup".utf8)) != nil
    }

    /// The `name` row of the game's profile: a game folder has no control data, so the script names the app after it too.
    package static func profileName(_ titleID: UInt64, engineRoot: String) -> String? {
        guard !engineRoot.isEmpty,
              let text = try? String(contentsOfFile: engineRoot + "/dm/games/" + String(format: "%016llX", titleID) + "/game.tsv", encoding: .utf8),
              let row = text.split(separator: "\n").first(where: { $0.hasPrefix("name\t") }) else { return nil }
        let name = row.dropFirst(5).trimmingCharacters(in: .whitespaces)
        return name.isEmpty ? nil : name
    }

    /// Whether the engine's profile is a Switch 2 game's. No profile key says so yet (#445 asks upstream for one): every Switch 2
    /// profile at seedds/nxnative 641d148 names it in its first line, "# Donkey Kong Bananza (Switch 2, update v458752)", and the
    /// launcher reads that. The `04` start of their title IDs is not used: it is an observation, not a rule.
    package static func profileIsSwitch2(_ titleID: String, engineRoot: String) -> Bool {
        guard !engineRoot.isEmpty, titleID.count == 16,
              let handle = FileHandle(forReadingAtPath: engineRoot + "/dm/games/" + titleID.uppercased() + "/game.tsv") else { return false }
        defer { try? handle.close() }
        let head = String(decoding: handle.readData(ofLength: 512), as: UTF8.self)
        guard let first = head.split(separator: "\n", maxSplits: 1).first, first.hasPrefix("#") else { return false }
        return first.contains("(Switch 2")
    }

    private static func isFile(_ path: String) -> Bool {
        var d: ObjCBool = false
        return FileManager.default.fileExists(atPath: path, isDirectory: &d) && !d.boolValue
    }
}

private extension Character {
    var isASCIIDigit: Bool { ("0"..."9").contains(self) }
}