Difference between revisions of "Modding:Modder Guide/Tutorial Mod"

From Stardew Valley Wiki
Jump to navigation Jump to search
(→‎Add your manifest: add update keys)
(update redirect)
 
(24 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
←[[Modding:Index|Index]]
+
#REDIRECT [[Modding:Modder Guide/Get Started]]
−
 
 
−
Ready to make your own mod? This page will help you create your first SMAPI mod and use the available APIs and events.
 
−
 
 
−
==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 (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.
 
−
# Create an entry 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.
 
−
 
 
−
==Intro==
 
−
* '''What is SMAPI?'''
 
−
*: A SMAPI mod uses the [https://github.com/Pathoschild/SMAPI 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. [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://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 [https://discord.gg/kH55QXP come chat on Discord] or [http://community.playstarbound.com/forums/mods.215/ post in the forums].
 
−
 
 
−
==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]
 
−
|
 
−
|-
 
−
| 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.
 
−
 
 
−
===Create the project===
 
−
# Open Visual Studio 2017 or MonoDevelop.
 
−
# Create a solution with a C# class library project (see [[Modding:IDE reference#create-project|how to]]).
 
−
# Change the target framework to .NET Framework 4.5 for compatibility with Linux (see [[Modding:IDE reference#set-target-framework|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]]). If you use Visual Studio 2017, you might need to close & reopen it before it handles the package correctly.<br /><small>''This will automatically reference the right dependencies for SMAPI modding, add support for debugging the mod, and copy the mod into your game's <tt>Mods</tt> folder when you build.''</small>
 
−
 
 
−
===Write the code===
 
−
Now for the 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]]).</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>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)
 
−
        {
 
−
            ControlEvents.KeyPressed += this.ControlEvents_KeyPress;
 
−
        }
 
−
 
 
−
        /*********
 
−
        ** Private methods
 
−
        *********/
 
−
        /// <summary>The method invoked when the player presses a keyboard button.</summary>
 
−
        /// <param name="sender">The event sender.</param>
 
−
        /// <param name="e">The event data.</param>
 
−
        private void ControlEvents_KeyPress(object sender, EventArgsKeyPressed e)
 
−
        {
 
−
            if (Context.IsWorldReady) // save is loaded
 
−
            {
 
−
                this.Monitor.Log($"{Game1.player.name} pressed {e.KeyPressed}.");
 
−
            }
 
−
        }
 
−
    }
 
−
}
 
−
</source></li>
 
−
</ol>
 
−
 
 
−
===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>&lt;...&gt;</tt> placeholders):
 
−
<source lang="json">
 
−
{
 
−
  "Name": "<your project name>",
 
−
  "Author": "<your name>",
 
−
  "Version": "1.0",
 
−
  "Description": "<One or two sentences about the mod>",
 
−
  "UniqueID": "<your name>.<your project name>",
 
−
  "EntryDll": "<your project name>.dll",
 
−
  "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 building the 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==
 
−
Now that you have a basic mod, see [[Modding:SMAPI APIs]] for the SMAPI features you can use to do more.
 
−
 
 
−
==Final considerations==
 
−
===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>
 
−
 
 
−
===Test on all platforms===
 
−
If you want to test your mod on all platforms, there's some first-time setup you need to get out of the way. Essentially you need to test your mod twice: once on Windows, and again on Linux or Mac. You can do that by testing one version on your computer, and the other in a virtual machine.
 
−
 
 
−
* '''If your main computer is Windows:'''
 
−
*# Install [https://www.virtualbox.org/ VirtualBox].
 
−
*# Add [https://www.dropbox.com/s/nrq9xsde2afp4ey/StardewValleyLinuxModding.7z this premade Linux virtual machine] (requires a 64-bit computer).<br /><small>''In VirtualBox, click Machine » Add and choose the downloaded <tt>.vbox</tt> file. This is a [https://manjaro.org/ Manjaro] virtual machine with Chromium (web browser), Steam, and [http://www.monodevelop.com/ MonoDevelop] preinstalled.''</small>
 
−
*# Launch the virtual machine, and install Stardew Valley from the Steam client (preinstalled) or GOG website.<br /><small>''Tip: don't change the default install path, or you'll need to customise the mod's build configuration.''</small>
 
−
 
 
−
* '''If your main computer is Linux or Mac:'''
 
−
*# Install [https://www.virtualbox.org/ VirtualBox].
 
−
*# [http://www.macworld.co.uk/how-to/mac-software/run-windows-10-on-your-mac-using-virtualbox-3621650/ Create a VM with Windows].
 
−
*# Install [https://www.visualstudio.com/vs/community/ Visual Studio Community] in your VM.
 
−
*# Install Stardew Valley in your VM.
 
−
 
 
−
===Release your mod===
 
−
Ready to share your mod with the world? If you [[#Create the project|installed the mod build package]], building the project automatically adds a <tt>.zip</tt> file to your project's <tt>bin/Debug</tt> or <tt>bin/Release</tt> folder (depending how you built the project). Just upload that file to [http://www.nexusmods.com/stardewvalley Nexus Mods], the [http://community.playstarbound.com/forums/mods.215/ official modding forums], or both.
 
−
 
 
−
{{collapse|see manual instructions|content=
 
−
Let's say you created a mod named ''Pineapples Everywhere'' which turns all NPCs into pineapples; here's how you would release it for others to use.
 
−
 
 
−
<ol>
 
−
<li>Copy your compiled mod and <tt>manifest.json</tt> into a folder matching your mod's name.</li>
 
−
<li>Delete the <tt>config.json</tt> if any (so it doesn't replace the player's current settings when they update).</li>
 
−
<li>Create a zip archive with your mod's name and version.
 
−
 
 
−
Your mod structure should look something like this:
 
−
 
 
−
<pre>
 
−
PineapplesEverywhere-1.0.zip
 
−
  PineapplesEverywhere/
 
−
      PineapplesEverywhere.dll
 
−
      PineapplesEverywhere.pdb
 
−
      manifest.json
 
−
</pre></li>
 
−
 
 
−
<li>Upload your mod to [http://www.nexusmods.com/stardewvalley Nexus Mods], the [http://community.playstarbound.com/forums/mods.215/ official modding forums], or both.</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.
 
−
 
 
−
Here's how to decompile the game code so you can look at it:
 
−
 
 
−
# 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. (Note that the decompiled code will not be functional due to limitations of the decompiler, but you'll be able to read the game code.)
 
−
 
 
−
Here's how to unpack the XNB data files:
 
−
 
 
−
# Download the [http://community.playstarbound.com/threads/modding-guides-and-general-modding-discussion-redux.109131/page-6#post-2837587 Easy XNB Pack/UnPack Toolkit].
 
−
# Copy the entire <tt>Stardew Valley\Content</tt> game folder into <tt>XNB-Mod-Toolkit\Packed</tt>.
 
−
# Run <tt>XNB-Mod-Toolkit\UNPACK FILES.bat</tt> to unpack the files into <tt>XNB-Mod-Toolkit\Unpacked</tt>.
 
−
 
 
−
[[Category:Modding]]
 

Latest revision as of 15:34, 3 September 2018

Redirect to:

Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Modder_Guide/Tutorial_Mod&oldid=74551"