模组:创建 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.exe
- 右键 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 文件