简介面向《杀戮尖塔》模组开发初学者的入门指南旨在帮助没有Java与Mod经验的玩家从零搭建MOD开发环境并完成第一个可运行的MOD项目。教程围绕modthespire、stslib和basemod三大支持库展开清楚解释它们如何在游戏本体与自定义代码之间建立接口同时覆盖IntelliJ IDEA安装、Maven环境变量配置、pom.xml编辑与依赖声明等关键环节。资源以1个PDF文档封装大小约1.5MB结构紧凑包含游戏本体安装、创意工坊支持库订阅、开发环境搭建、构建步骤以及Java语法基础等章节并配有控制台输出、变量、函数、类作用域、监听函数与继承等示例讲解。通过Maven构建时如何指定Steam游戏库路径、如何引用BaseMod依赖等细节也有直观展示适合希望快速入门的玩家边看边练。目前已有2121人学习下载能够帮助读者从环境准备到代码实现逐步建立起对MOD结构的基本认知适合作为杀戮尖塔Mod开发的第一份学习资料。1. 做杀戮尖塔Mod前先把三件事想清楚杀戮尖塔的Mod开发说到底是给一个Java 8时代的老游戏写外挂代码这句话决定了后面所有的版本选择。很多第一次上手的人栽在同一个地方按最新教程装了最新JDK和最新Maven结果ModTheSpire加载器根本不认或者构建出的jar包进游戏就闪退。花了一晚上最后发现是版本和路径的问题。这篇教程把游戏本体、三大支持库、IDE、Maven这一整条链路的安装和配置走一遍所有参数都给你拆开讲照着做就能把第一个能加载的jar跑出来。适合以前没配过Java环境、对创意工坊目录结构不熟、或者卡在pom.xml上不知道怎么改的人。装好这套环境你才能开始谈写卡牌、写事件、改机制。2. 装依赖游戏本体、ModTheSpire、BaseMod与stslib的下载与订阅2.1 游戏本体买了不一定能马上开发游戏本体是全部工作的基础但“装了游戏”和“能开发Mod”是两回事。很多教程把这一步标个“略”实际上这里有个前置条件至少用普通模式启动过一次游戏让Steam把游戏文件完整解压落盘。新下载的游戏有时候文件还没就绪直接开Mod加载器会报文件缺失。开发时我们需要的是游戏根目录下的这个文件SteamLibrary/steamapps/common/SlayTheSpire/desktop-1.0.jar这是游戏的主程序jar也就是Mod要注入的目标本体。后面的pom.xml会直接用系统路径引用它所以在开工之前先找到你的SteamLibrary在哪。Steam默认装的路径通常是C:\Program Files (x86)\Steam\steamapps但很多人的游戏库在别的盘这个路径记下来后面配置里要反复用。如果游戏刚装好我的建议是先普通模式启动一次看看能不能正常进游戏。能进再关掉继续配环境。别一上来就想着上Mod先确认本体是好的否则后面所有报错你都没法判断是游戏问题还是Mod问题。2.2 创意工坊订阅三大库每个库的职责先分清杀戮尖塔的Mod生态依赖三个Steam创意工坊模组ModTheSpire、BaseMod、stslib。这三者分工不同订阅之前先把职责理清楚后面排查问题会省很多时间ModTheSpireMod加载器。没有它游戏启动时不会扫描和加载任何Mod jar。它负责识别ModTheSpire.json、执行SpireInitializer注解、打印加载日志。也就是说你的Mod写了代码靠的是它来拉起。BaseModMod API支持库。提供大量与游戏交互的接口比如监听抽牌事件、受伤事件、战斗结束事件以及注册卡牌、角色、药水的API。写Mod基本离不开它。stslib扩展库。提供了不少现成的卡牌动作、UI组件和机制模板不是每个Mod都必须用但推荐先订阅上一方面测试别人的Mod经常需要它另一方面以后你用到特定功能时不用再回头补。订阅方式很简单在Steam客户端里打开《杀戮尖塔》的商店页面进入创意工坊分别搜索这三个名字点订阅。等Steam自动下载完成即可。需要特别提醒一点订阅只是加入下载队列不等于已经下载完成。Steam创意工坊的模组是异步下载的你得切到Steam的“下载”页面确认这三个都到了100%再去下一步。很多人卡在“我订阅了为什么游戏里看不到”这个问题上原因往往就是下载根本没完成。2.3 确认三个jar的落盘位置创意工坊订阅的模组下载完成后会落在SteamLibrary的workshop目录里路径规律是SteamLibrary/steamapps/workshop/content/646570/模组ID/模组文件.jar这里的646570是杀戮尖塔在Steam创意工坊的内容ID。三个依赖库中BaseMod和ModTheSpire的jar路径在后续pom.xml里会直接用到必须提前确认。下面是我这边的路径示例文件作用预期位置desktop-1.0.jar游戏本体SteamLibrary/steamapps/common/SlayTheSpire/desktop-1.0.jarBaseMod.jarMod APISteamLibrary/steamapps/workshop/content/646570/1605833019/BaseMod.jarModTheSpire.jarMod加载器SteamLibrary/steamapps/workshop/content/646570/1605060445/ModTheSpire.jarStSLib.jar扩展库SteamLibrary/steamapps/workshop/content/646570/对应ID/StSLib.jar注意1605833019和1605060445这两个数字是BaseMod和ModTheSpire在创意工坊里的固定ID后面配置依赖时要用。stslib的ID不用强行记到时候在workshop目录里翻一下就能找到但你要记住它存在。打开资源管理器把上面的路径逐个走一遍确认这些jar文件都真实存在。这一步偷懒不得——pom.xml里的systemPath写的是绝对路径路径错一个字符构建就会报“系统找不到指定的路径”而且报错信息往往要到很后面才暴露排查起来相当难受。如果你用的是Mac或Linux路径结构类似只是前缀从E:\SteamLibrary变成/home/你的用户名/.steam/steam/steamapps之类的挂载位置原理完全一样照着后面的逻辑替换即可。3. 搭开发环境JDK 8、IDEA社区版与Maven的Windows配置3.1 为什么选JDK 8而不是最新版杀戮尖塔本体是Java 8时代的工程Mod最终要注入到这个老工程里运行。官方推荐和大多数Mod作者使用的都是JDK 8你去看pom.xml里的编译配置写的是source 1.8和target 1.8意思就是编译出Java 8版本的class文件。有人会问我用JDK 17编译时把target设成1.8行不行行是行但没必要给自己找麻烦。高版本JDK在编译老项目时经常报一些莫名其妙的警告和错误比如Invalid source release或者对某些废弃API的报错调试起来纯属浪费时间。配环境的原则是匹配目标运行时不是追求工具最新版。下载JDK时选8系列的最新更新版本即可装完后在命令行验证java -version期望输出java version 1.8.0_202如果输出版本号还是1.8开头说明装对了。如果你机器上已经装了更高版本的JDK也不用卸载后面在IDEA里新建项目时单独给这个项目指定JDK 8的路径就行互不干扰。我已经不止一次看到有人因为不想动原有环境用高版本JDK硬编结果在target 1.8和依赖包之间反复报错最后还是乖乖装了8。装一次一劳永逸。3.2 IDEA社区版免费够用Java开发的IDE基本就是在Eclipse和IntelliJ IDEA之间选两个都有免费版本。这篇教程以IDEA为例因为它的Maven支持和代码提示对新手更友好而且社区版已经覆盖了开发Mod需要的全部功能。到IDEA官网下载Community版本也就是社区版。安装过程中按默认选项走即可建议勾选“创建桌面快捷方式”和“添加到PATH”后面在命令行里执行maven命令会更方便。安装完成后先不要急着建项目下一步先把Maven配好因为IDEA新建Maven项目时要调用本机的Maven配置。3.3 Maven下载、解压、配MAVEN_HOMEMaven是一个构建工具负责拉依赖、编译、打包、输出jar。杀戮尖塔Mod项目里pom.xml描述了项目结构Maven按这个文件去执行构建。Windows下的配置步骤如下下载Maven的二进制压缩包版本选3.3.9与这篇教程配套的pom.xml版本一致。解压到一个路径中不含中文、不含空格的目录比如E:\Maven\apache-maven-3.3.9。含中文或空格的路径在后续构建时可能引发奇怪的报错直接避掉比事后排查划算。然后是设置环境变量右键“此电脑”选择“属性”进入“高级系统设置”点击“环境变量”。在系统变量区域点击“新建”变量名填MAVEN_HOME变量值填Maven解压后的完整路径也就是E:\Maven\apache-maven-3.3.9。找到系统变量里的Path双击编辑点击“新建”填入%MAVEN_HOME%\bin。点击确定保存所有对话框然后新开一个命令行窗口。这里有个高频翻车点很多人改完环境变量后在一个旧的命令行窗口里执行命令发现mvn不存在就怀疑配置错了。环境变量在旧窗口里不会刷新必须全部关掉重开才生效。新开窗口这一步不是仪式感是实打实的坑。3.4 组合验证java与mvn一起跑打开新命令行窗口依次执行java -version mvn -versionmvn -version的输出应该包含类似这样的信息Apache Maven 3.3.9 Java version: 1.8.0_202只要这两条都能正常输出开发环境就通了。记住这个组合命令以后排查环境问题第一条就是它。Java和Maven任何一个输出异常你的Mod项目整个就没法构建所以先把这两行跑顺再往下走。4. 建项目pom.xml依赖注入与ModTheSpire.json注册4.1 在IDEA里新建Maven项目打开IDEA创建新项目选择Maven类型。这里有一步容易困惑IDEA会问你要不要选archetype模板这里是不要勾选任何archetype的直接按最简单的骨架创建。填写项目信息GroupId填org.exampleArtifactId填tutorial项目名取tutorial。ArtifactId会作为工程标识的一部分后面生成的jar包默认也叫这个名字建议取一个不带空格、全小写的名字避免后续路径和文件名出问题。创建完成后IDEA右下角通常会弹出一个提示说检测到Maven配置发生变化这时点击“Import Changes”或“Enable Auto-Import”。如果你没看到提示等Maven自动导入完成也可以。这时候项目目录结构大致是这样的tutorial/ ├── .idea/ # IDE辅助文件不用管 ├── src/ │ ├── main/ │ │ ├── java/ # 存放Java代码 │ │ └── resources/ # 存放json、图片等素材 │ └── test/ # Maven自动生成的测试目录 └── pom.xml # Maven构建配置.idea文件夹是IDEA自己的与Mod无关。src/main/java是你写代码的地方src/main/resources放ModTheSpire.json这类资源文件。Maven会自动处理test目录相关的细节暂时不用管。4.2 pom.xml逐块拆解路径、依赖、构建pom.xml是这个项目的命根子它负责告诉Maven三件事依赖哪些jar、编译成什么版本、构建完把jar复制到哪里。下面这个是我配好的完整配置注意steam.path用的是正斜杠?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdorg.example/groupId artifactIdtutorial/artifactId version0.1/version packagingjar/packaging nametutorialMod/name descriptiontutorial/description properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding steam.pathE:/SteamLibrary/steamapps/steam.path /properties dependencies dependency groupIdbin/groupId artifactIdBaseMod/artifactId scopesystem/scope version1.0/version systemPath${steam.path}/workshop/content/646570/1605833019/BaseMod.jar/systemPath /dependency dependency groupIdbin/groupId artifactIdSlayTheSpire/artifactId scopesystem/scope version1.0/version systemPath${steam.path}/common/SlayTheSpire/desktop-1.0.jar/systemPath /dependency dependency groupIdbin/groupId artifactIdModTheSpire/artifactId scopesystem/scope version1.0/version systemPath${steam.path}/workshop/content/646570/1605060445/ModTheSpire.jar/systemPath /dependency /dependencies build finalNametutorialMod/finalName plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.7.0/version configuration source1.8/source target1.8/target /configuration /plugin plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-antrun-plugin/artifactId version1.8/version executions execution phasepackage/phase goals goalrun/goal /goals configuration target copy filetarget/tutorialMod.jar tofile${steam.path}/common/SlayTheSpire/mods/tutorialMod.jar/ /target /configuration /execution /executions /plugin /plugins /build /project逐块说明一下关键参数。properties里的steam.path是整个配置文件的基础路径后面所有系统依赖都用${steam.path}拼接。这个值要填你的Steam库根目录路径分隔符建议用正斜杠。Windows下很多人习惯写E:\SteamLibrary\steamapps但在XML里反斜杠是转义符与后面的字符组合后可能被解析成别的东西。写成E:/SteamLibrary/steamapps是更稳妥的写法能少踩一个坑。dependencies里三个依赖是Mod开发的基石BaseMod.jar提供API接口desktop-1.0.jar是游戏本体ModTheSpire.jar是加载器。注意这里没有引入stslib因为它不是每个Mod都直接用到。等你后续代码里真的要调用stslib里的类时再把它的jar路径以同样方式追加一条依赖即可。三个依赖的scope都标为system意思是Maven不走中央仓库拉取直接读你本机的文件。version填1.0只是占位符system范围下的依赖版本号不会被实际校验。build里的finalName决定了输出jar的名字这里填tutorialMod。maven-compiler-plugin配置了source和target都是1.8即编译产物的Java版本。maven-antrun-plugin则是把package阶段输出的jar文件复制到游戏的mods目录这样构建完直接启动游戏就能在加载器里看到。这里的tofile路径后半段common/SlayTheSpire/mods需要你在游戏根目录下手动创建一个mods文件夹否则antrun复制时会报目标路径不存在。所有依赖的路径都要和你在2.3节里实际确认过的位置一一对应。尤其是workshop/content/646570/后面的数字ID不能凭记忆写去资源管理器里亲眼确认过再填进配置。4.3 ModTheSpire.json让加载器认识你的Mod打开src/main/resources目录在里面新建一个文件命名为ModTheSpire.json。这个文件的作用是告诉ModTheSpire加载器我这个Mod叫什么、是谁写的、依赖谁、版本是多少。内容如下{ modid: tutorial, name: tutorialMod, author_list: [A, B], description: 新手教程mod, version: 0.0.1, sts_version: 03-29-2018, mts_version: 2.6.0, dependencies: [basemod] }各字段的含义modid是这个Mod的唯一标识加载器靠它区分不同的Mod所以全小写且不要有空格。它最好和你在4.1节里填的ArtifactId保持一致后面写代码时包名也会用到它三者对齐能省很多不必要的加载报错。name是显示在ModTheSpire加载列表里的名字可以随意。author_list是一个数组可以写多个作者用方括号和逗号分隔。description是一段文本描述会显示在游戏的Mod菜单里。version和mts_version代表你的Mod版本号和ModTheSpire的版本号。dependencies数组里写basemod表示你的Mod在加载时要先加载BaseMod这在游戏里会表现成加载顺序的依赖关系。sts_version对应的是游戏版本这里填的是教程所用的示例版本。你实际填的时候可以打开ModTheSpire的加载日志里面会显示它识别到的游戏版本信息以日志为准。JSON格式的注意点集中在括号配对花括号{}表示对象方括号[]表示数组逗号分隔同级元素。写错了IDE会直接标红但如果IDE没标红也不代表没问题——这个文件里如果有多个对象漏一个逗号这种错误IDE经常能发现。4.4 执行package构建并确认产物所有配置写完开始构建测试。在IDEA右侧找到Maven面板展开Lifecycle双击package。这个操作会按顺序走完validate、compile、test、package整个生命周期最终在target目录下生成jar文件。也可以直接在IDEA的Terminal里执行mvn package两种方式等价区别仅是前者用的是IDEA内置的Maven配置后者用的是你命令行里配置的独立Maven。我一般直接用mvn package这样环境变量对不对一目了然不会被IDEA内置配置掩盖问题。构建成功后检查两个地方target/tutorialMod.jar是否生成——这是Maven的输出产物。游戏根目录的mods文件夹里是否出现同名jar——这是antrun插件复制过去的结果。只要这两个文件都存在配置就通了。然后启动游戏注意要用withmod模式的启动方式进入。在ModTheSpire的加载界面里勾选BaseMod、ModTheSpire和你刚输出的tutorialMod点运行。进入游戏后打开Mod菜单应该能看到你在ModTheSpire.json里写的名称和描述信息。此时这个Mod还没有任何功能只是个空壳但它已经证明整条链路是通的。接下来全部的工作就是往这个壳里写逻辑。5. 避坑排查环境配置与构建环节的常见问题5.1 构建显示BUILD SUCCESS但游戏里看不到我的Mod现象mvn package跑完日志输出BUILD SUCCESSIDEA的target目录里jar也存在但启动游戏后ModTheSpire界面里根本没有这个Mod的选项。原因最典型的两个。一是jar没有被复制到ModTheSpire实际扫描的目录里。你要确认加载器到底扫的是哪个目录——大多数情况下是游戏根目录下的mods文件夹但如果你把jar直接扔到结合了创意工坊的目录里扫描范围可能会被加载器配置影响。二是ModTheSpire.json没被正确打进jar包内部或者json格式有误加载器解析失败后直接跳过。解决先解开jar看内部结构。把jar用压缩软件打开确认ModTheSpire.json在jar包的根目录下而不是躺在某个子文件夹里。然后检查游戏mods目录下的jar文件是否真的存在且大小与target下的产物一致。最后在游戏里点运行时注意看加载日志它会打印每个Mod的加载状态被跳过的项目会显示具体原因这是最直接的判据。日志里记载的信息远比IDE里那行BUILD SUCCESS真实。5.2 路径里用反斜杠Maven报“系统找不到指定的路径”现象pom.xml里steam.path写的是E:\SteamLibrary\steamapps构建时提示找不到路径但是资源管理器里路径明明存在。原因XML规范里反斜杠是转义字符后面跟着的字符会被组合解析。\S、\s这类组合在XML解析时行为不稳定路径就这样被悄悄改写了。这个问题在Windows用户里极其常见。解决把steam.path里的反斜杠全部改成正斜杠E:/SteamLibrary/steamapps。Maven在Windows下完全支持正斜杠路径。如果你特别想用反斜杠那就写成E:\\SteamLibrary\\steamapps双反斜杠是XML里的正确转义方式但可读性差得多。从这以后我凡是写XML里的路径一律正斜杠不是玄学是避免解释器做多余事。5.3 命令行执行mvn提示“不是内部或外部命令”现象新开一个CMD窗口执行mvn -version系统提示mvn不是内部或外部命令也不是可运行的程序。原因Maven的bin目录没有正确加入Path环境变量。这一步常见的错误有MAVEN_HOME变量名拼错、Path里写成了%MAVEN_HOME%\bin;多余的分号、或者是修改环境变量后没有新开终端窗口直接就在旧窗口里跑了。解决重新打开环境变量编辑界面确认MAVEN_HOME指向Maven解压目录本身不是bin目录确认Path里的条目是%MAVEN_HOME%\bin然后彻底关掉所有命令行窗口重新打开一个再试。这个问题的排查顺序永远是先看变量值再看窗口是否新开。我见过最离谱的情况是用户把MAVEN_HOME直接设成了E:\Maven\apache-maven-3.3.9\bin然后又在Path里加了一次bin双重叠加后果就是mvn执行时报找不到某个文件排查起来绕了很大一圈。5.4 修改pom.xml后IDEA报依赖错误右侧Maven面板一片红现象复制教程的pom.xml后IDEA的Maven面板刷新时显示一堆依赖错误日志右键项目跑package直接报错。原因多数情况下是依赖路径里的jar文件不存在。system scope的依赖不会自动从远程下载路径只要有一点偏差IDE就会显示红色报错。另外有可能是复制XML时漏了标签比如properties里少写了一个闭合标签整个pom结构就崩了。解决先看IDEA的Event Log或Maven面板的输出它会具体报告哪个依赖的哪条路径失效。回去逐一核对2.3节里那张表格尤其是workshop目录下的两个数字ID最常错的就是这里。XML结构问题则借助格式化工具或者直接在IDEA里打开pom.xmlIDE的XML解析器会告诉你第几行有语法错误。改完之后点Maven面板顶部的刷新按钮重新导入而不是直接跑构建。5.5 加载Mod后日志显示类找不到或版本不匹配现象ModTheSpire加载时日志打印ClassNotFoundException或者提示某个类的方法签名对不上。原因最可能的是ModTheSpire和BaseMod的版本与你当前游戏版本不匹配。游戏更新后创意工坊里的BaseMod和ModTheSpire如果没有同步更新Mod运行时会引用到过期的API。另一种可能是你的jar包里混入了编译期打包进去的旧依赖类干扰了类加载。解决把创意工坊里的三个库重新订阅并强制更新到最新版同时确认你的sts_version和mts_version与日志中显示的实际版本一致。这个不用修改代码就能解决纯粹是环境匹配问题。6. 验证跑通从加载日志到第一个监听函数构建成功只是一个开始真正证明Mod活着要看游戏里跑起来之后的行为。我每次装完环境都会先做一次空壳验证再写一段代码做交互验证。先写第一个能产生输出的小类在src/main/java下建一个包名字取小写的modid然后在包里新建一个类文件比如Tutorial.javapackage tutorial; import com.evacipated.cardcrawl.modthespire.lib.SpireInitializer; SpireInitializer public class Tutorial { public Tutorial() { } public static void initialize() { new Tutorial(); System.out.print(hello world! 5*630); System.out.print(5 * 6 30); System.out.print(end of line!\n22 4); } }这段代码里SpireInitializer注解告诉ModTheSpire这个类的initialize()方法是整个Mod的入口。initialize()里new Tutorial()是调构造函数创建对象然后连续三行输出打印字符串和表达式计算结果。这段代码加载成功后ModTheSpire的日志框里能看到hello world! 5*63060这样的输出开头还会带一个类似2ms的时间标记表示加载这个类花了多长时间。看到这个log环境才叫真正的通。在IDEA里执行mvn package把新jar构建并复制到游戏mods目录然后以withmod模式启动游戏。这次留意ModTheSpire的日志面板或游戏的log输出窗口。如果控制台出现了这些输出无脑下一步即可。光有输出还不够我要再验证一步Mod是否真的在和游戏里的对象互动。把类改成这样package tutorial; import basemod.BaseMod; import basemod.interfaces.PostDrawSubscriber; import com.evacipated.cardcrawl.modthespire.lib.SpireInitializer; import com.megacrit.cardcrawl.cards.AbstractCard; SpireInitializer public class Tutorial implements PostDrawSubscriber { public Tutorial() { BaseMod.subscribe(this); } public static void initialize() { new Tutorial(); } Override public void receivePostDraw(AbstractCard abstractCard) { System.out.println(abstractCard.name); } }PostDrawSubscriber是BaseMod提供的一个接口Mod实现了它并在构造函数里BaseMod.subscribe(this)完成订阅之后每次玩家抽牌游戏都会调用receivePostDraw方法参数就是被抽到的那张牌的对象。abstractCard.name是这张卡的名字输出到log里。如果你进了游戏抽一张牌日志里就出现这张牌的名字说明你的Mod已经能接收游戏事件、读取游戏对象整个开发链路彻底打通了。从这以后每次新配环境我强制自己走一遍固定验证流程先跑java -version和mvn -version确认基础环境再构建空壳Mod确认加载最后用监听函数确认事件互动三关全部过了才放心开始写正式代码。这套流程救过我很多次——有次我把ModTheSpire.json里的modid改了一个字母构建日志一点错没有但游戏里出现了两个Mod条目旧的那个怎么都加载不出代码排查到最后才发现是modid、包名、类名三者没对齐。从那以后每次构建前我都会把modid、包名、类名这三样东西对照着读一遍再走一遍上面的验证清单。希望帮到你。本文还有配套的精品资源点击获取