Skip to content
HDZ123321Public

About

Slay the Spire 2 iOS port — v0.113.1 decompiled C#, NativeAOT pipeline, GitHub Actions IPA, Dynamic Island Live Activity, mod support

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

杀戮尖塔 2 · iOS 构建包

从 PC 版 Slay the Spire 2(v0.113.1,Godot 4.5.1 mono / .NET 9)反编译并重建的可移植工程, 面向 iOS 14+ 真机。在 Windows 上能做完的部分已经全部做完,剩下的必须 macOS + Xcode。


1. 这个目录里有什么

路径 大小 说明
sts2.pck 2.15 GB 完整资源包,17369 条目。纹理已同时含 ETC2(600 个)+ ASTC(973 个),iOS 直接可用
sts2.xcframework/ 355 MB Godot 引擎本体 libgodot.a(arm64 + simulator)
MoltenVK.xcframework/ 48 MB Vulkan → Metal 转译层(Godot 的 Mobile/Forward+ 渲染器走这条)
sts2.xcodeproj/ 21 KB Xcode 工程,已配好 arm64 / iOS 14.0 / 横屏 / 内嵌 PCK
sts2/ 294 KB app 外壳:Info.plist、entitlements、启动图、dummy 入口
BUILD_MACOS.sh 4 KB 一键构建脚本(6 步)
.github/workflows/ios.yml 9 KB GitHub Actions macos-15 自动出未签名 IPA
tools/patch_pbxproj.py 4 KB 把 sts2_aot.xcframework 接进 Xcode 工程

没有的东西:sts2_aot.xcframework —— 它是 dotnet publish -r ios-arm64 的 NativeAOT 产物, 必须在 macOS 上编译。这正是需要 Mac 的唯一原因。


2. 关键结论(先看这段,省得踩坑)

2.1 iOS 上 .NET 是走 NativeAOT,不是 Mono

Godot 4.2 起官方支持 C# 导出 iOS(标记 experimental)。Godot.NET.Sdk 4.5.1 在 RuntimeIdentifier 以 ios 开头时会自动 import iOSNativeAOT.props:

PublishAot                = true
PublishAotUsingRuntimePack= true
UseNativeAOTRuntime       = true
TrimmerSingleWarn         = false

C# 代码被 ILC 编译成一个 libsts2.dylib,再打成 xcframework 嵌进 app。 所以 libgodot.a 里搜不到任何 mono 运行时符号 —— 那是正常的。

2.2 三个必须的工程修补(源码里已包含,别删)

  1. src/_synthetic/AssemblyHasScripts.cs —— [assembly: AssemblyHasScripts]。 关掉了 Godot 源生成器,这个 attribute 就没人生成,缺了它 ScriptManagerBridge.LookupScriptsInAssembly() 直接 return,所有 C# 节点变成空 Node。
  2. src/_synthetic/{InlineArray*,ReadOnlyArray,ReadOnlyList,ReadOnlySingleElementList}.cs —— ilspy 导出的编译器合成类型,缺了报 1300+ 个 CS0400。
  3. src/_synthetic/PrivateImplementationDetails.cs —— switch 表达式异常辅助类,13 处调用点。

2.3 beforefieldinit 必须回填(本项目最隐蔽的坑)

ilspy 把「静态字段初始化器」还原成显式 static Xxx(),重新编译后类型失去 beforefieldinit。 后果:ModelDb.Init() 按 _subtypes 顺序逐个 Activator.CreateInstance, Darv(index 761)的 cctor 提前触发,而它要求 Astrolabe(index 1333)已在字典里 → KeyNotFoundException: 'RELIC.ASTROLABE',游戏卡在启动画面。

v0.113.1 上同一个坑换了张脸:BlitzRunModel(index 26)的 cctor 要 ModelDb.Enchantment<Sharp>(), 而 Sharp 在 index 804 —— KeyNotFoundException: 'ENCHANTMENT.SHARP'。判据完全一样: 反编译源码里那个 static BlitzRunModel() 是显式的,Roslyn 就生成精确类型初始化器。

已修:tools/BfiPatch/(Mono.Cecil)在编译后把这 8 个类型的标志打回去, sts2.csproj 里挂成 AfterTargets="CoreCompile" + BeforeTargets="CopyFilesToOutputDirectory;IlcCompile",全自动。 清单在 bfi_types.txt。校验方法:bfi+cctor 应等于 2568。

CI 会拦这一类回归:Verify BeforeFieldInit reached the ILC input 步骤除了 verify 清单里的 8 个类型, 还会断言 bfi+cctor 计数不低于 2568 —— 以后哪次反编译又冒出一个精确初始化器,构建阶段就 exit 1, 不会等到手机上才炸。

要自查是否还有同类隐患,用 _bfiscan(Mono.Cecil)双向比对上游与自建的 BeforeFieldInit 位, 再按 AbstractModelSubtypes 的数组序扫所有精确 cctor 里的 ModelDb.<T>() 调用; 两边都报 scanned PRECISE cctors: 0 才算干净。

2.3b 构造函数期读后建的模型(同一类坑的第二张脸)

ModelDb.Get<T>() 原本是裸的 _contentById[GetId<T>()]。ModelDb.Init() 按 _subtypes 顺序构造,所以任何构造函数里读一个排在自己后面的模型,都会当场 KeyNotFoundException。 这和 2.3 的 cctor 晚读是两件事:beforefieldinit 只管静态构造,管不到实例构造。

v0.113.1 上撞的是移植进来的观者卡:

