Protected, translators
5,421
edits
This wiki is a read-only version of the Stardew Valley Wiki. The official editable wiki maintained by ConcernedApe can be found at stardewvalleywiki.com
Changes
merge content from Modding:Modder Guide/Tutorial Mod (main author is Pathoschild, with contributions from Cheesysteak, Hawkfalcon, and Nobbele)
If you're not familiar with Visual Studio 2017 (on Windows/Mac) or MonoDevelop (on Linux), [[Modding:IDE reference]] explains how to do the important stuff you need for this guide.
==Quick start==
The rest of this page will help you create a mod. If you're experienced enough to skip the tutorial, here's a quick summary of what this page will walk you through:
# Create an empty C# class library project.
# Target .NET Framework 4.5, 4.5.1, or 4.5.2 for best compatibility.
# Reference the [https://github.com/Pathoschild/Stardew.ModBuildConfig <tt>Pathoschild.Stardew.ModBuildConfig</tt> NuGet package] to automatically add the right references depending on the platform the mod is being compiled on.
# Create a <tt>ModEntry</tt> class which subclasses <tt>StardewModdingAPI.Mod</tt>.
# Override the <tt>Entry</tt> method, and write your code using the [[#Mod APIs|SMAPI events and APIs]].
# Create a [[#Add your manifest|<tt>manifest.json</tt> file]] which describes your mod for SMAPI.
# Create [[#Release your mod|a zip file containing the mod files]] for release.
==Create a basic mod==
===Create the project===
A SMAPI mod is a compiled library (DLL) with an entry method that gets called by SMAPI, so let's set that up.
# Open Visual Studio 2017 or MonoDevelop.
# Create a solution with a .NET Framework class library project (see [[Modding:IDE reference#create-project|how to create a project]]). '''Make sure you choose .NET Framework, not .NET Core or .NET Standard.'''
# Change the target framework to .NET Framework 4.5, 4.5.1, or 4.5.2 for best compatibility (see [[Modding:IDE reference#set-target-framework|how to change target framework]]).
# Reference the [https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig <tt>Pathoschild.Stardew.ModBuildConfig</tt> NuGet package] (see [[Modding:IDE reference#add-nuget|how to add the package]]).
# Restart Visual Studio/MonoDevelop after installing the package.
===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):
<source 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)
{
InputEvents.ButtonPressed += this.InputEvents_ButtonPressed;
}
/*********
** Private methods
*********/
/// <summary>The method invoked when the player presses a controller, keyboard, or mouse button.</summary>
/// <param name="sender">The event sender.</param>
/// <param name="e">The event data.</param>
private void InputEvents_ButtonPressed(object sender, EventArgsInput 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}.");
}
}
}
</source></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>InputEvents.ButtonPressed += this.InputEvents_ButtonPressed;</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>InputEvents.ButtonPressed</tt> event), SMAPI will call your <tt>this.InputEvents_ButtonPressed</tt> method. See [[Modding:SMAPI APIs#Events]] 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 (replacing the <tt><...></tt> placeholders):
<source 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": "2.0",
"UpdateKeys": []
}
</source></li>
</ol>
This will be listed in the console output when the game is launching. For more info, see the [[Modding:SMAPI 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.
===Troubleshooting===
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.
# If all else fails, come ask for help in the [[Modding:Community#Discord|#modding in the Stardew Valley Discord]]. :)
==Going further==
===SMAPI APIs===
SMAPI provides a set of APIs you can use to do more. See [[Modding:SMAPI APIs]] for more info.
===Crossplatform support===
SMAPI will automatically adjust your mod so it works on Linux, Mac, and Windows. However, there are a few things you should do to avoid problems:
<ol>
<li>Use the [https://github.com/Pathoschild/Stardew.ModBuildConfig#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.
<source lang="c#">
// ✘ Don't do this! It will crash on Linux/Mac.
string path = Helper.DirectoryPath + "\assets\asset.xnb";
// ✓ This is OK
string path = Path.Combine(Helper.DirectoryPath, "assets", "asset.xnb");
</source></li>
<li>Use <tt>Helper.DirectoryPath</tt>, don't try to determine the mod path yourself.
<source 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 = Helper.DirectoryPath;
</source></li>
</ol>
===Decompile the game code===
When you start working on more complex mods, you may need to look at how the game code works.
To decompile the game code so you can read it (though it won't be fully functional due to decompiler limitations):
* On Windows:
*# Open <tt>StardewValley.exe</tt> in [https://www.jetbrains.com/decompiler/ dotPeek].
*# Right-click on ''Stardew Valley'' and choose ''Export to Project''. Accept the default options to create a decompiled project you can open in Visual Studio.
* On Linux/Mac:
*# Open <tt>StardewValley.exe</tt> in MonoDevelop through ''File > Open''.
*# Change ''Language'' from ''Summary'' to ''C#''.
To unpack the XNB data/image files, see [[Modding:Editing XNB files]].
{{modding guide footer
|prev =
|next = [[Modding:Modder Guide/Tutorial ModTesting and Releasing|Creating a Basic ModTesting and Releasing]]
}}
