---
name: ns-game-apple-arm-port
license: MIT
description: 将 Nintendo Switch（NS）游戏适配到 Apple Silicon macOS、iPadOS 和 iOS，以 Rust 原生兼容层与 Metal 为核心，涵盖版本识别、ARM64 离线改写、Horizon 服务、NVN 到 Metal、输入音频、签名部署及实机验收。用于原生移植、跨游戏或版本适配、黑屏花屏卡死排查、移植进度评估；普通模拟器安装配置不属于本 skill。
---

# NS 游戏到 Apple ARM 的原生移植

以原游戏代码在目标设备上产生可见、可操作、可保存的结果为目标。CPU 同为 ARM64 只减少指令翻译工作，不能省略 OS ABI、内存、线程、图形、音频与输入兼容层。

默认采用 **先全量实现，再统一测试修复** 的节奏：先完成当前任务范围内所有已明确的必要改动，再集中构建、测试和验收。“全量”以用户目标为边界，不扩展为实现全部 Horizon/NVN 功能；减少测试启动次数，不降低最终验收标准。

## 语言与架构要求

- 新建移植核心必须使用 Rust（`.rs`），以 Cargo workspace 分离资源解析、共享 ABI、离线改写、着色器转换与 host runtime。已有 Rust 工程直接复用；已有 C/C++ 原生模块通过明确的 FFI 边界接入，不为统一语言重写已验证模块。用户明确指定其他技术栈时遵从并记录差异。
- Swift 用于启动器与 Apple 平台 UI；Objective-C/Objective-C++、C/C++ 用于必要的系统桥接或现成原生库；AArch64 汇编限于入口、寄存器保存及调用跳板；Metal Shading Language（MSL）用于 GPU 程序。Python/Bash 只编排资源准备、构建、签名与诊断，不承载逐帧回放或 guest 执行热路径。
- 路线为本地资源解析 → AArch64 离线改写 → 原游戏机器码原生执行 → Horizon/SDK 兼容 → NVN 命令录制与 Metal 回放。保留原游戏逻辑，不以重写玩法、宿主演示画面或仅有 API 空桩替代移植。
- 开始实现或跨游戏复用前读 [architecture-and-workflow.md](references/architecture-and-workflow.md)，确定模块边界、游戏版本配置与最短纵向验证路径。该参考提炼自 Rust/Cargo 的实际移植结构，不依赖原项目存在于本机。

## 开始工作

1. 从用户指定目录或当前工作区定位目标仓库；参考仓库只在用户提供或当前工作区可发现时读取，不假定任何开发者本机路径。读取目标仓库说明、局部 AGENTS.md、Git 状态、构建入口和最新验证记录。先确认用户要实现、诊断还是只评估；评估任务保持只读。
2. 建立输入矩阵：游戏/Title ID、本体/升级/DLC、显示版本、NPDM 架构、实际 NSO 模块 build ID、目标 OS/芯片、源码版本、运行方式。以实际提取模块为准，不凭文件名或游戏名称推定 AArch64。
3. 保留既定路线。已有原生兼容层基础时复用提取、改写、host 与 Metal 架构，逐模块比较；不要把其他游戏的地址补丁直接搬过来。新项目先检查是否有可复用兼容层，再决定工程量。AArch32 输入不适用于这条 AArch64 直接执行路线；寻找用户已有的合适版本或明确需要另一条执行路线。
4. 先选一个可重复的最短验收路径：启动 → 标题/菜单 → 场景 → 操作 → 正常退出 → 新进程读档。结合源码、输入模块和已有日志，一次盘点这条路径涉及的全部已知缺口、依赖关系与验收项；该路径用于实现完成后的统一验收，不作为逐项改动后的启动门槛。

## 按问题读取参考

- 代码装载、补丁、Horizon ABI、线程与平台部署：读 [runtime-and-platforms.md](references/runtime-and-platforms.md)。
- 黑屏、花屏、地形/水色异常、shader 或性能问题：读 [graphics-and-debugging.md](references/graphics-and-debugging.md)。
- 验收、进度判断、复盘与交接：读 [validation-and-cases.md](references/validation-and-cases.md)。包含可迁移案例与证据边界。

