Skip to content
twoyears666Public

About

Gameshell — iOS/iPadOS/macOS 游戏启动器 UI 壳(参考盖世游戏/GameHub,Swift + Obj-C 混合,URL 驱动,支持手柄与键鼠)

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

22 Commits

Folders and files

Repository files navigation

Gameshell

一个 iOS / iPadOS / macOS 的 URL 启动器 UI 壳(shell)。 界面风格参考 盖世游戏 / GameHub、第一排方块行参考 PS5 首页,但不使用其任何代码或资源,仅参照「布局结构与视觉语言」。 本仓库以「壳 + 启动通路」为主;模拟器部分已接入 mGBA、Nestopia 与 Mesen-S(GBA / GB / GBC / NES / SNES),其余系统尚未接入。 功能会持续往里加,没实现的功能都在 REFERENCE.md 里如实标注为「未完成」。

  • 只有一个界面:主界面(顶栏 + 第一排方块行),没有游戏库 / 榜单 / 我的等其它页面
  • 技术栈:Swift(SwiftUI,UI 层)+ Objective-C(核心层)混合
  • 游戏来源:完全 URL 驱动 —— 打开一个 URL 就等于打开一个游戏或 App; http(s) 用内置 WebView 打开,steam:// 这类 scheme 交给系统唤起对应 App
  • App 内添加 URL:主界面右上角「添加」,填名称 + URL 即可,写入沙盒后重启仍在(基础功能)
  • 不内置任何游戏:清单默认为空,所有条目都由你自己添加
  • 模拟器 ROM 导入与模拟:主界面「模拟器 ROM」分区,导入 ROM 后点开卡片即用内置核心模拟; 不内置任何 ROM,全部由你自己导入(App 内导入,或从「文件」App 拷进 Documents/ROMs/<系统>/)
  • 已接入的核心:mGBA(GBA / GB / GBC)+ Nestopia(NES)+ Mesen-S(SNES);NDS / 3DS / Wii / Wii U 尚未接入(如实标注,见 REFERENCE.md)
  • 虚拟手柄:操控界面自绘(布局参照 Delta / manic emu),不借鉴 RetroArch 的触屏 UI
  • 第一排:PS5 风格的横向方块行(聚焦项放大 + 白色高亮描边,其余缩小变暗)
  • 输入:支持 手柄(GameController 框架,热插拔)与 键鼠
  • 构建:GitHub Actions CI(macOS runner:XcodeGen + xcodebuild)
  • 主题:所有颜色 / 圆角 / 间距 / 字号集中在 Theme.swift,便于后续做主题包

本项目的设计参考与「未完成功能诚实清单」见 REFERENCE.md。


快速开始

本仓库不包含 .xcodeproj(由 project.yml 生成),需要先安装 XcodeGen:

brew install xcodegen
xcodegen generate
open Gameshell.xcodeproj

命令行构建(与 CI 一致):

# iOS / iPadOS(模拟器)
xcodebuild -project Gameshell.xcodeproj -scheme Gameshell \
  -configuration Release -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  CODE_SIGNING_ALLOWED=NO build

# iOS 真机(用于打包 IPA)
xcodebuild -project Gameshell.xcodeproj -scheme Gameshell \
  -configuration Release -sdk iphoneos \
  -destination 'generic/platform=iOS' \
  CODE_SIGNING_ALLOWED=NO build

# macOS
xcodebuild -project Gameshell.xcodeproj -scheme Gameshell \
  -configuration Release -destination 'generic/platform=macOS' \
  CODE_SIGNING_ALLOWED=NO build

CI 产物

每次推送到 main,.github/workflows/build.yml 会在 macos-15 上跑完整流程并上传:

产物 内容 签名状态
Gameshell-macOS macOS .app ad-hoc 自签名
Gameshell-IPA iOS 真机 .ipa(Payload/Gameshell.app) ad-hoc 自签名 + 最小 entitlements,非开发者证书签名
Gameshell-TrollStore-tipa 与 IPA 内容相同的 .tipa,便于 TrollStore 识别 同上

⚠️ 诚实说明:CI 产出的 IPA / tipa 是 未签名 + codesign -s - ad-hoc 自签名 的包 (entitlements 见 Signing/Gameshell-iOS.entitlements), 只能通过 TrollStore(巨魔) 或侧载工具安装 / 重签, 不能直接装到未越狱设备、也不能上架 App Store。 正规签名的 IPA 需要 Apple 开发者证书与描述文件,属于未完成部分(见 REFERENCE.md)。

安装注意:

  • 系统要求 iOS / iPadOS 16.0 及以上(MinimumOSVersion 由工程 deploymentTarget 决定);低于此版本会装不上或启动即退。
  • macOS 上的 .app 是 ad-hoc 签名,从浏览器下载后带有 quarantine 标记,需要先执行:
xattr -dr com.apple.quarantine /path/to/Gameshell.app

URL 驱动

