Stardew Valley Wiki

Changes

Modding:Modder Guide/Tutorial Mod (view source)

Revision as of 17:46, 27 May 2018

1,965 bytes removed ,  17:46, 27 May 2018
integrate into modder's guide, move some content to intro page, rewrite and expand a bit
Line 1: Line 1: −
←[[Modding:Index|Index]]
+
{{../header}}
   −
Ready to make your own mod? This page will help you create your first SMAPI mod and use the available APIs and events.
+
'''See [[Modding:Modder Guide]] for an intro before reading this page. This page assumes you've already installed the software mentioned on that page.'''
 +
 
 +
This page will help you create your first SMAPI mod. The mod won't do much on its own (just detect user input and print a message to the console), but it'll be fully functional and provide a base you can expand from.
    
==Quick start==
 
==Quick start==
Line 9: Line 11:  
# Target .NET Framework 4.5 (for Linux compatibility).
 
# Target .NET Framework 4.5 (for Linux 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.
 
# 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 an entry class which subclasses <tt>StardewModdingAPI.Mod</tt>.
+
# 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]].
 
# 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 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 [[#Release your mod|a zip file containing the mod files]] for release.
   −
==Intro==
+
==Create a basic mod==
−
* '''What is SMAPI?'''
+
===Create the project===
−
*: A SMAPI mod uses the [https://smapi.io/ SMAPI] modding API to extend the game logic. You can run code when something happens (e.g. mouse clicked or menu opened), or periodically (e.g. once per game tick). SMAPI mods are written in C# using the .NET Framework. Stardew Valley also uses XNA (on Windows) or MonoGame (on Linux and Mac) for the fundamental game logic (drawing to the screen, user input, etc).
  −
 
  −
* '''Can I make a mod?'''
  −
*: The next few sections will walk you through creating a very simple mod. If you follow along, you'll have created a mod! All that will be left is making it do what you want.
  −
*:* <p>'''Scenario A: you're new to programming.'''<br />Many mod developers start with little or no programming experience. You can certainly learn along the way if you're determined, but you should be prepared for a steep learning curve. Don't be too ambitious at first; it's better to start with a small mod when you're figuring it out. It's easy to become overwhelmed at first and give up. The modding community is very welcoming, so don't be afraid to ask questions!</p><p>Since mods are written in C#, it's a good idea to get acquainted with it first. Some good resources are [https://docs.microsoft.com/en-us/dotnet/csharp/quick-starts/ ''C# Quickstarts''] and [https://mva.microsoft.com/en-us/training-courses/c-fundamentals-for-absolute-beginners-16169 ''C# Fundamentals for Absolute Beginners''], will walk you through the basics of C# needed to write SMAPI mods, from the basic concepts to event-driven programming (which is what SMAPI mods use).</p>
  −
*:* '''Scenario B: you already have programming experience.'''<br />You should be fine. Programming experience in C# or Java will make things easier, but it isn't critical. If you're unfamiliar with C#, you can skim through [https://docs.microsoft.com/en-us/dotnet/csharp/quick-starts/ C# Quickstarts] and [https://mva.microsoft.com/en-us/training-courses/c-fundamentals-for-absolute-beginners-16169 ''C# Fundamentals for Absolute Beginners''] to fill in any gaps.
  −
 
  −
* '''<span id="help">Where can I get help?</span>'''
  −
*: The Stardew Valley modding community is very welcoming; feel free to [[Modding:Community|ask the community]] for help.
  −
 
  −
==Requirements==
  −
Before you start:
  −
<ol>
  −
<li>Read the [[Modding:Player FAQs|player FAQs]] which answer common questions about Stardew Valley mods and troubleshooting.</li>
  −
<li>Install Stardew Valley.</li>
  −
<li>Install [[Modding:Installing SMAPI|SMAPI]].</li>
  −
<li>Install the IDE (''integrated development environment''):
  −
{| class="wikitable"
  −
|-
  −
! OS
  −
! what to install
  −
! notes
  −
|-
  −
| Linux
  −
| [http://www.monodevelop.com/ MonoDevelop]
  −
|
  −
|-
  −
| Mac
  −
| [https://www.visualstudio.com/vs/visual-studio-mac/ Visual Studio 2017 for Mac]
  −
| This is essentially MonoDevelop, don't be confused by the labeling.
  −
|-
  −
| Windows
  −
| [https://www.visualstudio.com/vs/community/ Visual Studio 2017 Community]
  −
| When the installer asks about workloads, enable ''.NET Desktop Development''.
  −
|}
  −
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.</li>
  −
</ol>
  −
 
  −
==Create a mod==
   
A SMAPI mod is a compiled library (DLL) with an entry method that gets called by SMAPI, so let's set that up.
 
A SMAPI mod is a compiled library (DLL) with an entry method that gets called by SMAPI, so let's set that up.
   −
===Create the project===
   
# Open Visual Studio 2017 or MonoDevelop.
 
# 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 solution with a .NET Framework class library project (see [[Modding:IDE reference#create-project|how to create a project]]).
−
# Change the target framework to .NET Framework 4.5 for compatibility with Linux (see [[Modding:IDE reference#set-target-framework|how to]]).
+
# Change the target framework to .NET Framework 4.5 for compatibility with Linux (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]]).
+
# 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]]).
 
#* '''Stardew Valley 1.3 only:''' make sure you install the latest 2.1-beta version of the package. (You may need to enable the 'include prerelease' checkbox above the search results to see it.)
 
#* '''Stardew Valley 1.3 only:''' make sure you install the latest 2.1-beta version of the package. (You may need to enable the 'include prerelease' checkbox above the search results to see it.)
 
# Restart Visual Studio/MonoDevelop after installing the package.
 
# Restart Visual Studio/MonoDevelop after installing the package.
   −
===Write the code===
+
===Add the code===
−
Now for the code SMAPI will run.
+
Next let's add some code SMAPI will run.
    
<ol>
 
<ol>
−
<li>Delete the <tt>Class1.cs</tt> or <tt>MyClass.cs</tt> file (see [[Modding:IDE reference#delete-file|how to]]).</li>
+
<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]]).</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):
 
<li>Put this code in the file (replace <tt>YourProjectName</tt> with the name of your project):
 
<source lang="c#">
 
<source lang="c#">
Line 94: Line 56:  
             InputEvents.ButtonPressed += this.InputEvents_ButtonPressed;
 
             InputEvents.ButtonPressed += this.InputEvents_ButtonPressed;
 
         }
 
         }
 +
    
         /*********
 
         /*********
Line 103: Line 66:  
         private void InputEvents_ButtonPressed(object sender, EventArgsInput e)
 
         private void InputEvents_ButtonPressed(object sender, EventArgsInput e)
 
         {
 
         {
−
             if (Context.IsWorldReady) // save is loaded
+
            // ignore if player hasn't loaded a save yet
−
             {
+
             if (!Context.IsWorldReady)
−
                this.Monitor.Log($"{Game1.player.Name} pressed {e.Button}.");
+
                return;
−
            }
+
 
 +
            // print button presses to the console window
 +
             this.Monitor.Log($"{Game1.player.Name} pressed {e.Button}.");
 
         }
 
         }
 
     }
 
     }
Line 113: Line 78:  
</ol>
 
</ol>
   −
For those who are curious, here's a breakdown of what this is doing:
+
Here's a breakdown of what that code is doing:
−
 
  −
<ol>
  −
<li>
  −
    <code>Mod</code> is how SMAPI determines that this is the file it should initialize the mod with.
  −
</li>
  −
<li>
  −
    <code>public override void Entry(IModHelper helper)</code> is overriding the <code>Mod.Entry</code> method. This is what SMAPI will execute one time once the Mod is initialized.
  −
</li>
  −
<li>
  −
    <code>InputEvents.ButtonPressed += this.InputEvents_ButtonPressed;</code> is adding <code>this.InputEvents_ButtonPressed</code> as an Event Handler to the SMAPI event "<code>InputEvents.ButtonPressed</code>". You can see more bindable Events on the [[Modding:SMAPI APIs#Events]] page, but this essentially means that anytime the ButtonPressed event fires, <code>this.InputEvents_ButtonPressed</code> will be executed as well.
  −
</li>
  −
</ol>
      +
# <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===
 
===Add your manifest===
Line 157: Line 115:     
===Troubleshooting===
 
===Troubleshooting===
−
If building the mod doesn't work:
+
If the tutorial mod doesn't work...
−
* If you see an error starting with "''The mod build package''", try following the instructions in the error message.
  −
* Try reviewing the above steps to make sure you didn't skip something.
  −
* If all else fails, [[#help|ask for help]]. :)
     −
==Mod APIs==
+
# Review the above steps to make sure you didn't skip something.
−
Now that you have a basic mod, see [[Modding:SMAPI APIs]] for the SMAPI features you can use to do more.
+
# 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]]. :)
   −
==Final considerations==
+
==Things to consider==
 
===Crossplatform support===
 
===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:
 
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:
Line 236: Line 194:     
To unpack the XNB data/image files, see [[Modding:Editing XNB files]].
 
To unpack the XNB data/image files, see [[Modding:Editing XNB files]].
−
  −
[[Category:Modding]]
 
Pathoschild
translators
8,403

edits

Retrieved from "https://stardewvalleywiki.com/Special:MobileDiff/70740"