SlayTheAmethyst
Slay the Spire
About the project
Slay the Spire es un videojuego roguelike, RPG de cartas y mazmorras desarrollado por MegaCrit y publicado por Humble Bundle. El acceso anticipado estuvo disponible primero en Mac, Windows y Linux a finales del 2017, y en 2019 fue lanzada la versión completa también para Nintendo Switch, PlayStation 4 y Xbox One. Las versiones de iOS y Android fueron lanzadas en 2020 y 2021 respectivamente.
Official project information
[!IMPORTANT] 本仓库不包含私有构建依赖。构建前请按下文在
build-deps/放置desktop.jar与jre8-pojav.zip，不需要配置 Steam 路径或环境变量。
<a id="highlights"></a>
核心特性
| 方向 | 说明 |
|---|---|
| 模组兼容性 | 目标是支持绝大多数模组加载，力求模组行为与桌面端一致。 |
| 兼容策略 | 启动器内置多种兼容策略。 |
| 运行时 | 运行 JavaSE 而不是 ART，避免因为实现不一致导致的兼容性问题。 |
| 移动端交互 | 针对触屏补充了控制适配与界面适配。 |
[!Note] 虽然尖塔采用了 LibGDX 编写，但是部分模组仍采用一些桌面特性进行编写，本项目旨在使用适配安卓的 JavaSE 与配套 Native 库来加载这些模组，从而最大限度还原模组的表现。 <a id="quick-start"></a>
快速开始
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
[!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/
<a id="build-from-source"></a>
构建说明
| 模块 | 职责 |
|---|---|
:app | Android 启动器 UI、打包逻辑、运行时资源组装，以及 adb 调试任务 |
:boot-bridge | 打包进运行时资源的 Java 启动桥接 jar |
:patches:gdx-patch | 构建期包含的桌面兼容补丁 jar |
构建目标：
minSdk 26targetSdk 33compileSdk 36- Java / Kotlin 字节码目标：
1.8
<a id="automation-and-docs"></a>
相关文档
基础调试指令
.\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
该任务会同时运行离线模拟和真实验收；未设置环境变量时真实部分自动跳过。
更多文档：
<a id="repository-layout"></a>
仓库结构
| 路径 | 用途 |
|---|---|
app/ | 主 Android 应用与启动器实现 |
boot-bridge/ | 启动桥接 jar 模块 |
patches/gdx-patch/ | 运行时兼容补丁模块 |
build-deps/ | 本地构建依赖包与运行时输入 |
docs/ | 开发文档、多语言 README 与架构说明 |
<a id="credits"></a>
致谢
本仓库复用了并改造了 Amethyst-Android / PojavLauncher 的部分原生与 Java
桥接实现。详细归属与许可证请见 NOTICE
和 THIRD_PARTY_LICENSES.md。
特别感谢：
- AngelAuraMC/Amethyst-Android 提供了 Android JavaSE 启动器桥接方向上的重要工程基础和参考实现。
- Alchyr/sts-ram-saver 为启动器内存优化提供了极大的指导，使得更多模组可以在启动器上使用。
- bwwq/ModTheSpire 提供了本项目当前使用的 ModTheSpire 变体。
- 所有为 Slay the Spire 模组生态、启动器工具链、问题排查和公开讨论做出贡献的开发者与社区成员。