| name | ns-game-apple-arm-port |
|---|---|
| description | 将 Nintendo Switch（NS）游戏适配到 Apple Silicon macOS、iPadOS 和 iOS，以 Rust 原生兼容层与 Metal 为核心，涵盖版本识别、ARM64 离线改写、Horizon 服务、NVN 到 Metal、输入音频、签名部署及实机验收。用于原生移植、跨游戏或版本适配、黑屏花屏卡死排查、移植进度评估；普通模拟器安装配置不属于本 skill。 |
NS 游戏到 Apple ARM 的原生移植
以原游戏代码在目标设备上产生可见、可操作、可保存的结果为目标。CPU 同为 ARM64 只减少指令翻译工作，不能省略 OS ABI、内存、线程、图形、音频与输入兼容层。
语言与架构要求
- 新建移植核心必须使用 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，确定模块边界、游戏版本配置与最短纵向验证路径。该参考提炼自 Rust/Cargo 的实际移植结构，不依赖原项目存在于本机。
开始工作
- 从用户指定目录或当前工作区定位目标仓库；参考仓库只在用户提供或当前工作区可发现时读取，不假定任何开发者本机路径。读取目标仓库说明、局部 AGENTS.md、Git 状态、构建入口和最新验证记录。先确认用户要实现、诊断还是只评估；评估任务保持只读。
- 建立输入矩阵：游戏/Title ID、本体/升级/DLC、显示版本、NPDM 架构、实际 NSO 模块 build ID、目标 OS/芯片、源码版本、运行方式。以实际提取模块为准，不凭文件名或游戏名称推定 AArch64。
- 保留既定路线。已有原生兼容层基础时复用提取、改写、host 与 Metal 架构，逐模块比较；不要把其他游戏的地址补丁直接搬过来。新项目先检查是否有可复用兼容层，再决定工程量。AArch32 输入不适用于这条 AArch64 直接执行路线；寻找用户已有的合适版本或明确需要另一条执行路线。
- 先选一个可重复的最短验收路径：启动 → 标题/菜单 → 场景 → 操作 → 正常退出 → 新进程读档。阶段性推进一个实际阻塞，使用日志、代码和画面确认原因。
按问题读取参考
- 代码装载、补丁、Horizon ABI、线程与平台部署：读 runtime-and-platforms.md。
- 黑屏、花屏、地形/水色异常、shader 或性能问题：读 graphics-and-debugging.md。
- 验收、进度判断、复盘与交接：读 validation-and-cases.md。包含可迁移案例与证据边界。
实施闭环
- 先记录故障所在层：提取/身份识别 → 指令改写 → 装载/重定位 → SDK/服务 → 命令录制 → Metal 回放/提交 → 实际窗口 → 游戏行为。
- 每轮用一个可证伪假设，收集最小必要证据，再作局部修复。诊断开关默认关闭，有数量/大小上限；异常应包含模块相对位置、请求或资源信息，不能泄露密钥。
- 为底层语义修复选择合适验证：指令等价、ABI 布局、并发、真实 GPU 读回。静态检查与构建后，按用户授权范围运行实际游戏；用户禁止测试时只记录尚未验证，不擅自运行。
- 对应版本的源码、构建、安装包、运行 ID、日志和截图必须能关联。新构建不能借旧设备日志证明成功。
- 保留诊断反例，更新当前结论。抓帧/单步可能改变时序；修复后用关闭重诊断的新进程复测。不要为消除表面异常而硬改角色高度、水色、碰撞或游戏进度。
- 未知服务、指令或格式保留明确失败信息；仅在证明调用方允许降级时实现有语义的降级。不要普遍返回成功掩盖未实现功能。
资源与交付
- 源包、密钥、固件保持本地；不把密钥值写入命令参数、日志或仓库。不复制这些内容进 skill。保留原作者许可及版权说明。
- 用户源包只读；提取内容、改写模块、缓存、存档和日志使用独立且被忽略的数据目录。按游戏与版本隔离，不覆盖其他模拟器的状态；源码回退不删除用户存档。
- 缓存须能识别输入 build ID、改写器/转换器版本、平台和编译选项的变化。未知或混合版本应在进入 guest 代码前拒绝。
- macOS 与 iOS/iPadOS 分别构建、签名和验证。安装脚本成功只证明对应阶段；iPhone、iPad、模拟器与 Mac 的结果分别报告。
- 本地 iOS 构建可能包含原游戏改写代码；交付或发布前检查应用包内容与许可，只分发有权分发的内容。不要自动上传本地派生产物。
完成报告说明：修改了什么、实际执行到哪一步、证据对应哪个构建和设备、仍有哪些限制、下一步应验证哪个阻塞。避免无法证实的完成百分比或“已全面兼容”。