[ERROR] KeyNotFoundException: The given key 'CARD.WATCHER-BETA' was not present in the dictionary.
  at ModelDb.Get[T]()
  at HoverTipFactory.FromCard[T](Boolean upgrade)
  at HoverTipFactory.FromCardWithCardHoverTips[T](Boolean upgrade)
  at Watcher.Code.Cards.Rare.Alpha..ctor()
  at ModelDb.Init(Type[] injectedModelTypes)

Alpha 在 index 1867,它构造函数里要 Beta(index 1871)的悬浮提示,晚 4 位。

已修:Get<T>() 与非泛型 Get(Type) 未命中时回落 TryResolveMissing,按需构造。 TryResolveMissing 里 _resolving.Contains(id) 挡住自我递归,所以构造中的模型不会被重入; 彻底找不到仍抛 ModelNotFoundException,不是裸字典异常。

要自查同类隐患用 _ctorcan(Mono.Cecil):按 _subtypes 数组序走每个类型的实例构造函数, 沿本程序集内的调用递归(默认 4 层)并传播泛型实参,报出所有 ModelDb.<T>() 晚读。 当前构建只剩 Alpha → Beta 这一处,已被延迟解析兜住;上游 DLL 是 problems: 0。

2.4 纹理格式:PCK 里原本只有 S3TC/BPTC,iOS 用不了

原版导出给 Windows,纹理只有 s3tc/bptc 变体。iOS 的 GPU 不支持 BC 格式, Godot 会运行时 image->decompress() 转 RGBA8 —— 不崩,但 1.86 GB 纹理会膨胀到约 3.5 GB 显存。

已修:把 1573 个压缩纹理(BPTC 973 + DXT5 542 + DXT1 58)从 ctex 反解回 RGBA8, 再用 Godot 的 Image.compress() 重新压成 iOS 能直接采样的格式,手工拼回 .ctex 容器:

原 .bptc 变体 → ASTC 4x4(fmt=35)
原 .s3tc 变体 → ETC2 RGBA8 / RGB8(fmt=31 / fmt=30)
原本未压缩的 2452 个 → 原样保留(fmt=5 / fmt=4)

iOS preset 的 feature 集合是 {etc2, astc, arm64}(见 editor/export/editor_export_platform_apple_embedded.cpp:51-53),导出器会按 feature 自动选对的那套。 现在 PCK 里 ASTC 973 个(807 MB)+ ETC2 600 个(179 MB)。重烤脚本是 texdump/recook.gd (Godot headless 跑,1573 个约 3 分钟,done=1573 failed=0)。

.ctex 容器格式(compressed_texture.cpp 的 _load_data)是 36 字节头 + 16 字节 image 头 + 裸 GPU 数据:

"GST2" | u32 version=1 | u32 w | u32 h | u32 df | u32 mipmap_limit | 3 x u32 reserved   (36 B)
u32 data_format=0 | u16 w | u16 h | u32 mipmaps | u32 format | payload                    (16 B + N)

data_format=0 时文件体就是裸的压缩数据,没有额外长度前缀 —— 所以不需要编辑器导入器也能手工拼。

2.5 导出器会丢弃「源文件不存在」的 .import

.import / .remap 只有在源文件存在时才被打包。原 PCK 剥掉了源图, 导致 4024 个纹理 .import 被静默丢弃,连带 177 .spatlas + 169 .spskel + 22 .fontdata + 7 image + 1 svg + 1 scene。 症状是 Resource file not found: res://fonts/kreon_bold.ttf。

已修:pack_pck.py 直接从解包树重建 PCK,把 4465 个 .import 与全部 artifact 原样写回, 只替换纹理变体那 1573 条 remap 目标。挂载验证:ctex=4025 ok=4025 failed=0 pixels=2021377134。

2.6 触屏

InputEventScreenTouch 在原代码里 0 命中,全靠 Godot 默认的 emulate_mouse_from_touch(单指 → 鼠标左键)。 但「右键看详情」和「ESC 返回」在 iOS 上没有触发方式,所以加了 src/Core/Touch/TouchInputAdapter.cs:

手势 映射
单指长按 550ms(位移 < 14px) 右键按下 + 抬起 → 打开卡牌/遗物详情
双指轻点(260ms 内) ui_cancel → 关闭面板 / 返回
其余 放行,交给引擎的触摸转鼠标

已注册为 autoload(project.godot 第 35 行)。

2.7 外部组件(哪些进了 App,哪些还是降级)

组件 状态 处理
Spine 已恢复(v6 起) spine-godot framework 随 sts2-frameworks.zip 一起发并链接进 App;C# 侧本来就是字符串反射,缺了只是动画降级,不崩
FMOD 已恢复(v7 起) fmod iOS framework 随 frameworks.zip 发;LC_LOAD_DYLIB 改 LC_LOAD_WEAK_DYLIB 指向 @rpath/fmod-disabled.framework/fmod-disabled(tools/disable_dylib_path.py),再把 flat-namespace 的 30 个 import 改弱绑定(tools/weaken_fmod_bind.py,bind opcode 0x40→0x41)。framework 缺失或版本不匹配时是静音,不是启动即 dyld 崩
Sentry 仍然关闭 SentryService 在 OS.HasFeature("mobile") 时直接 return——原生 sentry 库不在这个 build 里
Steam 无 iOS SDK 走 Platform.Null 分支,单机可用

N_WEAK_REF 那条路走不通:dyld4 只认 bind opcode 的弱绑定位,改 Mach-O 符号表没用——这是当时连续几次启动崩溃的根因。

