打开主菜单
首页
随机
登录
设置
关于Stardew Valley Wiki
免责声明
Stardew Valley Wiki
搜索
查看“模组:创建 SMAPI 模组”的源代码
←
模组:创建 SMAPI 模组
因为以下原因,您没有权限编辑本页:
您所请求的操作仅限于该用户组的用户使用:
用户
您可以查看和复制此页面的源代码。
{{模组:制作指南/header}} {{翻译}} 要为游戏创建 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|使用 Content Patcher]] 来编辑游戏的贴图并且不需要任何编程技术。本指南的其余部分是关于创建新的 SMAPI 模组的。有关内容包,请参阅 [[模组:Content Patcher]] (或模组的文档(如果为其他mod创建内容包)). ===我在哪里可以得到帮助?=== <span id="help"></span>星露谷模组社区欢迎你的到来. Feel free to ask for help in [[Modding:Community#Discord|#making-mods on the Stardew Valley Discord]]. ==开始== ===学习 C#=== 由于模组是用 C# 编写的,因此最好先熟悉它。无需记住所有内容,但是掌握基础知识(例如字段、方法、变量和类)将使其他所有内容都变得更加容易。 一些有用的资源: * [https://docs.microsoft.com/en-us/dotnet/csharp/quick-starts/ ''C# 快速学习''] 通过交互式示例讲解C#的基础知识。 * [https://mva.microsoft.com/en-us/training-courses/c-fundamentals-for-absolute-beginners-16169 ''C# 绝对初学者的基础知识''] 视频指南将引导您完成 C# 从基本概念到事件驱动的编程(这是 SMAPI 模组经常使用的内容)。 ===要求=== 在你开始之前: # 熟悉 [[模组:玩家指南|玩家指南]],本指南的其余部分假定你已经熟悉使用模组。 # 安装游戏 # 安装 [[模组:玩家指南#安装 SMAPI|SMAPI]] # 安装开发环境 #* 在 Linux 上:安装 [http://www.monodevelop.com/ MonoDevelop] #* 在 Mac 上:安装 [https://visualstudio.microsoft.com/vs/mac/ Visual Studio for Mac]. (This is a rebranded MonoDevelop.) #* 在 Windows 上:安装 [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community]. 在安装程序中的工作负载中选择 .NET 桌面开发 如果你不熟悉 Visual Studio (on Windows/Mac) 或者 MonoDevelop (on Linux), [[模组:IDE 参考]] 解释了如何完成本指南所需的重要工作。 ==创建一个基础的模组== ===快速开始=== 如果你有足够的经验来跳过本教程,则此部分的简要概述如下: {{collapse|快速开始|content=  # 创建一个空的 C#类库 项目 # 目标框架选择 .NET Framework 4.5 或者 4.5.1, 建议使用 4.5.2 # 参考 [https://smapi.io/package/readme <tt>Pathoschild.Stardew.ModBuildConfig</tt> NuGet package] 根据要在其上编译模组的平台自动添加正确的引用。 # 创建一个 <tt>ModEntry</tt> 类,该类将 <tt>StardewModdingAPI.Mod</tt> 子类化 # 覆写 <tt>Entry</tt> 方法,并使用 [[#Mod APIs|SMAPI events and APIs]] 编写代码 # 创建一个 [[#添加你的清单|<tt>manifest.json</tt> 文件]] 来描述了你的 SMAPI 模组 # 创建 [[#发布你的模组|一个包含模组文件的zip压缩包]] 来发布 }} ===创建解决方案=== 一个 SMAPI 模组是具有 SMAPI 调用入口方法的动态链接库(DLL),因此要对其进行设置 # 打开 Visual Studio 或者 MonoDevelop. # 创建 类库 项目,选择 .NET Framework 框架 (参阅 [[模组:IDE 参考#创建项目|如何创建一个项目]])。确保你选择的是 .NET Framework 而不是 .NET Core 或者 .NET Standard # 选择目标框架版本为 .NET Framework 4.5 或 4.5.1,使用 4.5.2 最佳 (参阅 [[模组:IDE 参考#选择目标框架|如何改变目标框架]]) # 参考 [https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig <tt>Pathoschild.Stardew.ModBuildConfig</tt> NuGet 包] (参阅 [[模组:IDE 参考#添加 NuGet 包|如何添加 NuGet 包]]). # 安装完包之后重新启动 Visual Studio 或者 MonoDevelop ===Add the code=== Next let's add some code SMAPI will run. <ol> <li>Delete the <tt>Class1.cs</tt> or <tt>MyClass.cs</tt> file (see [[Modding:IDE reference#delete-file|how to delete a file]]).</li> <li>Add a C# class file called <tt>ModEntry.cs</tt> to your project (see [[Modding:IDE reference#Add a file|how to add a file]]).</li> <li>Put this code in the file (replace <tt>YourProjectName</tt> with the name of your project): <syntaxhighlight lang="c#"> using System; using Microsoft.Xna.Framework; using StardewModdingAPI; using StardewModdingAPI.Events; using StardewModdingAPI.Utilities; using StardewValley; namespace YourProjectName { /// <summary>The mod entry point.</summary> public class ModEntry : Mod { /********* ** Public methods *********/ /// <summary>The mod entry point, called after the mod is first loaded.</summary> /// <param name="helper">Provides simplified APIs for writing mods.</param> public override void Entry(IModHelper helper) { helper.Events.Input.ButtonPressed += this.OnButtonPressed; } /********* ** Private methods *********/ /// <summary>Raised after the player presses a button on the keyboard, controller, or mouse.</summary> /// <param name="sender">The event sender.</param> /// <param name="e">The event data.</param> private void OnButtonPressed(object sender, ButtonPressedEventArgs e) { // ignore if player hasn't loaded a save yet if (!Context.IsWorldReady) return; // print button presses to the console window this.Monitor.Log($"{Game1.player.Name} pressed {e.Button}.", LogLevel.Debug); } } } </syntaxhighlight></li> </ol> Here's a breakdown of what that code is doing: # <code>using X;</code> (see [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/using-directive using directive]) makes classes in that namespace available in your code. # <code>namespace YourProjectName</code> (see [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/namespace namespace keyword]) defines the scope for your mod code. Don't worry about this when you're starting out, Visual Studio or MonoDevelop will add it automatically when you add a file. # <code>public class ModEntry : Mod</code> (see [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/class class keyword]) creates your mod's main class, and subclasses SMAPI's <tt>Mod</tt> class. SMAPI will detect your <tt>Mod</tt> subclass automatically, and <tt>Mod</tt> gives you access to SMAPI's APIs. # <code>public override void Entry(IModHelper helper)</code> is the method SMAPI will call when your mod is loaded into the game. The <code>helper</code> provides convenient access to many of SMAPI's APIs. # <code>helper.Events.Input.ButtonPressed += this.OnButtonPressed;</code> adds an 'event handler' (i.e. a method to call) when the button-pressed event happens. In other words, when a button is pressed (the <tt>helper.Events.Input.ButtonPressed</tt> event), SMAPI will call your <tt>this.OnButtonPressed</tt> method. See [[Modding:Modder Guide/APIs/Events|events in the SMAPI reference]] for more info. ===Add your manifest=== The mod manifest tells SMAPI about your mod. <ol> <li>Add a file named <tt>manifest.json</tt> to your project.</li> <li>Paste this code into the file: <syntaxhighlight lang="json"> { "Name": "<your project name>", "Author": "<your name>", "Version": "1.0.0", "Description": "<One or two sentences about the mod>", "UniqueID": "<your name>.<your project name>", "EntryDll": "<your project name>.dll", "MinimumApiVersion": "3.0.0", "UpdateKeys": [] } </syntaxhighlight></li> <li>Replace the <tt><...></tt> placeholders with the correct info. Don't leave any <tt><></tt> symbols!</li> </ol> This will be listed in the console output when the game is launching. For more info, see the [[Modding:Modder Guide/APIs/Manifest|manifest docs]]. ===Try your mod=== # Build the project.<br /><small>If you did the ''[[#Create the project|create the project]]'' steps correctly, this will automatically add your mod to the game's <tt>Mods</tt> folder.</small> # Run the game through SMAPI. The mod so far will just send a message to the console window whenever you press a key in the game. ===Troubleshoot=== If the tutorial mod doesn't work... # Review the above steps to make sure you didn't skip something. # Check for error messages which may explain why it's not working: #* In Visual Studio, click ''Build > Rebuild Solution'' and check the ''Output'' pane or ''Error'' list. #* In MonoDevelop, click ''Build > Rebuild All'' and wait until it's done. Then click the "Build: XX errors, XX warnings" bar at the top, and check the ''XX Errors'' and ''Build Output'' tabs. # See the [[Modding:Modder Guide/Test and Troubleshoot|troubleshooting guide]]. # If all else fails, come ask for help in the [[Modding:Community#Discord|#modding in the Stardew Valley Discord]]. :) ==FAQs== ===Where's the SMAPI documentation?=== This is just the 'getting started' tutorial. For more documentation, see the [[Modding:Modder Guide/APIs|SMAPI reference]] and the [[Modding:Index|topics listed on the index page]]. ===How do I make my mod work crossplatform?=== SMAPI will automatically adjust your mod so it works on Linux, MacOS, and Windows. However, there are a few things you should do to avoid problems: <ol> <li>Use the [https://smapi.io/package/readme crossplatform build config] package to automatically set up your project references. This makes crossplatform compatibility easier and lets your code compile on any platform. (If you followed the above guide, you already have this.)</li> <li>Use <tt>Path.Combine</tt> to build file paths, don't hardcode path separators since they won't work on all platforms. <syntaxhighlight lang="c#"> // ✘ Don't do this! It won't work on Linux/Mac. string path = this.Helper.DirectoryPath + "\assets\image.png"; // ✓ This is OK string path = Path.Combine(this.Helper.DirectoryPath, "assets", "image.png"); </syntaxhighlight></li> <li>Use <tt>this.Helper.DirectoryPath</tt>, don't try to determine the mod path yourself. <syntaxhighlight lang="c#"> // ✘ Don't do this! It will crash if SMAPI rewrites the assembly (e.g. to update or crossplatform it). string modFolder = Assembly.GetCallingAssembly().Location; // ✓ This is OK string modFolder = this.Helper.DirectoryPath; </syntaxhighlight></li> </ol> ===How do I decompile the game code?=== It's often useful to see how the game code works. The game code is compiled into <tt>StardewValley.exe</tt> (i.e. converted to a machine-readable format), but you can decompile it get a mostly-readable approximation of the original code. (This might not be fully functional due to decompiler limitations, but you'll be able to see what it's doing.) To decompile the game code... ; On Windows: :# First-time setup: :## Install the latest {{github|icsharpcode/ILSpy/releases|ILSpy}} release (get the "ILSpy_binaries" file under assets). :## Open ILSpy. :## Click ''View > Options'', scroll to the "Other" section at the bottom, and enable "Always qualify member references". :# Open <tt>StardewValley.exe</tt> in ILSpy. :# Right-click on ''Stardew Valley'' and choose ''Save Code'' to create a decompiled project you can open in Visual Studio. ; On Linux/MacOS: :# Install [https://code.visualstudio.com/download Visual Studio Code]. :# Get the [https://marketplace.visualstudio.com/items?itemName=icsharpcode.ilspy-vscode ILSpy .NET Decompiler] plugin for VSCode. :# Open the Visual Studio Code Command Palette (<code>Command+Shift+P</code>), then type <code>ilspy</code> to show the two commands. :# Choose ''Decompile IL Assembly (pick file)'', then choose the <tt>StardewValley.exe</tt> in your [[Modding:Player Guide/Getting Started#Find your game folder|game folder]]. :# A tree view named <tt>ILSPY DECOMPILED MEMBERS</tt> should appear in the Explorer view. This lets you expand and select various nodes to see the decompiled C# code in the editor. To unpack the XNB data/image files, see [[Modding:Editing XNB files]]. [[Category:模组]] [[en:Modding:Modder_Guide/Get_Started]] [[es:Modding:Guía del Modder/Introducción]] [[fr:Modding:Guide du Moddeur/Commencer]] [[pt:Modificações:Guia do Modder/Começando]]
该页面使用的模板:
Template:Collapse
(
查看源代码
)
Template:Github
(
查看源代码
)
模组:制作指南/header
(
查看源代码
)
返回至
模组:创建 SMAPI 模组
。