ModTheSpire 使用与 Mod 开发指南：杀戮尖塔外部模组加载器实战解析-北京尧图网络

游戏开发桌面应用【免费下载链接】ModTheSpireExternal mod loader for Slay The Spire项目地址https://gitcode.com/gh_mirrors/mo/ModTheSpire点击查看免费下载ModTheSpire下文简称 MTS是一个用于《杀戮尖塔》Slay the Spire的外部模组加载器它的核心价值在于无需修改游戏本体文件即可加载、管理并运行外部 Mod同时为 Mod 开发者提供了一套基于 Javassist 字节码注入的 Patch 注解体系。本文将以当前仓库 README.md 为主线结合 Loader.java、Patcher.java 等核心源码完整讲解 MTS 的安装、运行、命令行参数、Mod 打包规范与 Patch 开发 API。读完本文你将掌握一套从玩家装 Mod到开发者写 Mod的完整实战方案。一、ModTheSpire 是什么ModTheSpire 是《杀戮尖塔》社区中最核心的外部模组加载器。它的设计目标是在不修改 Slay the Spire 原始游戏文件的前提下将外部 Mod 注入游戏运行时。从源码结构看整个项目的核心运行链路集中在Loader.main()见 Loader.java启动时扫描mods/目录与 Steam Workshop 中的 Mod JAR → 校验依赖与版本 → 通过自定义的MTSClassLoader/MTSClassPool在字节码层面注入 Patch → 最后以反射方式调用com.megacrit.cardcrawl.desktop.DesktopLauncher.main()拉起游戏。也就是说MTS 是一个先打补丁、再启动游戏的代理启动器这与直接替换游戏文件的做法有本质区别游戏本体始终保持干净卸载 Mod 只需移除 JAR 即可。当前仓库的pom.xml中记录了项目版本为3.30.3Java 编译目标为 1.8并声明了对 javassist 3.22.0-GA、gson 2.8.9、commons-lang3 3.7 等核心依赖见 pom.xml。二、安装三步把 MTS 装进游戏目录2.1 下载与文件放置按照 README 的说明安装过程非常简单下载最新版 Release 中的ModTheSpire.jar将ModTheSpire.jar复制到你的《杀戮尖塔》安装目录在游戏目录下创建一个mods文件夹把所有 Mod JAR 文件放进去。Windows 额外步骤把仓库根目录的MTS.cmd复制到游戏安装目录。该脚本内容极简本质就是一行启动命令见 MTS.cmdstart .\jre\bin\javaw.exe -jar .\ModTheSpire.jarLinux 额外步骤把仓库根目录的MTS.sh复制到游戏安装目录并赋予可执行权限。脚本同样是一行 Java 启动命令见 MTS.sh#!/bin/sh ./jre/bin/java -jar ModTheSpire.jar仓库中还提供了_run.bat使用系统默认java直接启动并暂停窗口见 _run.bat以及面向旧笔记本的MTS_8u51.cmd使用jre1.8.0_51目录下的旧版 JRE 启动见 MTS_8u51.cmd后者与Loader中检测jre1.8.0_51目录并自动重启的兼容逻辑对应见 Loader.java。2.2 mods 目录的扫描规则Loader.getAllModFiles()会以mods/为默认目录通过文件名过滤器仅收录以.jar结尾的文件见 Loader.java。因此Mod 必须是JAR 格式直接放.java源文件或未打包的 class 目录是无效的文件扩展名不区分大小写name.toLowerCase().endsWith(.jar)。此外当游戏处于 Beta 分支时STS_BETA为 trueMTS 还会额外扫描mods/beta/子目录作为 Beta 版 Mod 的优先级来源并允许 Steam Workshop 下载的 Mod 出现在候选列表中见 Loader.java。三、运行选择 Mod 并启动游戏3.1 三种启动方式README 提供了三种运行入口任选其一平台方式说明Windows双击/命令行运行MTS.cmd使用游戏自带的jre目录启动避免系统 Java 版本干扰Linux运行MTS.sh需可执行权限同样使用./jre/bin/java任意平台java -jar ModTheSpire.jar需要系统已安装Java 8MTS 强依赖 Java 8 运行时启动后 MTS 会先弹出一个 Swing 窗口ModSelectWindow见 ModSelectWindow.java随后勾选你想启用的一个或多个 Mod点击Play按钮。Loader.runMods()会依次完成构建 ModInfo 数组 → 校验依赖 → 拓扑排序 → 枚举补丁 → 注入 Patch → 编译补丁类 → 反射启动游戏主类见 Loader.java。3.2 窗口中的附加功能除了 Play 之外ModSelectWindow还提供了几个开发向选项见 ModSelectWindow.javaDebug开启调试模式Loader.DEBUG truePatcher 会打印每个 Patch 的详细注入过程Dump Patched Jar把打补丁后的游戏类导出为desktop-1.0-patched.jar对应--out-jarPackage生成预打好补丁的游戏 JARdesktop-1.0-modded.jar对应--package。3.3 命令行参数进阶Loader.main()完整解析了一批命令行参数见 Loader.java可用java -jar ModTheSpire.jar 参数直接调用参数作用--debug开启调试模式--out-jar导出打补丁后的 JARdesktop-1.0-patched.jar后退出--package生成预打包 Mod 版游戏 JARdesktop-1.0-modded.jar后退出--close-when-finishedout-jar / package 完成后自动关闭便于脚本自动化--allow-beta允许加载 Beta 分支游戏对应的 Mod--skip-launcher跳过 Mod 选择窗口直接运行--skip-intro跳过开场动画画面--mods id1,id2,...按 Mod ID 直接指定要加载的 Mod隐含--skip-launcher--profile name使用指定的配置档案--imgui启用 LWJGL3 后端Steam Deck 或 Dear ImGui 场景--jre51强制使用jre1.8.0_51旧版 JRE内部自动重启时使用这些开关同时会写入ModTheSpire.properties配置文件由SpireConfig管理下次启动自动沿用。例如默认配置中包含debugfalse、out-jarfalse、packagefalse、allow-betatrue、skip-launcherfalse、mods等键见 Loader.java。3.4 启动时的版本与依赖检查Loader.main()在弹窗之前会做两件事定位游戏本体默认查找desktop-1.0.jar找不到时通过SteamSearch.findDesktopJar()搜索 Steam 安装路径Mac 版则回退到SlayTheSpire.app/Contents/Resources/desktop-1.0.jar见 Loader.java读取游戏版本与 Beta 标记用 ASM 的ClassReader直接读取CardCrawlGame与Settings两个 class 的常量池解析VERSION_NUM与isBeta见 Loader.java。如果系统 Java 不是 1.8 开头MTS 会弹出警告提示ModTheSpire requires Java version 8 to run properly见 Loader.java因此务必使用 Java 8 运行。四、Mod 打包规范ModTheSpire.json 与依赖声明4.1 新版清单文件ModTheSpire.json每个 Mod JAR 的根目录下需要放一个ModTheSpire.json清单文件。ModInfo.ReadModInfo()使用 Gson 解析它见 ModInfo.java可用的字段与ModInfo的属性一一对应JSON 字段对应属性类型说明modidIDstringMod 唯一标识用于依赖解析与--mods指定nameNamestringMod 显示名称列表中排序依据versionModVersionSemVer 字符串例如1.2.3用于 Workshop 版本比较author_listAuthorsstring 数组作者列表creditsCreditsstring致谢信息descriptionDescriptionstringMod 简介mts_versionMTS_VersionSemVer 字符串所需的最低 ModTheSpire 版本低于当前 MTS 版本时该 Mod 会被拒绝加载并弹窗提示sts_versionSTS_Versionstring兼容的《杀戮尖塔》版本dependenciesDependenciesstring 数组必需的依赖 Mod ID 列表缺失时抛MissingDependencyExceptionoptional_dependenciesOptionalDependenciesstring 数组可选依赖存在才建立加载顺序约束update_jsonUpdateJSONstring在线更新检查的 JSON 地址Workshop Mod 会被置空一个典型示例{ modid: examplemod, name: Example Mod, version: 1.0.0, author_list: [Alice, Bob], description: An example mod for ModTheSpire., mts_version: 3.0.0, sts_version: 2.2, dependencies: [basegame-lib], optional_dependencies: [other-mod], update_json: https://example.com/update.json }4.2 旧版清单ModTheSpire.config兼容仓库同时保留了旧格式的兼容读取逻辑当 JAR 内没有ModTheSpire.json时会回退读取ModTheSpire.configProperties 文件支持name、author逗号分隔、description、mts_version、sts_version等键若连配置文件都没有则默认以 JAR 文件名去掉.jar后缀作为 Mod 名见 ModInfo.java。推荐新 Mod 一律使用ModTheSpire.json。4.3 依赖解析与加载顺序Loader.runMods()在真正注入前会执行严格的依赖管理见 Loader.java重复 ID 检测两个 Mod 声明相同modid时抛出DuplicateModIDException并弹窗必需依赖校验dependencies中任一 ID 未在已选 Mod 中声明时抛出MissingDependencyException拓扑排序使用内部实现的GraphTS见 GraphTS.java对所有 Mod 做稳定拓扑排序保证依赖先于被依赖者加载存在循环依赖时抛出CyclicDependencyException。4.4 Steam Workshop 支持MTS 会通过SteamWorkshop子进程搜索 Steam 工作坊已订阅的 Mod并将其加入候选列表若工作坊版本比本地mods/中的同名 Mod 更新则自动优先使用工作坊版本见 Loader.java。Workshop 信息会以WorkshopInfo.json形式缓存供后续对比更新见 Loader.java。五、For Modders开发环境与构建5.1 环境要求README 明确列出 Mod 开发者的两个硬性要求JDK 8与 MTS 运行要求一致Maven项目使用 Maven 构建仓库根目录同时提供了mvnw与mvnw.cmd包装脚本方便无本地 Maven 的环境。5.2 构建 MTS 本体在仓库根目录执行mvnw package构建过程由maven-shade-plugin分多步完成见 pom.xml产出独立的ModTheSpire-kotlin.jar、ModTheSpire-lwjgl3.jar、ModTheSpire-corepatches.jar与ModTheSpire-corepatches-lwjgl3.jar最终的target/ModTheSpire.jar通过IncludeResourceTransformer把上述 JAR 打包为内嵌资源corepatches.jar、kotlin.jar、lwjgl3.jar等并在 Manifest 中把主类设为com.evacipated.cardcrawl.modthespire.Loadermaven-antrun-plugin会把成品再复制一份到../lib/ModTheSpire.jar与../_ModTheSpire/ModTheSpire.jar见 pom.xml。值得一提的是target/ModTheSpire.jar对 ASM 做了包重定位org.objectweb.asm→org.shaded.objectweb.asm并把 javassist 完整打入最终 JAR——这正是 MTS 运行时能做字节码注入的根基。5.3 Settings.isModded 自动置位README 特别强调ModTheSpire 会自动把Settings.isModded标志置为 trueMod 开发者无需自己处理。这个行为在源码中有明确对应Loader.runMods()通过反射加载com.megacrit.cardcrawl.core.Settings类把静态字段isModded设为true同时把isDev设为false并把[ModTheSpire 版本号]追加进CardCrawlGame.VERSION_NUM见 Loader.java。因此 Mod 内可以直接依赖该标志位判断当前是否处于 Mod 环境。六、Patch APIMTS 的字节码注入体系这是 Mod 开发的核心章节。MTS 基于javassist在字节码层面对游戏类进行手术式修改开发者只需写带注解的 Java 类即可无需触碰游戏源码。6.1 SpirePatch最基础的补丁注解SpirePatch标注在补丁类上用于声明要修改哪个类的哪个方法见 SpirePatch.java注解属性默认值说明clzvoid.class目标类的 Class 引用推荐编译期安全cls目标类的全限定名字符串无法直接引用游戏类时使用method必填目标方法名特殊值ctor构造函数、staticinit静态初始化块、class修改类本身paramtypez{void.class}目标方法的参数类型Class 数组void.class表示不限定paramtypes{DEFAULT}目标方法的参数类型类名字符串数组与paramtypez二选一requiredModId需要某个 Mod 加载时才应用本补丁该 Mod 未加载则忽略optionalfalse目标类/方法不存在时是否静默跳过不抛PatchingExceptionSpirePatch是可重复注解Repeatable(SpirePatches.class)同一个补丁类可通过SpirePatches({...})同时修补多个方法。补丁类内部按约定命名的方法会被Patcher.injectPatches()识别见 Patcher.java方法名 / 注解作用Prefix或SpirePrefixPatch在目标方法开头插入逻辑Postfix或SpirePostfixPatch在目标方法结尾插入逻辑Insert或SpireInsertPatch在目标方法指定行号/位置插入逻辑Locator配合SpireInsertPatch动态定位插入行Instrument或SpireInstrumentPatch通过 javassistExprEditor遍历修改方法内的表达式Replace用补丁方法整体替换目标方法体Raw或SpireRawPatch直接操作 javassistCtBehavior进行底层改写此外补丁方法必须为public static否则抛出NonStaticPatchMethodException见 Patcher.java。6.2 Prefix / Postfix 中的特殊参数在Prefix与Postfix方法中MTS 会注入一组约定的参数由PrefixPatchInfo/PostfixPatchInfo处理__instance被修补方法所属的实例对象静态方法为null__result目标方法的返回值仅Postfix可用void 方法为null__args全部原始参数的数组在SpirePatch2中提供见 SpirePatch2.java。如果需要提前中断目标方法并直接返回可以在Prefix中返回SpireReturn见 SpireReturn.javaSpirePatch(clz SomeGameClass.class, method someMethod) public class MyPatch { SpirePrefixPatch public static SpireReturnVoid Prefix(SomeGameClass __instance, int __arg0) { if (条件成立) { return SpireReturn.Return(); // 直接短路不再执行原方法 } return SpireReturn.Continue(); // 继续执行原方法 } }6.3 SpireInsertPatch 与 Locator精确定位插入点SpireInsertPatch支持按绝对行号、相对行号与Locator三种方式定位插入点见 SpireInsertPatch.java属性说明loc目标方法内的绝对行号-1表示未使用rloc相对目标方法起始行的偏移行号locs/rlocs多行号数组可一次插入多个位置localvars需要读取的局部变量名列表locator指定一个SpireInsertLocator子类动态计算插入行使用 Locator 是推荐做法——它不依赖硬编码行号对游戏版本升级更鲁棒。Locator 类需要继承 SpireInsertLocator.java重写Locate(CtBehavior ctMethodToPatch)返回目标行号数组并可与InOrderFinder/InOrderMultiFinder/MatchFinderExprEditor见 finders配合通过先匹配某段字节码模式、再偏移的方式寻找精确位置。6.4 枚举扩展SpireEnumSpireEnum标注在字段上用于给游戏的枚举类型新增常量见 SpireEnum.java。其处理分两阶段Patcher.patchEnums()在 javassist 层给目标枚举类添加public static final新字段见 Patcher.javaPatcher.bustEnums()运行时通过EnumBusterReflect见 EnumBusterReflect.java破坏枚举常量池限制把新常量注册进 JVM见 Patcher.java。public class MyEnumHolder { SpireEnum public static final CardRarity MY_RARITY null; // 值会在补丁期填充 }6.5 字段扩展SpireField 与 SpireOverrideSpireField配合SpirePatch(methodclass)使用给目标类新增实例字段见 SpireField.java。补丁类中声明形如public static SpireFieldT 字段名 new SpireField(() - 默认值);的静态字段补丁生效后即可在 Prefix/Postfix 中通过SpireField.get(__instance)/.set(__instance, v)读写SpireOverride标注在方法上实现类似继承并覆写父类方法的效果见 SpireOverride.java。Patcher.patchOverrides()会把父类中对被覆写方法的调用重定向到子类实现并用SpireSuper见 SpireSuper.java代替super调用以调用父类原始逻辑见 Patcher.java。6.6 Mod 初始化与侧载SpireInitializer标注在类上MTS 会在所有补丁注入完成后反射调用该类上的public static void initialize()方法sideload 场景调用sideload()常用于注册事件监听或初始化自定义逻辑见 SpireInitializer.java 与 Patcher.javaSpireSideload标注在类上并声明modIDs()用于把未被玩家勾选的另一个 Mod 强制加载进运行时如XX 汉化包自动附带依赖场景加载后其 ID 会被加__sideload_前缀以便区分见 SpireSideload.java 与 Patcher.java。6.7 配置 APISpireConfigSpireConfig为 Mod 提供了简单的键值配置持久化能力见 SpireConfig.java。配置文件以.properties格式保存位于游戏配置目录下支持按 Mod 名分目录隔离SpireConfig config new SpireConfig(MyMod, settings); // 生成 MyMod/settings.properties config.setBool(enabled, true); config.setInt(volume, 5); config.save(); // 写盘 boolean on config.getBool(enabled); // 读回Loader自身的ModTheSpire.properties也是用这套 API 管理的见 Loader.java。七、常见问题与调试建议ModTheSpire requires Java version 8请安装 JDK/JRE 8 并用它启动ModTheSpire.jarWindows 上推荐走MTS.cmd使用游戏自带 JRE。Mod 列表为空确认mods/目录在游戏根目录下、Mod 是.jar文件、JAR 根目录包含ModTheSpire.json或旧版ModTheSpire.config。Missing Dependency 弹窗被选 Mod 的dependencies中声明了未勾选的 Mod ID勾选全部依赖后重试。Duplicate Mod ID 弹窗两个 JAR 声明了相同modid删除其中一个。requires ModTheSpire vX or greater 弹窗Mod 的mts_version高于当前 MTS 版本升级 ModTheSpire 到最新 Release。调试补丁使用--debug参数启动或在启动器窗口中勾选 DebugPatcher会打印每个 Patch 的目标类、方法、注入行与最终字节码见 Patcher.java。异常崩溃启用 Debug 模式后查看控制台输出MTS 会在崩溃信息中附带当前加载的 Mod 列表自 v3.26.0 起支持见 CHANGELOG.md。八、版本演进与项目背景完整变更记录见仓库根目录的 CHANGELOG.md从 v3.18 到 v3.30 的演进中可以看到关键能力逐步落地SpirePatch2与__args参数v3.21、requiredModId条件补丁v3.20、--mods直接指定加载v3.25、预打包 Mod 版游戏v3.26、LWJGL3 / Dear ImGui 支持与 Steam Deck 兼容v3.30、属性化全部开关v3.28等。根据 README 的 Contributors 列表项目最初由 kiooeht 创建t-larson、test447、reckter、FlipskiZ、pk27602017 等人分别在多 Mod 加载、启动器 UI、Locator、Maven 构建、Mod 初始化与 ModInfo UTF-8 支持等方面做出贡献见 README.md。结语ModTheSpire 以外部加载字节码注入为核心设计把 Mod 生态从改游戏文件彻底解放出来玩家只需复制一个 JAR、建一个mods目录、勾选并 Play开发者则借助SpirePatch家族注解与ModTheSpire.json清单用纯 Java 完成对《杀戮尖塔》的深度定制。理解本文的安装流程、命令行参数、清单字段与 Patch API你就同时掌握了玩家侧与开发者侧两套完整的 ModTheSpire 实战技能。赞分享游戏开发桌面应用【免费下载链接】ModTheSpireExternal mod loader for Slay The Spire项目地址https://gitcode.com/gh_mirrors/mo/ModTheSpire点击查看免费下载相关推荐ModTheSpire杀戮尖塔模组加载器的专业使用指南ModTheSpire杀戮尖塔模组加载器的专业使用指南作为《Slay The Spire》游戏生态中不可或缺的模组加载工具ModTheSpire为玩家提供游戏开发桌面应用ModTheSpire完全攻略杀戮尖塔模组加载器深度使用指南ModTheSpire完全攻略杀戮尖塔模组加载器深度使用指南作为《杀戮尖塔》最强大的外部模组加载器ModTheSpire为这款经典卡牌游戏注入了无限可能。游戏开发桌面应用ModTheSpire终极指南杀戮尖塔模组加载器完整教程ModTheSpire终极指南杀戮尖塔模组加载器完整教程 ModTheSpire是专为《杀戮尖塔》设计的外部模组加载器能够在完全不修改游戏原始文件的情况下游戏开发桌面应用上一篇如何把Windows 11安装镜像砍半Tiny11Builder实操手册下一篇MiniExcel vs EPPlus vs ClosedXML全面性能对比分析与选择指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ModTheSpire 使用与 Mod 开发指南：杀戮尖塔外部模组加载器实战解析

相关推荐

排序算法比较与交换次数统计工具：面向性能调优的底层行为分析

用 N_m3u8DL-RE 完整下载 DASH/HLS 流媒体

FreeRTOS内存泄漏诊断：从堆监控到分配追踪的实战方法

更多资讯

Apollo-11式高可靠系统设计：实时容错与资源约束下的工程实践

大模型Agent入门：核心原理、ReAct循环与实战避坑指南

C++中std::string与std::wstring互转：编码转换原理与跨平台实践

QNN环境配置与模型转换实战：从SDK安装到模拟验证

Fontsource 字体档案解析：Carme 无衬线字体的数据化建模与 Web 集成实践

各类继电器接线详解：线圈与触点、接线图与避坑指南

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？