模组:創建 SMAPI 模組

出自Stardew Valley Wiki
於 2021年6月12日 (六) 06:43 由 1059 Studio（討論 | 貢獻） 所做的修訂 （→‎疑难解答）
跳至導覽 跳至搜尋

製作SMAPI模組 SMAPI mascot.png

← 模組:目錄

要為遊戲創建 SMAPI 模組？教程就在這兒。要使用模組，請參閱 使用指南。要創建內容包模組，請參閱 模組:Content Patcher。

介紹

什麼是 SMAPI 模組？

SMAPI 模組 使用改裝接口來擴展遊戲邏輯。可以在遊戲中發生某些情況時做出響應（例如，將對象放置在世界中），定期運行代碼（例如每個更新周期一次），更改遊戲的資源和數據等。SMAPI 模組使用 C＃ 編寫，使用 .NET Framework 和 Stardew Valley 將 XNA / MonoGame 用於遊戲邏輯（繪製到屏幕，用戶輸入等）。

為什麼模組使用 SMAPI？

SMAPI 可以做許多事情，例如：

  1. 將模組加載到遊戲中。沒有 SMAPI 就無法加載代碼模組。
  2. 提供接口和事件，能夠以其他方式與遊戲互動。有一些簡化的接口，可用於更改遊戲資源/數據，玩家配置，轉換，反映等。這些內容將在本指南的後面部分介紹。
  3. 在跨平台兼容時進行重構，這樣一來就不必擔心遊戲在 Linux/Mac/Windows 版本之間的差異。
  4. 重構模組以更新它。在常見情況下，SMAPI 會檢測並修復遊戲更新所破壞的模組代碼。
  5. 攔截錯誤。如果模組崩潰或發生錯誤，SMAPI 將攔截該錯誤，在控制台窗口中顯示錯誤詳細信息，並且在大多數情況下自動恢復遊戲。這意味着減少遊戲意外崩潰，並且可以更輕鬆地解決錯誤。
  6. 提供更新檢查。當有新版本可用時，SMAPI 會自動提醒玩家。
  7. 提供兼容性檢查。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＃ 編寫的，因此最好先熟悉它。無需記住所有內容，但是掌握基礎知識（例如字段、方法、變量和類）將使其他所有內容都變得更加容易。

一些有用的資源:

要求

在你開始之前:

  1. 熟悉 模組的使用，本指南的其餘部分假定你已經熟悉使用模組。
  2. 安裝遊戲
  3. 安裝 SMAPI
  4. 安裝開發環境

如果你不熟悉 Visual Studio (on Windows/Mac) 或者 MonoDevelop (on Linux), 模組:IDE 參考 解釋了如何完成本指南所需的重要工作。

創建一個基礎的模組

快速開始

如果你有足夠的經驗來跳過本教程，則此部分的簡要概述如下：

快速開始 
  1. 創建一個空的 C＃類庫 項目
  2. 目標框架選擇 .NET Framework 4.5 或者 4.5.1, 建議使用 4.5.2
  3. 參考 Pathoschild.Stardew.ModBuildConfig NuGet package 根據要在其上編譯模組的平台自動添加正確的引用。
  4. 創建一個 ModEntry 類，該類將 StardewModdingAPI.Mod 子類化
  5. 覆寫 Entry 方法，並使用 SMAPI events and APIs 編寫代碼
  6. 創建一個 manifest.json 文件 來描述了你的 SMAPI 模組
  7. 創建 一個包含模組文件的zip壓縮包 來發布

創建解決方案

一個 SMAPI 模組是具有 SMAPI 調用入口方法的動態鏈接庫（DLL），因此要對其進行設置

  1. 打開 Visual Studio 或者 MonoDevelop.
  2. 創建 類庫 項目，選擇 .NET Framework 框架 (參閱 如何創建一個項目)。確保你選擇的是 .NET Framework 而不是 .NET Core 或者 .NET Standard
  3. 選擇目標框架版本為 .NET Framework 4.5 或 4.5.1，使用 4.5.2 最佳 (參閱 如何改變目標框架)
  4. 添加 Pathoschild.Stardew.ModBuildConfig NuGet 包 (參閱 如何添加 NuGet 包).
  5. 安裝完包之後重新啟動 Visual Studio 或者 MonoDevelop

添加代碼

接下來讓我們添加一些將運行的 SMAPI 代碼

  1. 刪除 Class1.cs 或者 MyClass.cs 文件 (參閱 如何刪除文件).
  2. 在項目中添加一個 C# 類文件，取名為 ModEntry.cs (參閱 如何添加文件).
  3. 在此文件中輸入代碼 (把 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);
        }
    }
}

