簡(jiǎn)介面向《殺戮尖塔》模組開(kāi)發(fā)初學(xué)者的入門(mén)指南旨在幫助沒(méi)有Java與Mod經(jīng)驗(yàn)的玩家從零搭建MOD開(kāi)發(fā)環(huán)境并完成第一個(gè)可運(yùn)行的MOD項(xiàng)目。教程圍繞modthespire、stslib和basemod三大支持庫(kù)展開(kāi)清楚解釋它們?nèi)绾卧谟螒虮倔w與自定義代碼之間建立接口同時(shí)覆蓋IntelliJ IDEA安裝、Maven環(huán)境變量配置、pom.xml編輯與依賴(lài)聲明等關(guān)鍵環(huán)節(jié)。資源以1個(gè)PDF文檔封裝大小約1.5MB結(jié)構(gòu)緊湊包含游戲本體安裝、創(chuàng)意工坊支持庫(kù)訂閱、開(kāi)發(fā)環(huán)境搭建、構(gòu)建步驟以及Java語(yǔ)法基礎(chǔ)等章節(jié)并配有控制臺(tái)輸出、變量、函數(shù)、類(lèi)作用域、監(jiān)聽(tīng)函數(shù)與繼承等示例講解。通過(guò)Maven構(gòu)建時(shí)如何指定Steam游戲庫(kù)路徑、如何引用BaseMod依賴(lài)等細(xì)節(jié)也有直觀展示適合希望快速入門(mén)的玩家邊看邊練。目前已有2121人學(xué)習(xí)下載能夠幫助讀者從環(huán)境準(zhǔn)備到代碼實(shí)現(xiàn)逐步建立起對(duì)MOD結(jié)構(gòu)的基本認(rèn)知適合作為殺戮尖塔Mod開(kāi)發(fā)的第一份學(xué)習(xí)資料。1. 做殺戮尖塔Mod前先把三件事想清楚殺戮尖塔的Mod開(kāi)發(fā)說(shuō)到底是給一個(gè)Java 8時(shí)代的老游戲?qū)懲鈷齑a這句話(huà)決定了后面所有的版本選擇。很多第一次上手的人栽在同一個(gè)地方按最新教程裝了最新JDK和最新Maven結(jié)果ModTheSpire加載器根本不認(rèn)或者構(gòu)建出的jar包進(jìn)游戲就閃退?；艘煌砩献詈蟀l(fā)現(xiàn)是版本和路徑的問(wèn)題。這篇教程把游戲本體、三大支持庫(kù)、IDE、Maven這一整條鏈路的安裝和配置走一遍所有參數(shù)都給你拆開(kāi)講照著做就能把第一個(gè)能加載的jar跑出來(lái)。適合以前沒(méi)配過(guò)Java環(huán)境、對(duì)創(chuàng)意工坊目錄結(jié)構(gòu)不熟、或者卡在pom.xml上不知道怎么改的人。裝好這套環(huán)境你才能開(kāi)始談寫(xiě)卡牌、寫(xiě)事件、改機(jī)制。2. 裝依賴(lài)游戲本體、ModTheSpire、BaseMod與stslib的下載與訂閱2.1 游戲本體買(mǎi)了不一定能馬上開(kāi)發(fā)游戲本體是全部工作的基礎(chǔ)但“裝了游戲”和“能開(kāi)發(fā)Mod”是兩回事。很多教程把這一步標(biāo)個(gè)“略”實(shí)際上這里有個(gè)前置條件至少用普通模式啟動(dòng)過(guò)一次游戲讓Steam把游戲文件完整解壓落盤(pán)。新下載的游戲有時(shí)候文件還沒(méi)就緒直接開(kāi)Mod加載器會(huì)報(bào)文件缺失。開(kāi)發(fā)時(shí)我們需要的是游戲根目錄下的這個(gè)文件SteamLibrary/steamapps/common/SlayTheSpire/desktop-1.0.jar這是游戲的主程序jar也就是Mod要注入的目標(biāo)本體。后面的pom.xml會(huì)直接用系統(tǒng)路徑引用它所以在開(kāi)工之前先找到你的SteamLibrary在哪。Steam默認(rèn)裝的路徑通常是C:\Program Files (x86)\Steam\steamapps但很多人的游戲庫(kù)在別的盤(pán)這個(gè)路徑記下來(lái)后面配置里要反復(fù)用。如果游戲剛裝好我的建議是先普通模式啟動(dòng)一次看看能不能正常進(jìn)游戲。能進(jìn)再關(guān)掉繼續(xù)配環(huán)境。別一上來(lái)就想著上Mod先確認(rèn)本體是好的否則后面所有報(bào)錯(cuò)你都沒(méi)法判斷是游戲問(wèn)題還是Mod問(wèn)題。2.2 創(chuàng)意工坊訂閱三大庫(kù)每個(gè)庫(kù)的職責(zé)先分清殺戮尖塔的Mod生態(tài)依賴(lài)三個(gè)Steam創(chuàng)意工坊模組ModTheSpire、BaseMod、stslib。這三者分工不同訂閱之前先把職責(zé)理清楚后面排查問(wèn)題會(huì)省很多時(shí)間ModTheSpireMod加載器。沒(méi)有它游戲啟動(dòng)時(shí)不會(huì)掃描和加載任何Mod jar。它負(fù)責(zé)識(shí)別ModTheSpire.json、執(zhí)行SpireInitializer注解、打印加載日志。也就是說(shuō)你的Mod寫(xiě)了代碼靠的是它來(lái)拉起。BaseModMod API支持庫(kù)。提供大量與游戲交互的接口比如監(jiān)聽(tīng)抽牌事件、受傷事件、戰(zhàn)斗結(jié)束事件以及注冊(cè)卡牌、角色、藥水的API。寫(xiě)Mod基本離不開(kāi)它。stslib擴(kuò)展庫(kù)。提供了不少現(xiàn)成的卡牌動(dòng)作、UI組件和機(jī)制模板不是每個(gè)Mod都必須用但推薦先訂閱上一方面測(cè)試別人的Mod經(jīng)常需要它另一方面以后你用到特定功能時(shí)不用再回頭補(bǔ)。訂閱方式很簡(jiǎn)單在Steam客戶(hù)端里打開(kāi)《殺戮尖塔》的商店頁(yè)面進(jìn)入創(chuàng)意工坊分別搜索這三個(gè)名字點(diǎn)訂閱。等Steam自動(dòng)下載完成即可。需要特別提醒一點(diǎn)訂閱只是加入下載隊(duì)列不等于已經(jīng)下載完成。Steam創(chuàng)意工坊的模組是異步下載的你得切到Steam的“下載”頁(yè)面確認(rèn)這三個(gè)都到了100%再去下一步。很多人卡在“我訂閱了為什么游戲里看不到”這個(gè)問(wèn)題上原因往往就是下載根本沒(méi)完成。2.3 確認(rèn)三個(gè)jar的落盤(pán)位置創(chuàng)意工坊訂閱的模組下載完成后會(huì)落在SteamLibrary的workshop目錄里路徑規(guī)律是SteamLibrary/steamapps/workshop/content/646570/模組ID/模組文件.jar這里的646570是殺戮尖塔在Steam創(chuàng)意工坊的內(nèi)容ID。三個(gè)依賴(lài)庫(kù)中BaseMod和ModTheSpire的jar路徑在后續(xù)pom.xml里會(huì)直接用到必須提前確認(rèn)。下面是我這邊的路徑示例文件作用預(yù)期位置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擴(kuò)展庫(kù)SteamLibrary/steamapps/workshop/content/646570/對(duì)應(yīng)ID/StSLib.jar注意1605833019和1605060445這兩個(gè)數(shù)字是BaseMod和ModTheSpire在創(chuàng)意工坊里的固定ID后面配置依賴(lài)時(shí)要用。stslib的ID不用強(qiáng)行記到時(shí)候在workshop目錄里翻一下就能找到但你要記住它存在。打開(kāi)資源管理器把上面的路徑逐個(gè)走一遍確認(rèn)這些jar文件都真實(shí)存在。這一步偷懶不得——pom.xml里的systemPath寫(xiě)的是絕對(duì)路徑路徑錯(cuò)一個(gè)字符構(gòu)建就會(huì)報(bào)“系統(tǒng)找不到指定的路徑”而且報(bào)錯(cuò)信息往往要到很后面才暴露排查起來(lái)相當(dāng)難受。如果你用的是Mac或Linux路徑結(jié)構(gòu)類(lèi)似只是前綴從E:\SteamLibrary變成/home/你的用戶(hù)名/.steam/steam/steamapps之類(lèi)的掛載位置原理完全一樣照著后面的邏輯替換即可。3. 搭開(kāi)發(fā)環(huán)境JDK 8、IDEA社區(qū)版與Maven的Windows配置3.1 為什么選JDK 8而不是最新版殺戮尖塔本體是Java 8時(shí)代的工程Mod最終要注入到這個(gè)老工程里運(yùn)行。官方推薦和大多數(shù)Mod作者使用的都是JDK 8你去看pom.xml里的編譯配置寫(xiě)的是source 1.8和target 1.8意思就是編譯出Java 8版本的class文件。有人會(huì)問(wèn)我用JDK 17編譯時(shí)把target設(shè)成1.8行不行行是行但沒(méi)必要給自己找麻煩。高版本JDK在編譯老項(xiàng)目時(shí)經(jīng)常報(bào)一些莫名其妙的警告和錯(cuò)誤比如Invalid source release或者對(duì)某些廢棄API的報(bào)錯(cuò)調(diào)試起來(lái)純屬浪費(fèi)時(shí)間。配環(huán)境的原則是匹配目標(biāo)運(yùn)行時(shí)不是追求工具最新版。下載JDK時(shí)選8系列的最新更新版本即可裝完后在命令行驗(yàn)證java -version期望輸出java version 1.8.0_202如果輸出版本號(hào)還是1.8開(kāi)頭說(shuō)明裝對(duì)了。如果你機(jī)器上已經(jīng)裝了更高版本的JDK也不用卸載后面在IDEA里新建項(xiàng)目時(shí)單獨(dú)給這個(gè)項(xiàng)目指定JDK 8的路徑就行互不干擾。我已經(jīng)不止一次看到有人因?yàn)椴幌雱?dòng)原有環(huán)境用高版本JDK硬編結(jié)果在target 1.8和依賴(lài)包之間反復(fù)報(bào)錯(cuò)最后還是乖乖裝了8。裝一次一勞永逸。3.2 IDEA社區(qū)版免費(fèi)夠用Java開(kāi)發(fā)的IDE基本就是在Eclipse和IntelliJ IDEA之間選兩個(gè)都有免費(fèi)版本。這篇教程以IDEA為例因?yàn)樗腗aven支持和代碼提示對(duì)新手更友好而且社區(qū)版已經(jīng)覆蓋了開(kāi)發(fā)Mod需要的全部功能。到IDEA官網(wǎng)下載Community版本也就是社區(qū)版。安裝過(guò)程中按默認(rèn)選項(xiàng)走即可建議勾選“創(chuàng)建桌面快捷方式”和“添加到PATH”后面在命令行里執(zhí)行maven命令會(huì)更方便。安裝完成后先不要急著建項(xiàng)目下一步先把Maven配好因?yàn)镮DEA新建Maven項(xiàng)目時(shí)要調(diào)用本機(jī)的Maven配置。3.3 Maven下載、解壓、配MAVEN_HOMEMaven是一個(gè)構(gòu)建工具負(fù)責(zé)拉依賴(lài)、編譯、打包、輸出jar。殺戮尖塔Mod項(xiàng)目里pom.xml描述了項(xiàng)目結(jié)構(gòu)Maven按這個(gè)文件去執(zhí)行構(gòu)建。Windows下的配置步驟如下下載Maven的二進(jìn)制壓縮包版本選3.3.9與這篇教程配套的pom.xml版本一致。解壓到一個(gè)路徑中不含中文、不含空格的目錄比如E:\Maven\apache-maven-3.3.9。含中文或空格的路徑在后續(xù)構(gòu)建時(shí)可能引發(fā)奇怪的報(bào)錯(cuò)直接避掉比事后排查劃算。然后是設(shè)置環(huán)境變量右鍵“此電腦”選擇“屬性”進(jìn)入“高級(jí)系統(tǒng)設(shè)置”點(diǎn)擊“環(huán)境變量”。在系統(tǒng)變量區(qū)域點(diǎn)擊“新建”變量名填MAVEN_HOME變量值填Maven解壓后的完整路徑也就是E:\Maven\apache-maven-3.3.9。找到系統(tǒng)變量里的Path雙擊編輯點(diǎn)擊“新建”填入%MAVEN_HOME%\bin。點(diǎn)擊確定保存所有對(duì)話(huà)框然后新開(kāi)一個(gè)命令行窗口。這里有個(gè)高頻翻車(chē)點(diǎn)很多人改完環(huán)境變量后在一個(gè)舊的命令行窗口里執(zhí)行命令發(fā)現(xiàn)mvn不存在就懷疑配置錯(cuò)了。環(huán)境變量在舊窗口里不會(huì)刷新必須全部關(guān)掉重開(kāi)才生效。新開(kāi)窗口這一步不是儀式感是實(shí)打?qū)嵉目印?.4 組合驗(yàn)證java與mvn一起跑打開(kāi)新命令行窗口依次執(zhí)行java -version mvn -versionmvn -version的輸出應(yīng)該包含類(lèi)似這樣的信息Apache Maven 3.3.9 Java version: 1.8.0_202只要這兩條都能正常輸出開(kāi)發(fā)環(huán)境就通了。記住這個(gè)組合命令以后排查環(huán)境問(wèn)題第一條就是它。Java和Maven任何一個(gè)輸出異常你的Mod項(xiàng)目整個(gè)就沒(méi)法構(gòu)建所以先把這兩行跑順再往下走。4. 建項(xiàng)目pom.xml依賴(lài)注入與ModTheSpire.json注冊(cè)4.1 在IDEA里新建Maven項(xiàng)目打開(kāi)IDEA創(chuàng)建新項(xiàng)目選擇Maven類(lèi)型。這里有一步容易困惑IDEA會(huì)問(wèn)你要不要選archetype模板這里是不要勾選任何archetype的直接按最簡(jiǎn)單的骨架創(chuàng)建。填寫(xiě)項(xiàng)目信息GroupId填org.exampleArtifactId填tutorial項(xiàng)目名取tutorial。ArtifactId會(huì)作為工程標(biāo)識(shí)的一部分后面生成的jar包默認(rèn)也叫這個(gè)名字建議取一個(gè)不帶空格、全小寫(xiě)的名字避免后續(xù)路徑和文件名出問(wèn)題。創(chuàng)建完成后IDEA右下角通常會(huì)彈出一個(gè)提示說(shuō)檢測(cè)到Maven配置發(fā)生變化這時(shí)點(diǎn)擊“Import Changes”或“Enable Auto-Import”。如果你沒(méi)看到提示等Maven自動(dòng)導(dǎo)入完成也可以。這時(shí)候項(xiàng)目目錄結(jié)構(gòu)大致是這樣的tutorial/ ├── .idea/ # IDE輔助文件不用管 ├── src/ │ ├── main/ │ │ ├── java/ # 存放Java代碼 │ │ └── resources/ # 存放json、圖片等素材 │ └── test/ # Maven自動(dòng)生成的測(cè)試目錄 └── pom.xml # Maven構(gòu)建配置.idea文件夾是IDEA自己的與Mod無(wú)關(guān)。src/main/java是你寫(xiě)代碼的地方src/main/resources放ModTheSpire.json這類(lèi)資源文件。Maven會(huì)自動(dòng)處理test目錄相關(guān)的細(xì)節(jié)暫時(shí)不用管。4.2 pom.xml逐塊拆解路徑、依賴(lài)、構(gòu)建pom.xml是這個(gè)項(xiàng)目的命根子它負(fù)責(zé)告訴Maven三件事依賴(lài)哪些jar、編譯成什么版本、構(gòu)建完把jar復(fù)制到哪里。下面這個(gè)是我配好的完整配置注意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逐塊說(shuō)明一下關(guān)鍵參數(shù)。properties里的steam.path是整個(gè)配置文件的基礎(chǔ)路徑后面所有系統(tǒng)依賴(lài)都用${steam.path}拼接。這個(gè)值要填你的Steam庫(kù)根目錄路徑分隔符建議用正斜杠。Windows下很多人習(xí)慣寫(xiě)E:\SteamLibrary\steamapps但在XML里反斜杠是轉(zhuǎn)義符與后面的字符組合后可能被解析成別的東西。寫(xiě)成E:/SteamLibrary/steamapps是更穩(wěn)妥的寫(xiě)法能少踩一個(gè)坑。dependencies里三個(gè)依賴(lài)是Mod開(kāi)發(fā)的基石BaseMod.jar提供API接口desktop-1.0.jar是游戲本體ModTheSpire.jar是加載器。注意這里沒(méi)有引入stslib因?yàn)樗皇敲總€(gè)Mod都直接用到。等你后續(xù)代碼里真的要調(diào)用stslib里的類(lèi)時(shí)再把它的jar路徑以同樣方式追加一條依賴(lài)即可。三個(gè)依賴(lài)的scope都標(biāo)為system意思是Maven不走中央倉(cāng)庫(kù)拉取直接讀你本機(jī)的文件。version填1.0只是占位符system范圍下的依賴(lài)版本號(hào)不會(huì)被實(shí)際校驗(yàn)。build里的finalName決定了輸出jar的名字這里填tutorialMod。maven-compiler-plugin配置了source和target都是1.8即編譯產(chǎn)物的Java版本。maven-antrun-plugin則是把package階段輸出的jar文件復(fù)制到游戲的mods目錄這樣構(gòu)建完直接啟動(dòng)游戲就能在加載器里看到。這里的tofile路徑后半段common/SlayTheSpire/mods需要你在游戲根目錄下手動(dòng)創(chuàng)建一個(gè)mods文件夾否則antrun復(fù)制時(shí)會(huì)報(bào)目標(biāo)路徑不存在。所有依賴(lài)的路徑都要和你在2.3節(jié)里實(shí)際確認(rèn)過(guò)的位置一一對(duì)應(yīng)。尤其是workshop/content/646570/后面的數(shù)字ID不能憑記憶寫(xiě)去資源管理器里親眼確認(rèn)過(guò)再填進(jìn)配置。4.3 ModTheSpire.json讓加載器認(rèn)識(shí)你的Mod打開(kāi)src/main/resources目錄在里面新建一個(gè)文件命名為ModTheSpire.json。這個(gè)文件的作用是告訴ModTheSpire加載器我這個(gè)Mod叫什么、是誰(shuí)寫(xiě)的、依賴(lài)誰(shuí)、版本是多少。內(nèi)容如下{ 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是這個(gè)Mod的唯一標(biāo)識(shí)加載器靠它區(qū)分不同的Mod所以全小寫(xiě)且不要有空格。它最好和你在4.1節(jié)里填的ArtifactId保持一致后面寫(xiě)代碼時(shí)包名也會(huì)用到它三者對(duì)齊能省很多不必要的加載報(bào)錯(cuò)。name是顯示在ModTheSpire加載列表里的名字可以隨意。author_list是一個(gè)數(shù)組可以寫(xiě)多個(gè)作者用方括號(hào)和逗號(hào)分隔。description是一段文本描述會(huì)顯示在游戲的Mod菜單里。version和mts_version代表你的Mod版本號(hào)和ModTheSpire的版本號(hào)。dependencies數(shù)組里寫(xiě)basemod表示你的Mod在加載時(shí)要先加載BaseMod這在游戲里會(huì)表現(xiàn)成加載順序的依賴(lài)關(guān)系。sts_version對(duì)應(yīng)的是游戲版本這里填的是教程所用的示例版本。你實(shí)際填的時(shí)候可以打開(kāi)ModTheSpire的加載日志里面會(huì)顯示它識(shí)別到的游戲版本信息以日志為準(zhǔn)。JSON格式的注意點(diǎn)集中在括號(hào)配對(duì)花括號(hào){}表示對(duì)象方括號(hào)[]表示數(shù)組逗號(hào)分隔同級(jí)元素。寫(xiě)錯(cuò)了IDE會(huì)直接標(biāo)紅但如果IDE沒(méi)標(biāo)紅也不代表沒(méi)問(wèn)題——這個(gè)文件里如果有多個(gè)對(duì)象漏一個(gè)逗號(hào)這種錯(cuò)誤IDE經(jīng)常能發(fā)現(xiàn)。4.4 執(zhí)行package構(gòu)建并確認(rèn)產(chǎn)物所有配置寫(xiě)完開(kāi)始構(gòu)建測(cè)試。在IDEA右側(cè)找到Maven面板展開(kāi)Lifecycle雙擊package。這個(gè)操作會(huì)按順序走完validate、compile、test、package整個(gè)生命周期最終在target目錄下生成jar文件。也可以直接在IDEA的Terminal里執(zhí)行mvn package兩種方式等價(jià)區(qū)別僅是前者用的是IDEA內(nèi)置的Maven配置后者用的是你命令行里配置的獨(dú)立Maven。我一般直接用mvn package這樣環(huán)境變量對(duì)不對(duì)一目了然不會(huì)被IDEA內(nèi)置配置掩蓋問(wèn)題。構(gòu)建成功后檢查兩個(gè)地方target/tutorialMod.jar是否生成——這是Maven的輸出產(chǎn)物。游戲根目錄的mods文件夾里是否出現(xiàn)同名jar——這是antrun插件復(fù)制過(guò)去的結(jié)果。只要這兩個(gè)文件都存在配置就通了。然后啟動(dòng)游戲注意要用withmod模式的啟動(dòng)方式進(jìn)入。在ModTheSpire的加載界面里勾選BaseMod、ModTheSpire和你剛輸出的tutorialMod點(diǎn)運(yùn)行。進(jìn)入游戲后打開(kāi)Mod菜單應(yīng)該能看到你在ModTheSpire.json里寫(xiě)的名稱(chēng)和描述信息。此時(shí)這個(gè)Mod還沒(méi)有任何功能只是個(gè)空殼但它已經(jīng)證明整條鏈路是通的。接下來(lái)全部的工作就是往這個(gè)殼里寫(xiě)邏輯。5. 避坑排查環(huán)境配置與構(gòu)建環(huán)節(jié)的常見(jiàn)問(wèn)題5.1 構(gòu)建顯示BUILD SUCCESS但游戲里看不到我的Mod現(xiàn)象mvn package跑完日志輸出BUILD SUCCESSIDEA的target目錄里jar也存在但啟動(dòng)游戲后ModTheSpire界面里根本沒(méi)有這個(gè)Mod的選項(xiàng)。原因最典型的兩個(gè)。一是jar沒(méi)有被復(fù)制到ModTheSpire實(shí)際掃描的目錄里。你要確認(rèn)加載器到底掃的是哪個(gè)目錄——大多數(shù)情況下是游戲根目錄下的mods文件夾但如果你把jar直接扔到結(jié)合了創(chuàng)意工坊的目錄里掃描范圍可能會(huì)被加載器配置影響。二是ModTheSpire.json沒(méi)被正確打進(jìn)jar包內(nèi)部或者json格式有誤加載器解析失敗后直接跳過(guò)。解決先解開(kāi)jar看內(nèi)部結(jié)構(gòu)。把jar用壓縮軟件打開(kāi)確認(rèn)ModTheSpire.json在jar包的根目錄下而不是躺在某個(gè)子文件夾里。然后檢查游戲mods目錄下的jar文件是否真的存在且大小與target下的產(chǎn)物一致。最后在游戲里點(diǎn)運(yùn)行時(shí)注意看加載日志它會(huì)打印每個(gè)Mod的加載狀態(tài)被跳過(guò)的項(xiàng)目會(huì)顯示具體原因這是最直接的判據(jù)。日志里記載的信息遠(yuǎn)比IDE里那行BUILD SUCCESS真實(shí)。5.2 路徑里用反斜杠Maven報(bào)“系統(tǒng)找不到指定的路徑”現(xiàn)象pom.xml里steam.path寫(xiě)的是E:\SteamLibrary\steamapps構(gòu)建時(shí)提示找不到路徑但是資源管理器里路徑明明存在。原因XML規(guī)范里反斜杠是轉(zhuǎn)義字符后面跟著的字符會(huì)被組合解析。\S、\s這類(lèi)組合在XML解析時(shí)行為不穩(wěn)定路徑就這樣被悄悄改寫(xiě)了。這個(gè)問(wèn)題在Windows用戶(hù)里極其常見(jiàn)。解決把steam.path里的反斜杠全部改成正斜杠E:/SteamLibrary/steamapps。Maven在Windows下完全支持正斜杠路徑。如果你特別想用反斜杠那就寫(xiě)成E:\\SteamLibrary\\steamapps雙反斜杠是XML里的正確轉(zhuǎn)義方式但可讀性差得多。從這以后我凡是寫(xiě)XML里的路徑一律正斜杠不是玄學(xué)是避免解釋器做多余事。5.3 命令行執(zhí)行mvn提示“不是內(nèi)部或外部命令”現(xiàn)象新開(kāi)一個(gè)CMD窗口執(zhí)行mvn -version系統(tǒng)提示mvn不是內(nèi)部或外部命令也不是可運(yùn)行的程序。原因Maven的bin目錄沒(méi)有正確加入Path環(huán)境變量。這一步常見(jiàn)的錯(cuò)誤有MAVEN_HOME變量名拼錯(cuò)、Path里寫(xiě)成了%MAVEN_HOME%\bin;多余的分號(hào)、或者是修改環(huán)境變量后沒(méi)有新開(kāi)終端窗口直接就在舊窗口里跑了。解決重新打開(kāi)環(huán)境變量編輯界面確認(rèn)MAVEN_HOME指向Maven解壓目錄本身不是bin目錄確認(rèn)Path里的條目是%MAVEN_HOME%\bin然后徹底關(guān)掉所有命令行窗口重新打開(kāi)一個(gè)再試。這個(gè)問(wèn)題的排查順序永遠(yuǎn)是先看變量值再看窗口是否新開(kāi)。我見(jiàn)過(guò)最離譜的情況是用戶(hù)把MAVEN_HOME直接設(shè)成了E:\Maven\apache-maven-3.3.9\bin然后又在Path里加了一次bin雙重疊加后果就是mvn執(zhí)行時(shí)報(bào)找不到某個(gè)文件排查起來(lái)繞了很大一圈。5.4 修改pom.xml后IDEA報(bào)依賴(lài)錯(cuò)誤右側(cè)Maven面板一片紅現(xiàn)象復(fù)制教程的pom.xml后IDEA的Maven面板刷新時(shí)顯示一堆依賴(lài)錯(cuò)誤日志右鍵項(xiàng)目跑package直接報(bào)錯(cuò)。原因多數(shù)情況下是依賴(lài)路徑里的jar文件不存在。system scope的依賴(lài)不會(huì)自動(dòng)從遠(yuǎn)程下載路徑只要有一點(diǎn)偏差I(lǐng)DE就會(huì)顯示紅色報(bào)錯(cuò)。另外有可能是復(fù)制XML時(shí)漏了標(biāo)簽比如properties里少寫(xiě)了一個(gè)閉合標(biāo)簽整個(gè)pom結(jié)構(gòu)就崩了。解決先看IDEA的Event Log或Maven面板的輸出它會(huì)具體報(bào)告哪個(gè)依賴(lài)的哪條路徑失效?；厝ブ鹨缓藢?duì)2.3節(jié)里那張表格尤其是workshop目錄下的兩個(gè)數(shù)字ID最常錯(cuò)的就是這里。XML結(jié)構(gòu)問(wèn)題則借助格式化工具或者直接在IDEA里打開(kāi)pom.xmlIDE的XML解析器會(huì)告訴你第幾行有語(yǔ)法錯(cuò)誤。改完之后點(diǎn)Maven面板頂部的刷新按鈕重新導(dǎo)入而不是直接跑構(gòu)建。5.5 加載Mod后日志顯示類(lèi)找不到或版本不匹配現(xiàn)象ModTheSpire加載時(shí)日志打印ClassNotFoundException或者提示某個(gè)類(lèi)的方法簽名對(duì)不上。原因最可能的是ModTheSpire和BaseMod的版本與你當(dāng)前游戲版本不匹配。游戲更新后創(chuàng)意工坊里的BaseMod和ModTheSpire如果沒(méi)有同步更新Mod運(yùn)行時(shí)會(huì)引用到過(guò)期的API。另一種可能是你的jar包里混入了編譯期打包進(jìn)去的舊依賴(lài)類(lèi)干擾了類(lèi)加載。解決把創(chuàng)意工坊里的三個(gè)庫(kù)重新訂閱并強(qiáng)制更新到最新版同時(shí)確認(rèn)你的sts_version和mts_version與日志中顯示的實(shí)際版本一致。這個(gè)不用修改代碼就能解決純粹是環(huán)境匹配問(wèn)題。6. 驗(yàn)證跑通從加載日志到第一個(gè)監(jiān)聽(tīng)函數(shù)構(gòu)建成功只是一個(gè)開(kāi)始真正證明Mod活著要看游戲里跑起來(lái)之后的行為。我每次裝完環(huán)境都會(huì)先做一次空殼驗(yàn)證再寫(xiě)一段代碼做交互驗(yàn)證。先寫(xiě)第一個(gè)能產(chǎn)生輸出的小類(lèi)在src/main/java下建一個(gè)包名字取小寫(xiě)的modid然后在包里新建一個(gè)類(lèi)文件比如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這個(gè)類(lèi)的initialize()方法是整個(gè)Mod的入口。initialize()里new Tutorial()是調(diào)構(gòu)造函數(shù)創(chuàng)建對(duì)象然后連續(xù)三行輸出打印字符串和表達(dá)式計(jì)算結(jié)果。這段代碼加載成功后ModTheSpire的日志框里能看到hello world! 5*63060這樣的輸出開(kāi)頭還會(huì)帶一個(gè)類(lèi)似2ms的時(shí)間標(biāo)記表示加載這個(gè)類(lèi)花了多長(zhǎng)時(shí)間?？吹竭@個(gè)log環(huán)境才叫真正的通。在IDEA里執(zhí)行mvn package把新jar構(gòu)建并復(fù)制到游戲mods目錄然后以withmod模式啟動(dòng)游戲。這次留意ModTheSpire的日志面板或游戲的log輸出窗口。如果控制臺(tái)出現(xiàn)了這些輸出無(wú)腦下一步即可。光有輸出還不夠我要再驗(yàn)證一步Mod是否真的在和游戲里的對(duì)象互動(dòng)。把類(lèi)改成這樣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提供的一個(gè)接口Mod實(shí)現(xiàn)了它并在構(gòu)造函數(shù)里BaseMod.subscribe(this)完成訂閱之后每次玩家抽牌游戲都會(huì)調(diào)用receivePostDraw方法參數(shù)就是被抽到的那張牌的對(duì)象。abstractCard.name是這張卡的名字輸出到log里。如果你進(jìn)了游戲抽一張牌日志里就出現(xiàn)這張牌的名字說(shuō)明你的Mod已經(jīng)能接收游戲事件、讀取游戲?qū)ο笳麄€(gè)開(kāi)發(fā)鏈路徹底打通了。從這以后每次新配環(huán)境我強(qiáng)制自己走一遍固定驗(yàn)證流程先跑java -version和mvn -version確認(rèn)基礎(chǔ)環(huán)境再構(gòu)建空殼Mod確認(rèn)加載最后用監(jiān)聽(tīng)函數(shù)確認(rèn)事件互動(dòng)三關(guān)全部過(guò)了才放心開(kāi)始寫(xiě)正式代碼。這套流程救過(guò)我很多次——有次我把ModTheSpire.json里的modid改了一個(gè)字母構(gòu)建日志一點(diǎn)錯(cuò)沒(méi)有但游戲里出現(xiàn)了兩個(gè)Mod條目舊的那個(gè)怎么都加載不出代碼排查到最后才發(fā)現(xiàn)是modid、包名、類(lèi)名三者沒(méi)對(duì)齊。從那以后每次構(gòu)建前我都會(huì)把modid、包名、類(lèi)名這三樣?xùn)|西對(duì)照著讀一遍再走一遍上面的驗(yàn)證清單。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取