模组:創建 SMAPI 模組
← 模組:目錄
頁面仍需完善
該頁面由於下列原因被標記為不完善:
|
要為遊戲創建 SMAPI 模組?教程就在這兒。要使用模組,請參閱 使用指南。要創建內容包模組,請參閱 模組:Content Patcher。
介紹
什麼是 SMAPI 模組?
SMAPI 模組 使用改裝接口來擴展遊戲邏輯。可以在遊戲中發生某些情況時做出響應(例如,將對象放置在世界中),定期運行代碼(例如每個更新周期一次),更改遊戲的資源和數據等。SMAPI 模組使用 C# 編寫,使用 .NET Framework 和 Stardew Valley 將 XNA / MonoGame 用於遊戲邏輯(繪製到屏幕,用戶輸入等)。
為什麼模組使用 SMAPI?
SMAPI 可以做許多事情,例如:
- 將模組加載到遊戲中。沒有 SMAPI 就無法加載代碼模組。
- 提供接口和事件,能夠以其他方式與遊戲互動。有一些簡化的接口,可用於更改遊戲資源/數據,玩家配置,轉換,反映等。這些內容將在本指南的後面部分介紹。
- 在跨平台兼容時進行重構,這樣一來就不必擔心遊戲在 Linux/Mac/Windows 版本之間的差異。
- 重構模組以更新它。在常見情況下,SMAPI 會檢測並修復遊戲更新所破壞的模組代碼。
- 攔截錯誤。如果模組崩潰或發生錯誤,SMAPI 將攔截該錯誤,在控制台窗口中顯示錯誤詳細信息,並且在大多數情況下自動恢復遊戲。這意味着減少遊戲意外崩潰,並且可以更輕鬆地解決錯誤。
- 提供更新檢查。當有新版本可用時,SMAPI 會自動提醒玩家。
- 提供兼容性檢查。SMAPI 會自動檢測模組何時不兼容,並在它導致問題之前將其禁用,以防止遊戲爆炸。
我能製作一個模組嗎?
是的!本指南將幫助你逐步創建一個簡單的模組。然後你可以繼續學習,讓它做您想做的事即可。 如果你是編程新手,許多模組開發人員開始時幾乎沒有或完全沒有編程經驗。如果你下定決心,當然可以沿途學習,但是您應該為陡峭的學習曲線做好準備。剛開始時不要太過於自信,弄清楚它的時候,最好從一個小的模組開始。一開始很容易變得不知所措並放棄。模組社區非常熱情,所以不要害怕問問題!
如果你已經具備編程經驗,那應該沒問題。具有 C# 或 Java 的編程經驗將使事情變得容易,但這並不重要。如果不熟悉 C#,則可以瀏覽下面的「學習C#」參考資料以填補所有空白。
我可以不使用 SMAPI 來製作模組嗎?
當然。許多的 SMAPI 模組支持 內容包,可以讓你提供它們所使用的 JSON 文本文件、圖像等。例如,你可以 使用 Content Patcher 來編輯遊戲的貼圖並且不需要任何編程技術。本指南的其餘部分是關於創建新的 SMAPI 模組的。有關內容包,請參閱 模組:Content Patcher (或模組的文檔(如果為其他mod創建內容包)).
我在哪裏可以得到幫助?
星露谷模組社區歡迎你的到來. Feel free to ask for help in #making-mods on the Stardew Valley Discord.
開始
學習 C#
由於模組是用 C# 編寫的,因此最好先熟悉它。無需記住所有內容,但是掌握基礎知識(例如字段、方法、變量和類)將使其他所有內容都變得更加容易。
一些有用的資源:
- C# 快速學習 通過交互式示例講解C#的基礎知識。
- C# 絕對初學者的基礎知識 視頻指南將引導您完成 C# 從基本概念到事件驅動的編程(這是 SMAPI 模組經常使用的內容)。
要求
在你開始之前:
- 熟悉 模組的使用,本指南的其餘部分假定你已經熟悉使用模組。
- 安裝遊戲
- 安裝 SMAPI
- 安裝開發環境
- 在 Linux 上:安裝 MonoDevelop
- 在 Mac 上:安裝 Visual Studio for Mac. (This is a rebranded MonoDevelop.)
- 在 Windows 上:安裝 Visual Studio Community. 在安裝程序中的工作負載中選擇 .NET 桌面開發
如果你不熟悉 Visual Studio (on Windows/Mac) 或者 MonoDevelop (on Linux), 模組:IDE 參考 解釋了如何完成本指南所需的重要工作。
創建一個基礎的模組
快速開始
如果你有足夠的經驗來跳過本教程,則此部分的簡要概述如下:
快速開始 |
---|
|
創建解決方案
一個 SMAPI 模組是具有 SMAPI 調用入口方法的動態連結庫(DLL),因此要對其進行設置
- 打開 Visual Studio 或者 MonoDevelop.
- 創建 類庫 項目,選擇 .NET Framework 框架 (參閱 如何創建一個項目)。確保你選擇的是 .NET Framework 而不是 .NET Core 或者 .NET Standard
- 選擇目標框架版本為 .NET Framework 5 (參閱 如何改變目標框架)
- 添加 Pathoschild.Stardew.ModBuildConfig NuGet 包 (參閱 如何添加 NuGet 包).
- 安裝完包之後重新啟動 Visual Studio 或者 MonoDevelop
添加代碼
接下來讓我們添加一些將運行的 SMAPI 代碼
- 刪除 Class1.cs 或者 MyClass.cs 文件 (參閱 如何刪除文件).
- 在項目中添加一個 C# 類文件,取名為 ModEntry.cs (參閱 如何添加文件).
- 在此文件中輸入代碼 (把 YourProjectName 換成你的解決方案的名字):
using System; using Microsoft.Xna.Framework; using StardewModdingAPI; using StardewModdingAPI.Events; using StardewModdingAPI.Utilities; using StardewValley; namespace YourProjectName { /// <summary>模组入口点</summary> public class ModEntry : Mod { /********* ** 公共方法 *********/ /// <summary>模组的入口点,在首次加载模组后自动调用</summary> /// <param name="helper">对象 helper 提供用于编写模组的简化接口</param> public override void Entry(IModHelper helper) { helper.Events.Input.ButtonPressed += this.OnButtonPressed; //意思是将 OnButtonPressed 方法绑定到 SMAPI 的 ButtonPressed 按钮按下事件 //this 表示本对象,也就是当前的 ModEntry 类 } /********* ** 私有方法 *********/ /// <summary>在玩家按下键盘、控制器或鼠标上的按钮后引发</summary> /// <param name="sender">对象 sender 表示调用此方法的对象</param> /// <param name="e">对象 e 表示事件数据</param> private void OnButtonPressed(object sender, ButtonPressedEventArgs e) { // 如果玩家还没有进入存档,则取消执行 if (!Context.IsWorldReady) return; // 向控制台输出按下了什么按钮 this.Monitor.Log($"{Game1.player.Name} 按下了 {e.Button}.", LogLevel.Debug); } } }
以下是該代碼的功能細分:
using X;
(參閱 using directive) 使該命名空間中的類在你的代碼中可用namespace YourProjectName
(參閱 namespace keyword) 定義代碼的範圍,入門時不必擔心,因為在新建類文件時 Visual Studio 或 MonoDevelop 會自動添加它public class ModEntry : Mod
(參閱 class keyword) 創建你的模組的主類文件,並繼承 SMAPI 的 Mod 類。SMAPI 將自動檢測你的 Mod 子類,而 Mod 使你可訪問 SMAPI 的接口public override void Entry(IModHelper helper)
是將模組加載到遊戲中時 SMAPI 將調用的方法。這裏的helper
對象提供了對許多 SMAPI 接口的便捷訪問helper.Events.Input.ButtonPressed += this.OnButtonPressed;
添加了一個 '事件綁定' (i.e., a method to call) 到當按下按鈕的事件發生時. 換句話說,當一個按鈕被按下 (也就是 helper.Events.Input.ButtonPressed 事件觸發了), SMAPI 會調用你的 this.OnButtonPressed 方法。參閱 SMAPI 中的事件 獲取更多信息
添加你的清單
模組的清單為 SMAPI 提供模組的信息
- 向你的解決方案添加一個名為 manifest.json 的文本文件
- 將這些代碼複製到文件中:(注意要區分鍵值的大小寫,避免出現意外情況)
{ "Name": "<模组的名字>", "Author": "<你的名字>", "Version": "1.0.0", "Description": "<一句话简单描述你的模组是干什么的>", "UniqueID": "<你的名字>.<模组的名字>", "EntryDll": "<你的解决方案的名字>.dll", "MinimumApiVersion": "3.0.0", "UpdateKeys": [] }
- 正確填寫其中的信息,不要留着空信息
當遊戲啟動時,它將在控制台中輸出。更多信息請參閱 清單文檔
構建你的模組
- 構建項目
如果你不知道怎麼構建:在開發工具的菜單欄中選擇 項目,然後選擇 生成
如果你已經做了 創建解決方案 這一步,在構建時你的模組會自動安裝到遊戲的 Mods 文件夾中 - 通過 SMAPI 啟動遊戲
到目前為止,每當按下遊戲中的一個鍵時,該模組會向控制台窗口發送一條消息
疑難解答
如果上述教程創建的模組不能正常運行:
- 重複查看以上步驟,以確保你沒有跳過任何內容
- 檢查是否有任何的錯誤消息,也許可以解釋為什麼它不起作用:
- 在 Visual Studio 中嘗試重新構建解決方案,查看 輸出 面板 或者 錯誤列表
- 在 MonoDevelop 中點擊 Build > Rebuild All 等待處理完畢。然後點擊 "Build: XX errors, XX warnings" 在頂部的條,點擊 XX Errors 和 Build Output 選項卡
- 參閱 疑難解答.
- 如果其他所有方法均失敗,請到 Stardew Valley Discord 尋求幫助 :)
常見問題
SMAPI 的文檔在哪裏?
這只是「入門」教程。更多信息請參閱 SMAPI reference 和 topics listed on the index page.
我如何使我的模組跨平台工作?
SMAPI 將自動調整模組使其可以在 Linux、MacOS 和 Windows 上運行。但是你也應該採取一些措施來避免出現問題:
- 使用 跨平台構建配置 包以自動設置您的項目引用,這使跨平台兼容性變得更容易,並使代碼可以在任何平台上進行編譯。(如果遵循上述指南,那麼就沒問題了)
- 使用 Path.Combine 構建文件路徑,請不要對路徑分隔符進行硬編碼,因為它們不能在所有平台上都可使用
// ✘ 不要这样做!这在 Linux 和 Mac 上不会起作用 string path = this.Helper.DirectoryPath + "\assets\image.png"; // ✓ 这样才是对的 string path = Path.Combine(this.Helper.DirectoryPath, "assets", "image.png");
- 使用 this.Helper.DirectoryPath,請勿嘗試自行確定模組路徑
// ✘ 不要这样做!如果 SMAPI 重写了程序集(例如对其进行了更新或跨平台),它将崩溃 string modFolder = Assembly .GetCallingAssembly().Location; // ✓ 这样就没问题 string modFolder = this.Helper.DirectoryPath;
如何反編譯遊戲代碼?
觀察遊戲代碼的工作方式通常對開發很有用。遊戲的代碼都編譯在 StardewValley.exe 文件中,但是可以對其進行反編譯,以獲得原始代碼的近似可讀性。(由於反編譯器的限制,此功能可能無法完全發揮作用,但是能夠看到它在做什麼。)
要反編譯遊戲代碼...
- 在 Windows 上:
-
- 第一步:
- 安裝最新版本的 ILSpy
- 打開 ILSpy
- 點擊 視圖 > 選項滑動至底部的 "其他" 選項, 並啟用「始終限定成員引用」
- 在 ILSpy 打開 StardewValley.dll
- 右鍵 Stardew Valley 並選擇 保存代碼 創建反編譯的項目,可以在 Visual Studio 中打開
- 第一步:
- On Linux/MacOS:
-
- Install Visual Studio Code.
- Get the ILSpy .NET Decompiler plugin for VSCode.
- Open the Visual Studio Code Command Palette (
Command+Shift+P
), then typeilspy
to show the two commands. - Choose Decompile IL Assembly (pick file), then choose the StardewValley.exe in your game folder.
- A tree view named ILSPY DECOMPILED MEMBERS should appear in the Explorer view. This lets you expand and select various nodes to see the decompiled C# code in the editor.
要解包 XNB 數據或圖像文件,請參閱 模組:編輯 XNB 文件