## 实施节奏

### 1. 集中实现

- 按提取/身份识别、指令改写、装载/重定位、SDK/服务、命令录制、Metal 回放/提交、窗口及游戏行为整理改动清单。确定共享接口后，连续完成相关模块、调用方、平台接线、配置及必要回归用例，避免只改底层而留下已知的上层缺口。
- 实现期间以源码阅读、符号搜索、差异审查和已有证据推进。不要每改一个文件、模块或补丁就运行 `cargo check`、构建、测试、shader 全量转换、安装、启动游戏或抓帧；把这些执行集中到实现完成后。无需为了切换阶段再次请求确认。
- 不确定项先记入清单并继续不依赖它的改动。仅当缺失事实会改变架构/接口、使后续实现无法可靠继续，且源码与已有记录无法回答时，提前做一次能解决该问题的最小探针；注明待回答问题，获得答案后立即回到实现。不要以一般性风险或“确认一下”为由恢复逐改逐测。用户明确要求的测试节奏优先。

### 2. 统一验证

- 当前目标内已明确的必要改动完成、调用链接通后，统一执行静态检查、受影响模块的测试及目标平台构建；通过后集中完成必要的资源准备、签名/部署与实际游戏验收。优先复用有效增量产物，不无故重建全部资源或清空缓存。
- 底层语义按改动选择指令等价、ABI 布局、并发或真实 GPU 读回验证；游戏运行覆盖约定路径与受影响行为。尽量在同一构建、同一轮运行中采集多个验收项，保存与新进程读档等必需的生命周期检查仍分别执行。用户禁止测试时不运行，明确列出未验证项。
- 一轮内汇总所有可独立执行的检查结果；构建失败时跳过依赖新产物的运行，不拿旧包继续验收。记录失败、阻塞和未测项，不把首个失败后尚未执行的项目当成通过。

### 3. 集中修复与收敛

- 将统一验证发现的问题按根因和依赖分组，用可证伪假设定位。集中修复同组问题及其受影响调用链后再复测，不按每条报错或每个小补丁重启完整流程。
- 每批修复先增量构建并复测失败项与受影响的回归项；涉及共享 ABI、改写或同步语义时相应扩大覆盖。修复收敛后，用最终构建统一确认受影响的游戏路径；没有新改动、新失败或未决问题时停止重复测试。
- 保留诊断反例，更新当前结论。诊断开关默认关闭，采集有数量/大小上限；抓帧/单步可能改变时序，最终运行关闭重诊断并使用新进程。异常应包含模块相对位置、请求或资源信息，不能泄露密钥。
- 对应版本的源码、构建、安装包、运行 ID、日志和截图必须能关联。新构建不能借旧设备日志证明成功。未解决问题和环境阻塞如实交接，不把“代码已改完”报告为“移植已通过”。
- 未知服务、指令或格式保留明确失败信息；仅在证明调用方允许降级时实现有语义的降级。不要普遍返回成功掩盖未实现功能，也不要为消除表面异常而硬改角色高度、水色、碰撞或游戏进度。

## 资源与交付

- 源包、密钥、固件保持本地；不把密钥值写入命令参数、日志或仓库。不复制这些内容进 skill。保留原作者许可及版权说明。
- 用户源包只读；提取内容、改写模块、缓存、存档和日志使用独立且被忽略的数据目录。按游戏与版本隔离，不覆盖其他模拟器的状态；源码回退不删除用户存档。
- 缓存须能识别输入 build ID、改写器/转换器版本、平台和编译选项的变化。未知或混合版本应在进入 guest 代码前拒绝。
- macOS 与 iOS/iPadOS 分别构建、签名和验证。安装脚本成功只证明对应阶段；iPhone、iPad、模拟器与 Mac 的结果分别报告。
- 本地 iOS 构建可能包含原游戏改写代码；交付或发布前检查应用包内容与许可，只分发有权分发的内容。不要自动上传本地派生产物。

完成报告说明：修改了什么、实际执行到哪一步、证据对应哪个构建和设备、仍有哪些限制、下一步应验证哪个阻塞。避免无法证实的完成百分比或“已全面兼容”。