以下是該代碼的功能細分：

  1. using X; (參閱 using directive) 使該命名空間中的類在你的代碼中可用
  2. namespace YourProjectName (參閱 namespace keyword) 定義代碼的範圍，入門時不必擔心，因為在新建類文件時 Visual Studio 或 MonoDevelop 會自動添加它
  3. public class ModEntry : Mod (參閱 class keyword) 創建你的模組的主類文件，並繼承 SMAPI 的 Mod 類。SMAPI 將自動檢測你的 Mod 子類，而 Mod 使你可訪問 SMAPI 的接口
  4. public override void Entry(IModHelper helper) 是將模組加載到遊戲中時 SMAPI 將調用的方法。這裡的 helper 對象提供了對許多 SMAPI 接口的便捷訪問
  5. helper.Events.Input.ButtonPressed += this.OnButtonPressed; 添加了一個 '事件綁定' (i.e. a method to call) 到當按下按鈕的事件發生時. 換句話說，當一個按鈕被按下 (也就是 helper.Events.Input.ButtonPressed 事件觸發了), SMAPI 會調用你的 this.OnButtonPressed 方法。參閱 SMAPI 中的事件 獲取更多信息

添加你的清單

模組的清單為 SMAPI 提供模組的信息

  1. 向你的解決方案添加一個名為 manifest.json 的文本文件
  2. 將這些代碼複製到文件中：（注意要區分鍵值的大小寫，避免出現意外情況） 
    {
  "Name": "<模组的名字>",
  "Author": "<你的名字>",
  "Version": "1.0.0",
  "Description": "<一句话简单描述你的模组是干什么的>",
  "UniqueID": "<你的名字>.<模组的名字>",
  "EntryDll": "<你的解决方案的名字>.dll",
  "MinimumApiVersion": "3.0.0",
  "UpdateKeys": []
}
  3. 正確填寫其中的信息，不要留着空信息

當遊戲啟動時，它將在控制台中輸出。更多信息請參閱 清單文檔

構建你的模組

  1. 構建項目
    如果你不知道怎麼構建：在開發工具的菜單欄中選擇 項目，然後選擇 生成
    如果你已經做了 創建解決方案 這一步，在構建時你的模組會自動安裝到遊戲的 Mods 文件夾中
  2. 通過 SMAPI 啟動遊戲

到目前為止，每當按下遊戲中的一個鍵時，該模組會向控制台窗口發送一條消息

疑難解答

如果上述教程創建的模組不能正常運行：

  1. 重複查看以上步驟，以確保你沒有跳過任何內容
  2. 檢查是否有任何的錯誤消息，也許可以解釋為什麼它不起作用：
    • 在 Visual Studio 中嘗試重新構建解決方案，查看 輸出 面板 或者 錯誤列表
    • 在 MonoDevelop 中點擊 Build > Rebuild All 等待處理完畢。然後點擊 "Build: XX errors, XX warnings" 在頂部的條，點擊 XX Errors 和 Build Output 選項卡
  3. 參閱 疑難解答.
  4. 如果其他所有方法均失敗，請到 Stardew Valley Discord 尋求幫助 :)

常見問題

SMAPI 的文檔在哪裡？

這只是「入門」教程。更多信息請參閱 SMAPI reference 和 topics listed on the index page.

我如何使我的模組跨平台工作？

SMAPI 將自動調整模組使其可以在 Linux、MacOS 和 Windows 上運行。但是你也應該採取一些措施來避免出現問題：

  1. 使用 跨平台構建配置 包以自動設置您的項目引用，這使跨平台兼容性變得更容易，並使代碼可以在任何平台上進行編譯。（如果遵循上述指南，那麼就沒問題了)
  2. 使用 Path.Combine 構建文件路徑，請不要對路徑分隔符進行硬編碼，因為它們不能在所有平台上都可使用 
    // ✘ 不要这样做！这在 Linux 和 Mac 上不会起作用
string path = this.Helper.DirectoryPath + "\assets\image.png";

// ✓ 这样才是对的
string path = Path.Combine(this.Helper.DirectoryPath, "assets", "image.png");
  3. 使用 this.Helper.DirectoryPath，請勿嘗試自行確定模組路徑 
    // ✘ 不要这样做！如果 SMAPI 重写了程序集（例如对其进行了更新或跨平台），它将崩溃
string modFolder = Assembly .GetCallingAssembly().Location;

// ✓ 这样就没问题
string modFolder = this.Helper.DirectoryPath;

如何反編譯遊戲代碼？

觀察遊戲代碼的工作方式通常對開發很有用。遊戲的代碼都編譯在 StardewValley.exe 文件中，但是可以對其進行反編譯，以獲得原始代碼的近似可讀性。（由於反編譯器的限制，此功能可能無法完全發揮作用，但是能夠看到它在做什麼。）

要反編譯遊戲代碼...

在 Windows 上:
  1. 第一步:
    1. 安裝最新版本的 ILSpy
    2. 打開 ILSpy
    3. 點擊 視圖 > 選項滑動至底部的 "其他" 選項, 並啟用「始終限定成員引用」
  2. 在 ILSpy 打開 StardewValley.exe
  3. 右鍵 Stardew Valley 並選擇 保存代碼 創建反編譯的項目，可以在 Visual Studio 中打開
On Linux/MacOS:
  1. Install Visual Studio Code.
  2. Get the ILSpy .NET Decompiler plugin for VSCode.
  3. Open the Visual Studio Code Command Palette (Command+Shift+P), then type ilspy to show the two commands.
  4. Choose Decompile IL Assembly (pick file), then choose the StardewValley.exe in your game folder.
  5. 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 文件

取自「https://zh.stardewvalleywiki.com/mediawiki/index.php?title=模组:创建_SMAPI_模组&oldid=19818」