fmod 还有一层只在 PCK 里才会犯的坑:游戏原版 addons/fmod/fmod.gdextension 把 iOS 库写成 libGodotFmod.ios.template_release.xcframework,而 Godot 判定静态库的规则是 path.ends_with(".a") || path.ends_with(".xcframework")(gx_gdextension_library_loader.cpp:364)。 .xcframework 被当成静态库后走 open_dynamic_library(""),iOS 实现在路径为空时直接返回 RTLD_SELF,接着 dlsym(RTLD_SELF, "fmod_library_init") 必然失败,日志是 GDExtension entry point 'fmod_library_init' not found in library .(库路径是个空串)。 症状不是崩,是整个 FMOD 扩展没加载:FmodServer 等四个类全部 class_exists = False, FmodManager.gd 满屏 Parse Error: Identifier "FmodServer" not declared。

所以 pack_pck.py 有一张 OVERRIDES 表,把仓库里那份指向 .framework 的 addons/fmod/fmod.gdextension 覆盖进 PCK;CI 的 Verify PCK present 步骤会读回这一条, 只要里面还出现 .xcframework 就直接 exit 1。

2.8 卡图替换:两套 Regent 立绘,启动时选一套

储君(Regent)的卡图有两条上游 mod,都是 Harmony DLL,AOT 里跑不了,所以由工具把美术从它们的 PCK 里抽出来重新烤成两个独立包,跟着 App 一起发:

包 上游 mod 卡数 包内命名空间 重烤工具
res/RegentArt.pck RegentCardsAnimeRework 1.0(动漫风) 94 res://generated/assets/card_art/ tools/regent/build_regent_art.py
res/RegentFemArt.pck RegentFemPortraits 1.0(娘化,Regent 760) 60 res://RegentFemPortraits/card_portraits/ tools/regent/build_regent_fem_art.py

两个包各自的 res:// 命名空间不重叠,所以能同时躺在 bundle 里;src/Core/Modding/RegentCardArt.cs 在 OneTimeInitialization.ExecuteVeryEarly 里一次挂载,CardModel.PortraitPath 按 CLR 全名查当前那套的表,没覆盖到的卡继续用原版图集精灵。

切换靠 user://regent_art.txt(iOS 上就是 App 的「文稿」目录,用「文件」App 可改)。第一行 fem(默认)或 anime,改完重启生效;文件不存在、内容不认识、或者对应的包没打进 bundle,都会退回默认那套。

上游包里那两份 res://.godot/uid_cache.bin / global_script_class_cache.cfg 必须在烤包时丢掉——挂载带它们的包会让引擎从包里重读 UID 缓存,把本体的 uid:// 引用全部盖掉。

2.9 手机上的发热与帧率:一次性的省电档

抓日志看到的现象是这台机器在 120 Hz 屏上跑满帧、机身发烫。原因不在 C# 每帧逻辑(全工程的 _Process 方法体都扫过,最长的 1.5 KB,_PhysicsProcess 一个都没有),而在渲染带宽,且历史构建从来没动过 steady-state 帧循环。三处改动:

改动 位置 为什么
MSAA 关掉(Msaa: 2 → 0) src/Core/Helpers/MobileGraphicsProfile.cs 2D 渲染器开 MSAA 只是把采样带宽翻倍,没有可见收益。原来 SettingsSaveManager.ApplyPlatformDefaults 只在新建存档时设 Msaa=2,老存档永远带着它
帧率钳到 [30, 60] 同上 + NFpsPaginator 设置界面的档位到 500,ProMotion 会真的去追;Engine.MaxFps 在 iOS 上经 swapchain 生效,不是空设
VSync 固定 On 同上 原来是 Adaptive,帧时抖动时白烧功耗

ApplyOnce 写在 user://mobile_profile_v1.txt 里的标记只写一次:升级后第一次启动改一次,之后玩家自己把 MSAA 开回去就不会再被覆盖。想重跑就把那个文件删掉。

可选:按设计画布渲染(默认关)

user://render_scale.txt 第一行写 design(或 canvas,或任意 0 < x < 1 的浮点数),重启后从 canvas_items 切到 viewport 拉伸,渲染目标就是 1920×1080 设计画布,再双线性放大到屏幕;iPhone 2796×1290 上相当于 0.70× 像素。

要点:canvas_items 下怎么设 ContentScaleSize 都不省像素——Window::_update_viewport_size() 里 final_size = screen_size,永远物理分辨率;只有 viewport 模式才 final_size = (viewport_size / content_scale_factor).floor()。切过去之后 canvas 坐标系不变(两边都是 viewport_size),所以布局和触摸目标一动不动,代价只是 1.19× 的轻微软化。写 1 或删文件即回原样。

怎么量

手机上 Perf 是自动开的(MobileDevice.IsMobile 即启用),每 1800 帧(约 30 秒)打一行:

[Perf] frames=1800 avg=8.31ms fps=120.4 max=19.7ms hitch=0 proc=1.92ms phys=0.00ms draw=84 obj=612 nodes=2174 gc0=0 gc1=0 gc2=0 managed=61MB vram=214MB

proc(C# 每帧时间)远小于 avg 就是 GPU 受限;draw/obj 高则先砍绘制批次。想看更密的报表用 --perf 启动(600 帧一行),想彻底关掉用 --noperf。桌面端默认不开,--perf 才开。

卡顿归因:hitch 行带阶段标签

帧报表只说了「有几次长帧」,说不出长在哪。所以超过 HitchThresholdMs(33 ms)的帧会单独打一行,带上当前阶段标签(每个报表窗口最多 12 行,总量仍由 hitch= 计):

[Perf] hitch 187.4ms phase=combat.enemies scene=NCombatRoom proc=41.2ms nodes=2310 draw=126 vram=268MB managed=64MB

phase 是 Perf.Phase("...") 设的短标签,战斗进入这条链上埋了这些点:

阶段 覆盖的工作
map.travel / map.arrive 点地图点后的镜头平移,到房间真正开始之前
combat.generate 生成怪物与站位
combat.preload PreloadManager.LoadRoomCombatAssets 的等待
combat.creatures CombatState.CreateCreature × N
combat.create-room combat_room.tscn 实例化
combat.room-ready / .allies / .enemies / .room-ready.done NCombatRoom._Ready 的各段
combat.creature-node 每个 NCreature 节点创建
combat.populate / register-creatures 玩家战斗状态、手牌进 DB
combat.combat-setup-hooks / ui-activate / background UI 激活、能量球、场景背景
combat.bgm / after-creature-added 战斗音乐(FMOD bank)、每只怪的入场

判读:proc 小、draw/vram 跳高 → GPU 侧(纹理上传或首次 PSO);proc 大 → 主线程同步干活(实例化、Spine 建骨、卡面解码)。

单帧 hitch 行最多 12 条,而进战常常是一串刚过 33 ms 的帧。所以每行帧报表末尾按阶段汇总这一窗口里超阈值帧花了多少时间(前 3 名):

[Perf] frames=1800 avg=8.44ms fps=118.5 max=41.2ms hitch=17 proc=2.03ms ... managed=63MB vram=241MB hitchby=combat.enemies:214ms spine.ready:96ms combat.room-ready:41ms

hitch= 是次数,hitchby= 是归属。两个数字一起看就知道是「一场战斗进战时抖了十几下」还是「全程平均」。

进战这条链的总账从点地图点那一刻开始算(MapRoom 之前那段 map.travel),到 combat.after-room 结束,所以 total 就是玩家手感上的「点了之后等了多久」。

另有两个不在调用链上、但仍会出现在进战后几帧里的标签:spine.ready(某只怪的 SpineSprite 把骨架建完、图集页上传完的那一帧,之前是空白)和 combat.banner(「战斗开始」横幅的 MegaLabel 自适应字号二分重排)。

hitch 只在某一帧真的超过 33 ms 时才有输出,而进战卡顿常常是一串二十几毫秒的帧叠出来的。所以进战这条链跑完时还会多打一行阶段总账(Perf.ReportPhases,在 CombatRoom.StartCombat 末尾和 StartPreFinishedCombat 末尾各调一次):

[Perf] combat entry total=1290ms max=64.0ms hitchby=combat.creatures:96ms spine.ready:41ms map.travel=142ms map.arrive=28ms combat.generate=3ms combat.preload=812ms combat.creatures=44ms combat.create-room=171ms combat.room-ready=48ms combat.creature-node=12ms combat.creature-node=9ms combat.creature-node=11ms combat.ui-activate=26ms combat.background=31ms combat.bgm=4ms combat.after-creature-added=18ms

数据怎么从手机里拿出来

上面这些行除了进日志,还会被镜像到 combat_perf.txt —— 因为 iOS 上应用容器里的 godot.log 极难取,而这份文件落在 Documents 目录(App 已声明 UIFileSharingEnabled + LSSupportsOpeningDocumentsInPlace),在文件 App → 我的 iPhone → sts2 里直接能看见、能分享出来。

内容就是同样的行,前面加时间戳,每次启动写一行 header:

=== session 2026-11-05 20:31:07 engine=4.5.1-stable (official) os=iOS model=iPhone18,2 renderer=mobile fps=60 ===
20:31:09.114 [Perf] frame watch started (report every 1800 frames)
20:31:41.882 [Perf] frames=1800 avg=8.44ms fps=118.5 max=22.1ms hitch=0 proc=2.03ms ...
20:33:02.517 [Perf] combat entry total=486ms combat.generate=3ms combat.preload=141ms ...

超过 128 KB 自动轮转一次,只保留最后 400 行(前面补一行 (rotated, N older lines dropped)),所以跑一整天也不会把手机塞满。--noperf 时整个镜像一起关掉。

要定位卡顿,只需要把这个文件(或者其中带 combat entry / hitch 的几十行)发出来,不必设法去捞 godot.log。

2.9.1 进战预热:怪物节点提前一帧一个建好

NCombatRoom._Ready 建房间时,每只怪的 NCreature.Create 都在同一帧里跑 —— PackedScene、visuals 子场景、纹理全都要在那里实例化,敌人越多这一帧越重。现在这部分搬到 CombatRoom.StartCombat 的 combat.prepare-nodes 阶段:NCombatRoom.PrepareCreatureNodes(CombatState) 在地图还在屏幕上的时候,每帧建一只,先不挂进树;等房间真正创建时,AddCreature 直接从预备表里取,只做挂载。

房间本身也一样:combat_room.tscn 有两千多个节点,Instantiate() 是原子的、拆不开,所以给它单独一帧——NCombatRoom.PrepareRoom 在地图还在的时候就把房间树建好,NCombatRoom.Create 直接取走。combat.create-room 那一步于是只剩「换场景」。

站位场景也跟着建:手摆敌人的 encounter 自带一个 slots 场景(EncounterModel.CreateScene()),实例化它同样是几百个节点,原来也在 _Ready 的 combat.enemies 里。PrepareRoom 现在一起建好,CreateEnemyNodes 取走。

玩家节点现在也算在内。PrepareCreatureNodes 原来跳过了 creature.IsPlayer,理由是「玩家走 CreateAllyNodes」——但 CreateAllyNodes 里也是调 AddCreature,同一条路,而可玩角色的 visuals 场景往往是全场最重的一套图集。现在它跟敌人一样提前建好。

背景跟着房间一起建:NCombatBackground.Create 会按 BackgroundAssets.BgLayers 逐层实例化视差层场景(每层都带自己的大图),原来也挤在 combat.background 那一格里。PrepareRoom(visuals, mode, runState) 现在把背景一起建好挂在预备位上,SetUpBackground 直接取走再挂进 BgContainer。安全前提是背景的层组只由 Encounter 和 new Rng(runState.Rng.Seed + 当前地图点) 决定(GenerateBackgroundRngForCurrentPoint),不碰全局 RNG,且 BackgroundAssets 本来就缓存在 EncounterModel 上——提前算一次和晚算一次结果一样。

时序没变:_Ready 仍然在 SetCurrentRoom 那一帧跑,入场动画、血条 SpawnedAtCombatStart 判定都照旧。变的只是「资源实例化」提前了几帧,并且分散开了。没用掉的预备节点在 _Ready 末尾统一释放,房间退出时 CombatRoom.Exit 再兜一次底。

关掉它做对照:写 user://combat_prewarm.txt,内容 off(大小写不敏感),下次进战就退回老的单帧路径。

读法:total 是整段真实墙钟(含 await 的空帧),每项是两个标签之间的时间。行尾的 max= 是这段里最慢的一帧,hitchby= 是这段里超阈值帧的时间归属(前 3 名),所以一行就能回答「点了之后等了多久、最卡那一下在哪一阶段」,不必再和 30 秒窗口的帧报表对表。combat.preload 里包含后台加载让出的帧,所以它大不代表卡;真正要看的是同一帧里干完的那几项——creatures / create-room / room-ready / 重复出现的 creature-node 加起来接近某次 hitch 的毫秒数,就是它。这样即使一帧都没超过 33 ms,也能看出时间被谁吃了。

已经因此改掉的两处(同一提交):

改动 位置 为什么
房间加载后的全量 GC.Collect() 在移动端改成不等结果 src/Core/Assets/PreloadManager.cs CollectIfHeapGrew 它就落在进房间的转场帧上,5–20 ms 的停顿正好被玩家看见。GC.Collect(2, Forced, blocking: false) 照样回收,只是不在绘制那一帧上等
意图动画帧并入 run 资产集 PreloadManager.GetRunAssetPaths + IntentAnimData.AssetPaths AbstractIntent.AssetPaths 只报了静态图标,动画帧每次进战全部 miss,走 AssetCache 的同步 ResourceLoader.Load
自适应字号的拟合结果做记忆化 addons/mega_text/MegaLabel.cs _fittedSizes 拟合是二分搜索,每一步都把整段字重新 shaping,中文尤其贵。战斗开始时血条、名牌、意图、横幅一起出现,几十个新 label 问的是同一批 (文本, 字体, 矩形),缓存命中后一次 shaping 都不做

进战之后还有一条单独的总账,因为「刚开始打怪」的手感往往落在房间已经出现之后:SetupPlayerTurn 末尾打 [Perf] combat turn setup total=<ms> combat.hand-draw=<ms> ...,其中 combat.hand-draw 包住 CardPileCmd.Draw —— 起手五张牌就是这个阶段一张一张建节点出来的。等到 StartCombatInternal 里逐只怪 await AfterCreatureAdded 的那段,也按 combat.creature-added 记账。

2.10 灵动岛:跑图状态挂在 Live Activity 上

iPhone 14 Pro 以后的机型(含 17 Pro Max)在 App 外能看到一条「第 X 幕 第 Y 层 · HP 32/80」的实时活动。实现刻意避开两处最容易翻车的地方:

C# 不直接调 Swift。 NativeAOT 镜像里 DllImport 打到主镜像的 Swift 符号,这条路在本机完全无法验证(成了就是成了,不成就整个启动段崩),所以走文件通道:

C#  DynamicIslandReporter  每秒(只在内容变化时)写 user://island_state.json
                                 ↓  0.5 s 轮询
Swift Sts2IslandBridge     读文件 → Activity.update() / Activity.request()

写失败只丢灵动岛,一帧都不影响。文件内容是一行 JSON:{"seq":12,"active":true,"hp":32,"maxHp":80,"floor":7,"act":2,"gold":143,"character":"铁甲战士","avatar":"island_avatar.png"};不在跑图时 active 为 false,扩展收到就把活动结束掉。

角色 2D 形象跟着状态一起传。 扩展进程有自己的沙盒,读不到 Godot 的 user://;这个构建又是 ad-hoc 签名,拿不到 App Group 去共享容器,所以图片只能塞进 ContentState.avatar(Data)走系统通道:

IslandAvatar.Ensure(角色)   角色变了才编码:取 char_select 立绘(回落 top_panel 图标)
                            → 解压 → 裁正方形 → 长边缩到 132 px → user://island_avatar.jpg
Swift Bridge                读字节(按 size+mtime 缓存)→ ContentState.avatar
Widget IslandAvatarView     Image(uiImage:) 圆环裁切;缺失就退回落一个 figure.stand 符号

硬上限是 4 KB,不是 48 KB。 ActivityKit 把 attributes + contentState 归档后有 4096 字节的硬限制, 超了 Activity.request 直接抛 ActivityAuthorizationError.attributesTooLarge,整个 Live Activity 根本不出现 (症状就是「灵动岛一点反应都没有」,日志里连一行都没有)。所以编码走两级阶梯,预算 BudgetBytes = 3000:

边 132/112/96/80/64/48 px  ×  JPEG 质量 0.85/0.7/0.55/0.4/0.28
先 JPEG(小图省得多),全部超预算再退 PNG;仍超就不带头像发

Sts2IslandBridge 里还有第二道保险:for attempt in [avatar, nil] —— 带头像的 request 失败就无头像重试一次, 成功时把 avatarCache 清空,下次不再走同一条死路。展开态左侧、紧凑态前区、极简态、锁屏左侧都用这张图。

扩展不建 Xcode target。 tools/build_island_extension.py 用 swiftc 直接编出 .appex 塞进 sts2.app/PlugIns/,版本号从主 app 的 Info.plist 回填。值得记的三件事:

细节 为什么
-Xlinker -e -Xlinker _NSExtensionMain 扩展入口不是 main();不指定的话系统启动扩展时立刻崩
-Xlinker -application_extension 缺 MH_APP_EXTENSION 标记,系统以 "not a valid extension" 拒掉整个 bundle
IPHONEOS_DEPLOYMENT_TARGET 保持 14.0,但 -weak_framework ActivityKit + -Xfrontend -disable-autolink-framework -Xfrontend ActivityKit ActivityKit 是 16.1 才有的库。强链接会让 dyld 在旧系统上拒绝启动 App;Swift 的 autolink 会把它链接成强引用,所以必须从两头掐掉。代价只是旧系统没有灵动岛

app 侧因此必须开 Swift:tools/patch_app_sources.py 往 project.pbxproj 里补三个源文件、SWIFT_VERSION = 5.0、上面那两个链接设置(跑两遍结果一样)。sts2/dummy.cpp 的 godot_apple_embedded_plugins_initialize() 与 Sts2IslandBootstrap.m 的 +load 各触发一次 sts2_island_bootstrap(),两处都幂等。

排查时先看 user://island_status.txt(和日志同目录):扩展侧拿不到授权、请求失败、活动结束都会在那里留一行带时间戳的记录,同时进 NSLog。

2.11 iPhone 17 Pro Max(6.9",1320×2868)

这块屏不需要单独的代码路径——布局全走 canvas 坐标系——但有三件事值得写下来:

  • 横向安全区:灵动岛在横屏时压住一侧,DisplayServer.GetDisplaySafeArea() 报的 insets 会非零,NGame.ApplySafeArea() 已经按 uniformScale 换算成 canvas 单位并缩进 UI。启动日志里那行 [Display] model=... safeInsetsPx=... safeInsetsPt=... 就是这件事的自证,换机型后先看它。
  • 帧率:这块 120 Hz 屏正是 §2.9 那套省电档的目标,Engine.MaxFps 被钳在 60,MSAA 关掉。
  • 分辨率:原生渲染是 3.8 MPx。想要更省电就在 user://render_scale.txt 写 design(见 §2.9),画面从 1920×1080 放大,布局与触摸目标不动。

2.12 iPad Air(4:3 画布)

TARGETED_DEVICE_FAMILY 一直是 "1,2",Info.plist 里 UISupportedInterfaceOrientations~ipad 也一直有,所以 iPad 本来就能装能跑。真正没做的是按 4:3 布局——之前所有坐标都假设可见画布是 1920×1080。

canvas_items 拉伸 + expand 宽高比下,可见画布是「按高度贴合设计高度、宽度按屏幕比例扩展」:

设备 屏幕 可见画布
iPhone 17 Pro Max 2868×1320(2.17:1) 2346×1080
iPad Air 13" 2732×2048(4:3) 1920×1440
iPad Air 11" 2360×1640(4:3) 1920×1440

也就是说手机上宽度比设计画布多 426 px,平板上高度比设计画布多 360 px。所有拿 1920×1080 当屏幕尺寸用的地方,在这两种设备上都是错的,只是错的方向不同。修的是这几处:

  • NCombatRoom.CreateEnemyNodes():EncounterSlots.Position -= new Vector2(1920f, 1080f) * 0.5f → -= SceneContainer.Size * 0.5f。遭遇战槽位场景是以左上为原点的 1920×1080 布局,容器锚在中心,减半个设计画布只在 16:9 上对得上;4:3 上整组敌人偏低 180 px。
  • NCombatRoom.PositionEnemies():960f / scaling → SceneContainer.Size.X * 0.5f / scaling。敌人是围绕场景水平中心排的,用字面 960 在宽手机上整排偏左。
  • NCombatRoom.PositionPlayersAndPets():签名加了 float canvasWidth = 1920f(默认值保证 mod 调用者不用改),内部 960f 换成 canvasWidth * 0.5f,唯一调用点传 SceneContainer.Size.X。
  • NTargetingArrow:两处 540f(From.Y > 540f 选贝塞尔控制点在箭头上方还是下方、箭头首段朝向)换成 MidlineY 属性,取 GetViewport().GetVisibleRect().GetCenter().Y。4:3 上真中线是 720。
  • NCardFlyShuffleVfx._Ready():_arcDir = ((_endPos.Y < 540f) ? ...) 同理,改用可见矩形中心。

帧率:平板 Engine.MaxFps 钳到 120 而不是 60(MobileGraphicsProfile.TabletMaxFrameRate),设置里的帧率分页器也随之钳到 120。MSAA 在平板上和手机上一样保持关闭——2D 游戏多采样只花带宽不换画质。这两条都写在 SettingsSaveManager.ApplyPlatformDefaults 的 IsTablet 分支里,只对新存档生效。

触摸目标:MobileDevice.MinimumTouchTarget 按 44pt 换算成画布像素。4:3 平板上一 pt 对应的画布像素比宽手机少,所以算出来的命中框反而更小——但 NClickableControl.BuildTouchHitRect 只放大不缩小(上限 1.5×),不会把本来就够大的按钮改小。


2.13 取消选取 / 取消出牌

触屏上「选错了想退出来」原来几乎做不到,两条路都是给鼠标设计的。

手牌选择模式(NPlayerHand.SelectCards,弃牌、消耗、变化、升级都走这条)原来根本没有退出入口:CancelHandSelectionIfNecessary() 唯一的调用点是 AnimOut(),也就是战斗结束。对比之下牌库选择屏(NDeckCardSelectScreen)一直有 _closeButton,_prefs.Cancelable 控制它显不显示。现在手牌屏补了三条:

  • 点 SelectModeBackstop 那层全屏暗色遮罩即取消(它原本 MouseFilter = Stop 只是挡输入,什么都不做)
  • ui_cancel 也取消(iOS 上是双指轻点,桌面上是 ESC)
  • 两条都走新增的 public void CancelCardSelection(),TrySetResult(Array.Empty<CardModel>()) 而不是 SetCanceled() —— CardSelectCmd.cs:694 和 :779 两个调用点都没有 catch TaskCanceledException,走 SetCanceled() 会把异常抛进战斗流程。返回空列表的语义与牌库屏的 CloseSelection 一致,调用方本来就要处理「一张都没选」。

CardSelectorPrefs.Cancelable 默认 false,而且绝大多数卡牌/事件/遗物调用根本不设这个字段。所以不能拿它当「显不显示取消入口」的判据,否则弃牌、消耗、变化、升级这些牌全都没有取消入口。手牌选择一律允许取消。

战斗里拖动卡牌:取消区是「可玩区底部 5%」,_cancelZoneScreenProportion = 0.95f。17 Pro Max 上那是 54 画布像素,一根拇指盖住的面积就超过它。触屏上改成底部 15%(0.85f),桌面保持 0.95;判定走 MobileDevice.IsTouchOnly,是 static readonly 字段所以只算一次。取消区仍然远在出牌区(底部 25%)下方,只有刻意往下拖才会进。

双指轻点:TouchInputAdapter.TwoFingerTapSeconds 从 0.26 s 放宽到 0.60 s。0.26 s 是从第一根手指落下开始算的键盘手反应时间;双指按住一拍再抬起才是人在触摸屏上的实际动作。0.60 s 仍然远短于 0.55 s 长按之外的另一套判定(长按是单指静止 0.55 s,双指时 _points.Count != 1 直接跳过),两者不会互相干扰。

快速点击丢失:NClickableControl.HandleMousePress/Release 原来都要求 IsFocused,而 IsFocused 由 _isHovered || _isControllerFocused 决定,_isHovered 只由 MouseEntered 维护。触屏上 MouseEntered 是引擎从触摸合成出来的,不保证在按下之前到达。手指快速点一下,按下和抬起两个处理器都不跑,什么都不发生。现在触屏构建走新增的 CanAcceptPointer()(只要求 _isEnabled && IsVisibleInTree()),并且 HandleMousePress 开头会把控件提升为 hovered 再刷焦点——下游的 NCardHolder.OnMouseReleased 是靠 _isHovered 判定的,不补这一步卡片点选仍然会被丢掉。


3. 构建方式 A:本地 Mac

# 0. 准备
export TEAM_ID=ABCDE12XYZ              # 你的 Apple Developer Team ID(10 位)
export BUNDLE_ID=com.yourname.sts2     # 反向域名
cd /path/to/build_ios5

# 1-6. 跑脚本(内部依次做 publish / xcframework / patch pbxproj / archive / export)
chmod +x BUILD_MACOS.sh
./BUILD_MACOS.sh

产出 build/ipa/sts2.ipa。

前提:

  • Xcode 15+(xcode-select -p 指向它)
  • .NET 9 SDK
  • 如果 TEAM_ID 留空会走未签名分支,只出 .xcarchive

4. 构建方式 B:GitHub Actions(无需自备 Mac)

把 ci_bundle/ 的内容推到 GitHub 仓库,.github/workflows/ios.yml 会在 macos-15 上跑完全流程, 产出未签名 IPA 作为 artifact。

4.1 sts2.pck 怎么进仓库

iOS 用的 sts2.pck 是 2.15 GB(2,149,457,068 字节 / 17369 条目),超过 GitHub 单文件 100 MB 和 单 release 资产 2 GiB 两条限制(超了 176 MB),所以 release 上放的是 deflate 过的 sts2.pck.zip (1,286,223,114 字节,压缩率 0.598),CI 下载后 unzip 再校验 GDPC 头与 file_base。 workflow 里的 Fetch sts2.pck from release 已经这么做了,本地已有 sts2.pck 时自动跳过。

路线 1 — Git LFS

git lfs install
git lfs track "*.pck"
git add .gitattributes sts2.pck
git commit -m "add pck via lfs"
git push

workflow 里已经开了 with: lfs: true。

路线 2 — Release 资产(更省 LFS 配额) 把 sts2.pck 传到一个 Release,然后在 workflow 的 Verify PCK present 步骤前插一段:

      - name: Fetch sts2.pck from release
        run: |
          curl -fL -o sts2.pck.zip \
            https://github.com/<owner>/<repo>/releases/download/v0.113.1-ios/sts2.pck.zip
          unzip -q sts2.pck.zip -d .
          rm -f sts2.pck.zip

4.2 仓库结构

.
├── .github/workflows/ios.yml
├── sts2.csproj          # Godot.NET.Sdk/4.5.1
├── sts2.sln
├── bfi_types.txt
├── nuget.config
├── nuget_local/         # Godot.NET.Sdk / GodotSharp / Godot.SourceGenerators nupkg
├── libs/                # 12 个引用 DLL(Sentry/Steamworks.NET/0Harmony/SmartFormat/…)
├── src/                 # 3420 个 .cs(含 src/_synthetic/ 与 src/Core/Touch/)
├── addons/mega_text/    # 4 个 .cs
├── RiderTestRunner/     # 2 个 .cs
├── tools/BfiPatch/      # beforefieldinit 回填工具
├── tools/patch_pbxproj.py
├── tools/patch_app_sources.py          # 把灵动岛的 Swift/ObjC 挂进 app target
├── tools/build_island_extension.py     # swiftc 手工组装 .appex
├── sts2.xcodeproj/
├── sts2/                # 导出模板 + island/(灵动岛源码与扩展 Info.plist)
├── PrivacyInfo.xcprivacy
└── sts2.pck

libs/ 里的 DLL 来自正版游戏安装目录 data_sts2_windows_x86_64/,不随仓库分发。


5. 装到 iPhone / iPad

拿到 sts2-unsigned.ipa 后,按 iOS 版本选:

工具 适用 说明
Sideloadly iOS 任意版本 用你的 Apple ID 免费签名,7 天有效,到期重签;需开「开发者模式」
AltStore / SideStore iOS 14+ 同上,但支持自动续签(SideStore 无需常连电脑)
TrollStore iOS 14.0–16.6.1 / 17.0 永久签名,无需账号,最省事
付费开发者账号 任意 证书 1 年有效,可用 BUILD_MACOS.sh 直接出签名版

必读:

  • 游戏是横屏,UISupportedInterfaceOrientations 是 [LandscapeLeft, LandscapeRight](两个方向都开,可以翻面玩); display/window/handheld/orientation 在 project.binary 里被设成 4(Sensor Landscape),否则引擎默认会锁死单方向
  • 首次启动需要几十秒建缓存(要解压 PCK 里的纹理)
  • 存档路径 user://。Godot 的 Apple 嵌入式实现(os_ae.mm 的 OS_AppleEmbedded::get_user_data_dir)用的是 NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, ...),所以真机上是 <app 沙盒>/Documents/,配合 UIFileSharingEnabled + LSSupportsOpeningDocumentsInPlace 直接在「文件 → 我的 iPhone → sts2」里可见(combat_perf.txt、island_state.json、mods/ 都在那儿)

6. 已知限制

  1. 音效取决于 framework 落位 —— FMOD framework 没进 bundle 时静音(弱链接,不崩)
  2. Spine 动画同理 —— framework 缺失只是退化到静态帧
  3. 无多人联机 —— Steam 传输层不可用,单机全功能
  4. 模拟器跑不了 —— 需要 compatibility 渲染器;当前工程用默认 forward_plus。 真机 arm64 没问题
  5. 首次加载慢 —— 2.15 GB PCK(17369 条目,4025 个 ctex),A19 Pro 上约 20–40 秒
  6. audio_manager_proxy.gd 报 Parse error —— 这不是 .gdc 的问题,是 FMOD 扩展没加载时 FmodServer 等类不存在导致的连带报错(见 §2.7)。fmod.gdextension 的 .framework 覆盖进 PCK 后 这些报错全部消失,FMOD Sound System: Successfully initialized 会出现在日志第 4 行
  7. 灵动岛要 iOS 16.1+ —— ActivityKit 的下限;旧系统上 App 正常跑(弱链接), 只是没有实时活动。另外必须在「设置 → 杀戮尖塔 2 → 实时活动」里允许, 扩展侧被拒时会在 user://island_status.txt 里写明原因。头像有 4 KB 硬上限 (ActivityKit 归档上限 4096 字节),超了就自动降级成无头像,不会让整个活动消失
  8. Steam 初始化在 mobile 上被跳过 —— NGame.InitializePlatform() 的条件里带了 OS.HasFeature("mobile"),否则会卡在一个永不可能成功的 Steam 初始化上。 日志里的 Steam initialization skipped (editor mode) 是预期行为,不是错误

7. 版本与来源

项 值
游戏版本 v0.113.1 / commit d09d48e5
引擎 Godot 4.5.1-stable mono(MegaDot 定制版)
运行时 .NET 9.0.7 → NativeAOT
反编译 ilspycmd 10.1.0.8386,3888 个 .cs,无混淆
PCK 格式 packver 3, flags 0x2, file_base 112, 无加密
桌面验证 Time to main menu: 4,479ms,Cannot instantiate = 0
CI run 44020550579(28 步全绿,6d619bd)
纹理校验 ctex=4025 ok=4025 failed=0(ASTC 973 + ETC2 600 + 未压缩 2452)

About

Slay the Spire 2 iOS port — v0.113.1 decompiled C#, NativeAOT pipeline, GitHub Actions IPA, Dynamic Island Live Activity, mod support

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages