简体中文 ｜ English

Slay the Amethyst

一个面向 模组版 Slay the Spire 的 Android 启动器项目，在移动端运行大部分桌面版模组

核心特性 • 快速开始 • 构建说明 • 文档入口 • 仓库结构 • 致谢

[!IMPORTANT] 本仓库不包含私有构建依赖。构建前请按下文在 build-deps/ 放置 desktop.jar 与 jre8-pojav.zip，不需要配置 Steam 路径或环境变量。

方向	说明
模组兼容性	目标是支持绝大多数模组加载，力求模组行为与桌面端一致。
兼容策略	启动器内置多种兼容策略。
运行时	运行 JavaSE 而不是 ART，避免因为实现不一致导致的兼容性问题。
移动端交互	针对触屏补充了控制适配与界面适配。

[!Note] 虽然尖塔采用了 LibGDX 编写，但是部分模组仍采用一些桌面特性进行编写，本项目旨在使用适配安卓的 JavaSE 与配套 Native 库来加载这些模组，从而最大限度还原模组的表现。

快速开始

1. 准备构建依赖

构建只读取仓库内的 build-deps/ 目录，不需要配置 Steam 路径或环境变量。必需文件：

文件	来源
build-deps/desktop.jar	从你自己的 Steam 安装复制 steamapps/common/SlayTheSpire/desktop-1.0.jar 并重命名为 desktop.jar
build-deps/jre8-pojav.zip	https://github.com/ModinMobileSTS/SlayTheAmethystModdedDependence/releases/download/pojav-jre8/jre8-pojav.zip

两个文件都可以手动放入 build-deps/。若构建时发现缺失，ensureBuildDependencies 会自动从依赖包下载并解压补全（默认地址 build-deps.tar.gz，内含这两个文件）：

https://github.com/ModinMobileSTS/SlayTheAmethystModdedDependence/releases/download/deps-20260305/build-deps.tar.gz

可用 -PbuildDeps.bundleUrl=<url> 覆盖下载地址；离线构建时请预先手动放入文件。

可选签名目录（放置后所有 checkout 的 debug 签名一致，release 无需环境变量）：

• build-deps/debug-signature/：覆盖 AGP 默认 debug keystore。
• build-deps/release-signature/：release 签名。

两个目录结构相同，内含 keystore 文件与一个 signing.properties：

# build-deps/release-signature/signing.properties
storeFile=keystore.jks
storePassword=...
keyAlias=upload
keyPassword=...

storeFile 省略时默认 keystore.jks；keyPassword 省略时默认等于 storePassword。release 构建优先读取 RELEASE_STORE_FILE / RELEASE_STORE_PASSWORD / RELEASE_KEY_ALIAS / RELEASE_KEY_PASSWORD 环境变量及 release.* Gradle 属性，全部为空时才读取 build-deps/release-signature/。release APK 强制使用 release 密钥，并启用 APK Signature Scheme v1（JAR）和 v2；未配置 release 密钥时构建会失败，不会回退到 debug 签名。

依赖下载来源：

• 构建依赖包（含 desktop.jar 与 jre8-pojav.zip）：ModinMobileSTS/SlayTheAmethystModdedDependence

• 原生库市场：ModinMobileSTS/SlayTheAmethystResource

[!NOTE] ModTheSpire.jar、BaseMod.jar、StSLib.jar 等核心模组 jar 由应用资源打包提供，不会在构建时从外部模组源动态解析。

资源包策略：slim APK 在需要时从固定的 GitHub/Gitee resources-v1.7 链接下载；full APK 可将同版本归档内置在 APK 中供离线首次安装。两种 APK 使用相同的本地资源仓库。只要 resourcePack.version 不变，应用升级会复用已安装的 generation，不会重新下载。资源包不随本仓库 CI 发版。

2. 检查构建环境

一键检查工具链、网络连通性与依赖是否就绪（类似 flutter doctor）：

python3 scripts/build/main.py doctor

该命令会探测 Maven Central / Google Maven / Gradle Plugin Portal / foojay 以及依赖包下载地址的可达性；离线环境可用 --no-network 跳过网络检测。

3. 构建调试版 APK

.\gradlew.bat :app:assembleDebug

在 Linux/macOS 或 Git Bash 中，也可以直接打包并安装到已连接的 Android 设备：

./scripts/build-debug-install.sh

连接了多台设备时，传入目标设备序列号：

./scripts/build-debug-install.sh <设备序列号>

4. 构建签名发布版 APK

[!IMPORTANT] 建议使用发布自动化指南中的方法进行Release版本的构建，以避免签名不同的问题

推荐把签名放在 build-deps/release-signature/（见上文），然后直接构建：

./gradlew :app:assembleRelease

也可以改用标准 Android 签名环境变量（优先级高于签名目录）：

$env:RELEASE_STORE_FILE="C:\path\to\release-signing.jks"
$env:RELEASE_STORE_PASSWORD="..."
$env:RELEASE_KEY_ALIAS="..."
$env:RELEASE_KEY_PASSWORD="..."
.\gradlew.bat :app:assembleRelease

APK 输出目录：

• app/build/outputs/apk/debug/
• app/build/outputs/apk/release/

构建说明

模块	职责
:app	Android 启动器 UI、打包逻辑、运行时资源组装，以及 adb 调试任务
:boot-bridge	打包进运行时资源的 Java 启动桥接 jar
:patches:gdx-patch	构建期包含的桌面兼容补丁 jar

构建目标：

• minSdk 26
• targetSdk 33
• compileSdk 36
• Java / Kotlin 字节码目标：1.8

相关文档

基础调试指令

.\gradlew.bat :app:stsStart
.\gradlew.bat :app:stsStop
.\gradlew.bat :app:stsPullLogs

性能测试

发版前应该进行一轮性能测试，查看更改是否引入性能问题。

./gradlew :app:stsHarnessPerfBench

该任务将会自动启动 app，自动跑真实的运行场景，一并收集性能信息。

建议使用 -PdeviceSerial 和 -PharnessOutDir 指定设备和结论输出目录。

./gradlew :app:stsHarnessPerfBench -PdeviceSerial=10.126.126.1:5555 -PharnessOutDir=agent-tmp/perf-bench

完整参数、默认值、固定行为和输出文件见 perf-bench 参数参考。

GPU 诊断开销应使用固定战斗做关闭/开启配对测试；方法、指标定义和阈值限制见 GPU 性能诊断与配对基准。

市场网络测试

市场加载测试分两层：离线不稳定网络模拟，以及连接真实 Watt / Steam 的连通性验收。

离线模拟不需要设备、账号、代理或外网，用本地 MockWebServer 注入连接拒绝、黑洞超时、 节点重置、403、TLS 故障、换网/冷启动、路由目录故障和网络恢复等场景，验证市场页面仍能 加载或按预期失败：

./gradlew :app:marketNetworkSimulationTest

场景覆盖：

场景	注入方式	预期
健康网络	正常 Watt 节点	正常加载市场
默认内置跳点策略	直接使用 rmbgame 跳点	正常加载，不查询 Watt 目录
默认内置跳点失败	跳点连接重置	回退官方 origin
中途开启 VPN/关闭加速	每请求读取加速开关	后续请求走官方 origin
首选节点拒绝连接	连接 127.0.0.1:1	切换到下一节点
首选节点 DNS 故障	域名解析失败	切换节点
首选节点连接重置	响应前关闭 socket	切换节点
首选节点黑洞	不返回响应头直到读超时	切换节点，加载耗时有界
首选节点返回 403	拒绝 workshop browse	刷新路线后切换节点
全部 Watt 节点失败	连接重置	回退官方 origin
Watt 路由目录故障	目录接口 500	仍回退官方 origin
慢但可用节点	延迟 350ms 返回	不误判为失败
校园网/酒店认证页	HTTP 200 登录页	明确提示网络认证，不显示空市场
全部线路不可用	节点与官方都失败	有界失败，不挂起
网络恢复后重试	首次失败、随后恢复	用户重试即可继续加载
加载途中 Wi-Fi 切移动网络	旧节点失效、路由目录返回新节点	刷新路线并切换新节点
换网后冷启动	本地缓存仍是旧节点	跳过失效缓存并加载
页面下载到一半断网	响应体中途关闭	不伪装成空市场，重试后恢复
代理 TLS 链路损坏	一个节点 TLS 握手失败	切换到正常节点
页面加载后元数据接口故障	文件大小/订阅数接口 503	已显示的市场列表不受影响

真实连通性测试仍保持显式开关，避免普通单测访问第三方服务：

STS_RUN_MARKET_NETWORK_ACCEPTANCE=true ./gradlew :app:marketNetworkAcceptanceTest

该任务会同时运行离线模拟和真实验收；未设置环境变量时真实部分自动跳过。

更多文档：

• 英文版 README
• 架构总览
• 调试自动化指南
• GPU 性能诊断与配对基准
• 发布自动化指南
• 后端启动链路说明

仓库结构

路径	用途
app/	主 Android 应用与启动器实现
boot-bridge/	启动桥接 jar 模块
patches/gdx-patch/	运行时兼容补丁模块
build-deps/	本地构建依赖包与运行时输入
docs/	开发文档、多语言 README 与架构说明

致谢

本仓库复用了并改造了 Amethyst-Android / PojavLauncher 的部分原生与 Java 桥接实现。详细归属与许可证请见 NOTICE 和 THIRD_PARTY_LICENSES.md。

特别感谢：

• AngelAuraMC/Amethyst-Android 提供了 Android JavaSE 启动器桥接方向上的重要工程基础和参考实现。
• Alchyr/sts-ram-saver 为启动器内存优化提供了极大的指导，使得更多模组可以在启动器上使用。
• bwwq/ModTheSpire 提供了本项目当前使用的 ModTheSpire 变体。
• 所有为 Slay the Spire 模组生态、启动器工具链、问题排查和公开讨论做出贡献的开发者与社区成员。