打开一个 URL = 打开一个游戏 / App。App 内添加(基础功能):主界面右上角「添加」→ 填名称和 URL → 保存。

  • 条目写入沙盒 Documents/games.json,下次启动优先读这份;内置的 Resources/games.json 只是空的兜底清单。
  • 长按方块卡片可以删除条目(自绘确认浮层,不用系统弹窗)。
  • 单条记录的字段(见 GSGame):
{
  "id": "唯一 id",
  "name": "显示名称",
  "url": "https://example.com/game",
  "platform": "网页",
  "icon": "gamecontroller.fill",
  "controllerSupport": false
}
  • url:URL 驱动的核心。
    • http(s) → 由内置 WebView 打开(网页 / 网页游戏)。
    • 其它 scheme → 交给系统打开,用于唤起本机 App,例如 steam://、minecraft://、youtube://。
    • 在 App 内添加时如果没写 scheme,会自动补 https://。
  • icon:以 http 开头按远程图片加载,否则按 SF Symbol 名渲染。
  • rating / description / tags:能被解析入库,但当前 UI 没有展示(详见 REFERENCE 的未完成清单)。

深链(URL scheme:gameshell://)

深链 作用
gameshell://open?url=https://example.com/game&name=示例 用 URL 直接开一个不在清单里的条目
gameshell://open?url=steam://run/123 URL 是 steam:// 这类时,交给系统唤起对应 App
gameshell://play?id=<清单里的 id> 按 id 在清单里找到并打开
gameshell://home 关闭播放器,回到主界面

命令行验证:

# macOS
open "gameshell://open?url=https://example.com&name=示例"

模拟器(ROM 导入与模拟)

ROM 全由你自己导入,App 不内置、也不下载任何 ROM。

导入(两种方式)

  1. 主界面「模拟器 ROM」分区 → 点「导入 ROM」→ 从系统「文件」里选 ROM。 选中的文件会被复制进沙盒 Documents/ROMs/<系统>/;重名自动加序号,不覆盖已有文件。
  2. 直接用「文件」App 把 ROM 拷进 Documents/ROMs/<系统>/(已开启文件共享),回到 App 会自动扫到。

点开卡片即启动:整屏模拟画面 + 自绘虚拟手柄;长按卡片删除(只删 ROM 文件,同目录的 .sav 存档会保留)。

各系统接入状态(诚实标注)

系统 认作的扩展名 计划核心(许可证) 当前状态
NES .nes .fds .unf .unif Nestopia(GPL-2.0-or-later) ✅ 已接入
SNES .sfc .smc .swc .fig .bs Mesen-S(GPL-3.0) ✅ 已接入
GB .gb mGBA(MPL-2.0) ✅ 已接入
GBC .gbc mGBA(MPL-2.0) ✅ 已接入
GBA .gba .agb mGBA(MPL-2.0) ✅ 已接入
NDS .nds melonDS(GPL-3.0) 未接入
3DS .3ds .cia .cci .cxi .app Azahar 系(GPL-2.0,需 JIT) 未接入
Wii .wbfs .iso .rvz .wia .dol .elf Dolphin(GPL-2.0+,需 JIT) 未接入
Wii U .wud .wux .rpx .wua .rpl Cemu / MeloCafe 系(MPL-2.0,需 JIT) 未接入

为什么 SNES 不用 Snes9x:Snes9x 的许可证是「非商用专用」 ("freeware for PERSONAL USE only",且 libretro 移植部分写明 "Under no circumstances will commercial rights be given"),它不是开源许可、也与 GPL-3.0 不兼容, 所以本仓库不引入它的源码。SNES 最终选了同样是 GPL-3.0 的 Mesen-S。

未接入的系统也能导入 ROM(文件先待在库里),只是点开时 App 会如实告诉你「核心还没接入」,不会假装能玩。

为什么核心是静态链接,而不是动态加载

iOS 15 + A12 起系统封禁了 dynamic-codesigning 与 com.apple.private.cs.debugger, 运行时 dlopen 一个未签名的核心动态库已经不可行(RetroArch 那种「外挂 core dylib」的做法在 TrollStore 上也不成立)。 因此核心一律用 CMake 交叉编译成 arm64 静态库,直接链接进主二进制 (见 Scripts/build_cores.sh;编译不成功时会降级成「该核心不可用」,不会让整个构建挂掉)。

JIT(3DS / Wii / Wii U 必需)

需要 JIT 的平台,App 会在启动前真实探测(直接在进程里 mmap(MAP_JIT) 试探);拿不到可执行内存时如实提示,并给出两条开启路径:

  1. TrollStore(巨魔)安装:装好后即为 App 打开了 JIT 权限。若进 App 仍提示未开,点提示条上的「开启 JIT」—— App 会用 apple-magnifier://enable-jit?bundle-id=<本 App bundle-id> 拉起 TrollStore 开一次,回到 App 点「重试」。
  2. 普通侧载(没有 TrollStore):用 StikDebug 附加调试器后再启动 App,由调试器授予 JIT。

现状:目前还没有任何依赖 JIT 的核心真正接入,上面两条路径是为后续接入准备的;现在 JIT 探测结果只用于如实展示状态。

目录结构

Sources/
├── App/                        # Swift:入口与全局状态
│   ├── GameshellApp.swift      # @main,注册 gameshell:// scheme
│   ├── AppState.swift          # 清单 / ROM 库、启动、浮层、外设状态
│   └── GSAudioPlayer.swift     # 模拟器音频(核心 → AVAudioEngine,iOS)
├── Core/                       # Objective-C:核心逻辑 + 模拟器宿主
│   ├── GSGameManifest.h/.m     # 清单解析 + 增删 + 沙盒持久化
│   ├── GSGameLauncher.h/.m     # 深链解析 / URL 规整
│   ├── GSInputManager.h/.m     # 手柄(GCController)+ 键鼠在线探测
│   ├── GSSystem.h/.m           # 模拟器「系统」注册表(扩展名 → 系统 → 计划核心)
│   ├── GSROMLibrary.h/.m       # ROM 扫描 / 导入 / 删除 / .sav 路径
│   ├── GSEmulator.h/.m         # 会话 + 帧循环 + 音频环形缓冲 + JIT 探测(GSJIT)
│   ├── GSMGBACore.m            # mGBA 宿主适配(GBA / GB / GBC)
│   ├── GSNestopiaCore.mm       # Nestopia 宿主适配(NES,ObjC++:Nestopia 是 C++)
│   ├── GSSnesCore.mm           # Mesen-S 宿主适配(SNES,ObjC++:走 libretro 接口)
│   ├── GSBuiltCoresCompat.h    # 编译期开关:核心没编出来就降级为「不可用」
│   └── Gameshell-Bridging-Header.h
└── UI/                         # Swift:SwiftUI 界面
    ├── Theme.swift             # 设计令牌(颜色/圆角/间距/字号/尺寸)
    ├── Components/             # 顶栏、方块卡片(PS5 风格)、封面
    ├── Screens/                # 主界面 / 播放器(WebView)/ 模拟器(EmulatorView)
    ├── Emulator/               # ROM 库分区 + 自绘虚拟手柄
    └── Overlay/                # 自绘浮层 + 添加 URL 表单 + 导入 ROM 浮层
Resources/
├── games.json                  # 内置兜底清单(默认为空)
└── Assets.xcassets

Vendor/mgba/                    # mGBA 源码(MPL-2.0),CI 里交叉编译成 arm64 静态库
Vendor/nestopia/                # Nestopia 源码(GPL-2.0-or-later),同上
Vendor/mesens/                  # Mesen-S 源码(GPL-3.0),同上
Scripts/build_cores.sh          # 编译核心 → build/cores/<平台>/(含 GSBuiltCores.h 开关)
build/cores/<平台>/             # 核心编译产物(lib*.a + 头文件,不提交)

用户数据:沙盒 Documents/games.json(App 内添加的条目)
         沙盒 Documents/ROMs/<系统>/(自己导入的 ROM 与 .sav 存档)

设计约束

  • 禁止系统弹窗:不使用 UIAlertController / NSAlert / NSPanel,所有提示、确认、输入表单都走自绘浮层。
  • 深色主题:近黑背景 + #1B1B20 卡片 + 橙色 #FF7A18 强调色,卡片带 #2A2A30 细描边。
  • 令牌集中:任何视图都不硬编码颜色尺寸,一律引用 Theme.*。

状态

主界面(PS5 风格方块行 + App 内添加 URL + 沙盒持久化 + URL 启动 + 手柄键鼠探测 + CI)已经可用, 模拟器部分 mGBA(GBA / GB / GBC)与 Nestopia(NES)已经能导入 ROM 并模拟 (画面 + 自绘虚拟手柄 + 声音;NES 画面 256×240,音频是单声道扩成立体声); Mesen-S(SNES) 的宿主适配也已完成、CI 里交叉编译并链接通过, 但本机没有 iOS 工具链、尚未实机实测(所以先按「已接入、待实机验证」对待,不写成「实测可玩」); NDS / 3DS / Wii / Wii U 的核心尚未接入,业务功能仍在补。 逐项完成度请看 REFERENCE.md 的「未完成清单」。

许可证

本仓库以 GPL-3.0 发布,全文见 LICENSE。 Vendor/ 下的第三方源码各自保留原许可:Vendor/mgba(mGBA)为 MPL-2.0, Vendor/nestopia(Nestopia)为 GPL-2.0-or-later(其每个源文件都写明可选用更高版本, 所以能按 GPL-3.0 一并分发),Vendor/mesens(Mesen-S)为 GPL-3.0。 Snes9x 不引入(非商用许可,与 GPL-3.0 不兼容)。 第三方组件与接入进度在 LICENSE 末尾与 REFERENCE.md 里如实列出。

About

Gameshell — iOS/iPadOS/macOS 游戏启动器 UI 壳(参考盖世游戏/GameHub,Swift + Obj-C 混合,URL 驱动,支持手柄与键鼠)

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages