Skip to content

Launcher & ShellHost: externalize oversized msl shaders, repack shared IPA, and batch-transfer games - #1216

Merged
LNPANDY merged 1 commit into
mainfrom
feat/shared-ipa-repack-and-ext-msl
Nov 12, 2026
Merged

LNPANDY merged 1 commit into
mainfrom
feat/shared-ipa-repack-and-ext-msl

Conversation

@LNPANDY

@LNPANDY LNPANDY commented Nov 12, 2026

Copy link
Copy Markdown
Owner

Summary

Stacked on top of #1215 (refactor/patch-slim-phase2). Delivers the refined, zero-engine-patch version of #1080 and #947 across macOS (NXCore / NXModel / NXLauncher), Windows/Qt (nspb_qt), and iOS (ShellHost):

  1. Non-polluting externalization of oversized msl/ shader trees (> 64 MiB, fixes Ocarina of Time (NUP) shared-app IPA: 7 GB msl shader image can't be installed by Sideloadly, AltServer or AltStore; romfs.id "cannot be read" after install #947):

    • When packing an unsigned shared IPA (NX2Apple.ipa), any staged game framework whose msl/ directory exceeds 64 MiB has its staged msl/ replaced with external-msl.json ({"schema": 1, "external_msl": true}) and records its title ID in <shellRoot>/export/external-msl-titles.json, keeping the unsigned IPA well below sideloaders' 2 GB / 4 GB limits while leaving <shellRoot>/frameworks/DmGame<ID>.framework/msl/ untouched in place.
    • Packed game data archives (<archive>/<ID>/) remain clean without copying msl/ into them, preventing direct Xcode-signed installs from duplicating bundled shaders onto the device.
    • During unsigned-IPA transfers (ShellInstall.transferSources on macOS and DriveCopy.collect_transfer_files on Windows/Qt), externalized msl/ files are merged on the fly from the mirrored framework into <dest>/<ID>/msl/... for both device (devicectl) and external drive copies.
    • On iOS (ShellHost), ExternalShaders recursively inspects Documents/games/<ID>/msl and <dataURL>/msl (rejecting any incomplete .nxpart, .nxjoin, .part, or .partial entries while ignoring harmless hidden metadata), blocks launch with .needsGameData when required external shaders are missing or half-transferred, and wires EngineLaunchPlan to resolve DM_MSL_DIR from appFolder/msl -> dataURL/msl -> bundled framework msl.
  2. No-rebuild shared IPA repack with stale-engine preflight:

    • Exposes Export IPA directly in Step 1 on both macOS (ExportSteps.swift) and Windows/Qt (ui.py + win/shell_export.py:repack_built_shell) so users can repack NX2Apple.ipa from already-built frameworks in shell.json without rebuilding any game.
    • Adds stale_frameworks preflight checks on Windows/Qt matching macOS so repacking warns when cached frameworks come from an older DMSH_CHAIN.
  3. Multi-game batch selection for device transfers and external drives:

    • Adds SendSelectedSheet on macOS (for both Device queue transfers and sequential Drive or folder copies with live free-space and FAT32 4 GB preflight checks and cancellation support) and DriveSelectDialog on Windows/Qt, replacing the coarse all-or-nothing action with per-game checkboxes, Select All / Clear toggles, and accurate byte totals (including externalized msl/ trees).
    • Updates all 10 shipped localization catalogs (de, en, es, fr, it, ja, ko, pt-br, sv, zh) and Localizable.xcstrings.

UI Comparison 1: macOS Launcher (InstallCard & SendSelectedSheet)

Simplified Chinese (zh)

View Before After
Export Mode (Device) mac-export-device-before-zh mac-export-device-after-zh
Export Mode (Drive or folder) mac-export-drive-before-zh mac-export-drive-after-zh
Select Games Sheet N/A mac-select-sheet-drive-zh

English (en)

View Before After
Export Mode (Device) mac-export-device-before-en mac-export-device-after-en
Export Mode (Drive or folder) mac-export-drive-before-en mac-export-drive-after-en
Select Games Sheet N/A mac-select-sheet-drive-en

Japanese (ja)

View Before After
Export Mode (Device) mac-export-device-before-ja mac-export-device-after-ja
Export Mode (Drive or folder) mac-export-drive-before-ja mac-export-drive-after-ja
Select Games Sheet N/A mac-select-sheet-drive-ja

UI Comparison 2: Windows / Qt Launcher (InstallCard & DriveSelectDialog)

Language Before (InstallCard) After (InstallCard) After (DriveSelectDialog)
Chinese (zh) qt-install-card-before-zh qt-install-card-after-zh qt-drive-select-dialog-zh
English (en) qt-install-card-before-en qt-install-card-after-en qt-drive-select-dialog-en
Japanese (ja) qt-install-card-before-ja qt-install-card-after-ja qt-drive-select-dialog-ja

Verification

  • patches/ and .upstream-ref remain completely untouched (0 engine patches added).
  • Negative testing verified on iOS (EngineLaunchPlan / ExternalShaders recursive .nxpart check) and Windows/Qt (ExternalMslAndBatchDriveCopyTest) prior to restoring fixes.
  • Passed python3 tools/l10n_shell_catalogs.py --check, frontend-ios ShaderResourcesTests & EngineLaunchPlanTests, frontend-qt full unittest suite (including test_localization_rules.py and test_win_shell_export.py), and frontend full swift test suite (including LauncherControlWidthTests across all 10 languages and SourceSizeTests).

@github-actions github-actions Bot added launcher The NX2Apple launcher app ios iPhone or iPad windows Windows (the Qt front end) labels Nov 12, 2026
@v0lumehi v0lumehi modified the milestones: v1.4.0, v1.5.0, v1.6.0 Nov 12, 2026
…d IPA, and batch-transfer games

Strip msl shader trees exceeding 64 MiB from unsigned shared IPAs on both macOS and Windows/Qt without polluting the packed archive directory, record external-msl.json inside the staged framework plus external-msl-titles.json in the export folder, and merge externalized shaders on the fly during device or external drive transfers. Teach iOS ShellHost to verify complete external msl trees recursively and resolve DM_MSL_DIR from appFolder or dataURL. Add no-rebuild shared IPA repack with stale-engine preflight and multi-game selection sheets across macOS and Windows/Qt with all 10 localization catalogs.
@LNPANDY
LNPANDY force-pushed the refactor/patch-slim-phase2 branch from 18203cb to 07a0149 Compare November 12, 2026 19:45
@LNPANDY
LNPANDY force-pushed the feat/shared-ipa-repack-and-ext-msl branch from 0a36e25 to 0d9e398 Compare November 12, 2026 19:45
@LNPANDY
LNPANDY changed the base branch from refactor/patch-slim-phase2 to main November 12, 2026 20:07
@LNPANDY
LNPANDY merged commit ff6011c into main Nov 12, 2026
19 of 33 checks passed
@LNPANDY
LNPANDY deleted the feat/shared-ipa-repack-and-ext-msl branch November 12, 2026 20:07
LNPANDY added a commit that referenced this pull request Nov 12, 2026
Bump AppUpdateStore.appVersion and Qt APP_VERSION to 1.5.0 and add CHANGELOG.md, CHANGELOG.zh-CN.md, and bilingual release-notes/v1.5.0.md entries covering PRs #1214, #1215, #1216, #1217, #1226, and #1227.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ios iPhone or iPad launcher The NX2Apple launcher app windows Windows (the Qt front end)

Projects

None yet

2 participants