Line 7: |
Line 7: |
| Testing is pretty straightforward for most mods: | | Testing is pretty straightforward for most mods: |
| # Click ''Build > Rebuild Solution'' (Visual Studio) or ''Build > Rebuild All'' (MonoDevelop). | | # Click ''Build > Rebuild Solution'' (Visual Studio) or ''Build > Rebuild All'' (MonoDevelop). |
− | # Make sure there are no build errors and the mod gets copied to your <tt>Mods</tt> folder. | + | # Make sure there are no build errors and the mod gets copied to your <samp>Mods</samp> folder. |
| # Try the mod in-game. | | # Try the mod in-game. |
| # Make sure there are no errors or warnings for your mod in the SMAPI console. | | # Make sure there are no errors or warnings for your mod in the SMAPI console. |
Line 28: |
Line 28: |
| For complex mods, you may need to test your mod on all platforms. The game is mostly the same on Linux/Mac, so you only 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. | | For complex mods, you may need to test your mod on all platforms. The game is mostly the same on Linux/Mac, so you only 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:'''
| + | <dl> |
− | *# Install [https://www.virtualbox.org/ VirtualBox].
| + | <dt>If your main computer is Windows 10 or 11:</dt> |
− | *# Create a [https://zorinos.com/ ZorinOS Core] VM in VirtualBox.
| + | <dd> |
− | *#* ''See [https://extr3metech.wordpress.com/2013/09/05/installing-zorin-os-7-in-virtual-box-screenshots this setup guide] for more details. The ZorinOS installer might be a bit different than shown, but should be pretty intuitive.''
| + | <ol> |
− | *#* ''If you don't see any options for 64-bit OSes in VirtualBox, see [https://superuser.com/a/866963 how to enable them].''
| + | <li>[https://docs.microsoft.com/en-us/windows/wsl/install Install Windows Subsystem for Linux (WSL)].</li> |
− | *#* ''When creating the virtual disk, at least 20GB is recommended.''
| + | <li>Install the required software in WSL:</li> |
− | *# [https://store.steampowered.com/about Download the Steam installer] in the VM and run it.
| + | <ol> |
− | *# Launch Steam to finish installation. If nothing happens, see [https://askubuntu.com/questions/771032/steam-not-opening-in-ubuntu-16-04-lts these extra steps] to fix it.
| + | <li>[https://linuxconfig.org/how-to-install-steam-on-ubuntu-20-04-focal-fossa-linux Install Steam].</li> |
− | *# Install Stardew Valley through Steam.
| + | <li>Launch <code>export TERM=xterm && steam</code>, then install & launch Stardew Valley through its UI. This will also install its dependencies.</li> |
− | *# [[Modding:Player Guide/Getting Started#Install SMAPI|Install SMAPI]].
| + | <li>''(optional)'' Download and install your preferred IDE, if you plan to compile the code on Linux. For the [https://www.jetbrains.com/help/rider/Installation_guide.html#prerequisites latest standalone Rider version] (not free): |
− | *# ''(optional)'' Install [https://www.mono-project.com/ <tt>mono-complete</tt>] and [http://www.monodevelop.com/download/ MonoDevelop] in your VM. This is only needed if you want to compile separately for Linux/Mac. When installing <tt>.deb</tt> files, use the instructions for [https://zorinos.com/help/install-apps/#deb-files the Ubuntu version shown here]. If you run into errors, may Linux have mercy on your soul.
| + | <syntaxhighlight lang="sh"> |
− | *# ''(optional)'' For unlocking Mac OS only: [https://www.insanelymac.com/forum/files/file/838-unlocker/ Virtual Machine Unlocker 2.1.1] for VmWare Workstation 11/12/14, VmWare Player 7/12/14, or Fusion 7/8/10. '''This is needed to boot Mac OS on a virtual Machine'''
| + | wget "<download url here>" -O rider-install.tar.gz |
| + | sudo tar -xzvf rider-install.tar.gz -C /opt |
| + | ln -s "/opt/JetBrains Rider-<version>/bin/rider.sh" |
| + | ./rider.sh |
| + | </syntaxhighlight></li> |
| + | <li>[[Modding:Installing SMAPI on Linux|Install SMAPI]].</li> |
| + | </ol></li> |
| + | <li>To launch the game, launch <code>steam</code> and run the game through its UI.</li> |
| + | </ol></li> |
| + | </ul> |
| + | </dd> |
| + | </dl> |
| | | |
| + | ; If your main computer is Windows 8 or earlier: |
| + | :# Install [https://www.virtualbox.org/ VirtualBox]. |
| + | :# Create a [https://zorinos.com/ ZorinOS Core] VM in VirtualBox. |
| + | :#* ''See [https://extr3metech.wordpress.com/2013/09/05/installing-zorin-os-7-in-virtual-box-screenshots this setup guide] for more details. The ZorinOS installer might be a bit different than shown, but should be pretty intuitive.'' |
| + | :#* ''If you don't see any options for 64-bit OSes in VirtualBox, see [https://superuser.com/a/866963 how to enable them].'' |
| + | :#* ''When creating the virtual disk, at least 20GB is recommended.'' |
| + | :# [https://store.steampowered.com/about Download the Steam installer] in the VM and run it. |
| + | :# Launch Steam to finish installation. If nothing happens, see [https://askubuntu.com/questions/771032/steam-not-opening-in-ubuntu-16-04-lts these extra steps] to fix it. |
| + | :# Install Stardew Valley through Steam. |
| + | :# [[Modding:Player Guide/Getting Started#Install SMAPI|Install SMAPI]]. |
| + | :# ''(optional)'' Install [https://www.mono-project.com/ <samp>mono-complete</samp>] and [http://www.monodevelop.com/download/ MonoDevelop] in your VM. This is only needed if you want to compile separately for Linux/Mac. When installing <samp>.deb</samp> files, use the instructions for [https://zorinos.com/help/install-apps/#deb-files the Ubuntu version shown here]. If you run into errors, may Linux have mercy on your soul. |
| + | :# ''(optional)'' For unlocking Mac OS only: [https://www.insanelymac.com/forum/files/file/838-unlocker/ Virtual Machine Unlocker 2.1.1] for VmWare Workstation 11/12/14, VmWare Player 7/12/14, or Fusion 7/8/10. '''This is needed to boot Mac OS on a virtual Machine''' |
| | | |
− | | + | ; If your main computer is Linux or macOS: |
− | * '''If your main computer is Linux or Mac:'''
| + | :# Install [https://www.virtualbox.org/ VirtualBox]. |
− | *# 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]. |
− | *# [http://www.macworld.co.uk/how-to/mac-software/run-windows-10-on-your-mac-using-virtualbox-3621650/ Create a VM with Windows].
| + | :# Install Stardew Valley in your VM. |
− | *# Install Stardew Valley in your VM.
| + | :# [[Modding:Player Guide/Getting Started#Install SMAPI|Install SMAPI]]. |
− | *# [[Modding:Player Guide/Getting Started#Install SMAPI|Install SMAPI]].
| + | :# ''(optional)'' Install [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] in your VM. This is only needed if you want to compile separately for Windows. |
− | *# ''(optional)'' Install [https://www.visualstudio.com/vs/community/ Visual Studio Community] in your VM. This is only needed if you want to compile separately for Windows.
| |
| | | |
| ==Fix common build warnings== | | ==Fix common build warnings== |
| After building your project, you can see build warnings via ''Visual Studio > View > Error List'' or ''MonoDevelop > View > Pads > Errors''. Here are some common ones. | | After building your project, you can see build warnings via ''Visual Studio > View > Error List'' or ''MonoDevelop > View > Pads > Errors''. Here are some common ones. |
− |
| |
− | ===Mismatch between the processor architecture...===
| |
− | Sample warning: "''There was a mismatch between the processor architecture of the project being built "{0}" and the processor architecture of the reference "{1}". This mismatch may cause runtime failures.''"
| |
− |
| |
− | That warning is normal. The error is saying that your build is set to 'Any CPU', but Stardew Valley is x86-only so it'll only work in x86 anyway. You can either ignore it, or [https://docs.microsoft.com/en-ca/visualstudio/ide/how-to-configure-projects-to-target-platforms change your platform target] to x86.
| |
| | | |
| ===This implicitly converts...=== | | ===This implicitly converts...=== |
| Sample warning: "''This implicitly converts '{0}' from Net{1} to {2}, but Net{1} has unintuitive implicit conversion rules. Consider comparing against the actual value instead to avoid bugs. See https://smapi.io/buildmsg/avoid-implicit-net-field-cast for details.''" | | Sample warning: "''This implicitly converts '{0}' from Net{1} to {2}, but Net{1} has unintuitive implicit conversion rules. Consider comparing against the actual value instead to avoid bugs. See https://smapi.io/buildmsg/avoid-implicit-net-field-cast for details.''" |
| | | |
− | Your code is referencing a [[Modding:Modder Guide/Game Fundamentals#Net fields|net field]], which can cause subtle bugs. This field has an equivalent non-net property, like <tt>monster.Health</tt> (<tt>int</tt>) instead of <tt>monster.health</tt> (<tt>NetBool</tt>). Change your code to use the suggested property instead. | + | Your code is referencing a [[Modding:Modder Guide/Game Fundamentals#Net fields|net field]], which can cause subtle bugs. This field has an equivalent non-net property, like <samp>monster.Health</samp> (<samp>int</samp>) instead of <samp>monster.health</samp> (<samp>NetBool</samp>). Change your code to use the suggested property instead. |
| | | |
| ===FieldName is a Net* field...=== | | ===FieldName is a Net* field...=== |
Line 68: |
Line 85: |
| Your code is referencing a [[Modding:Modder Guide/Game Fundamentals#Net fields|net field]], which can cause subtle bugs. You should access the underlying value instead: | | Your code is referencing a [[Modding:Modder Guide/Game Fundamentals#Net fields|net field]], which can cause subtle bugs. You should access the underlying value instead: |
| <ul> | | <ul> |
− | <li>For a reference type (i.e. one that can contain <tt>null</tt>), you can use the <tt>.Value</tt> property (or <tt>.FieldDict</tt> for a <tt>NetDictionary</tt>): | + | <li>For a reference type (''i.e.,'' one that can contain <samp>null</samp>), you can use the <samp>.Value</samp> property (or <samp>.FieldDict</samp> for a <samp>NetDictionary</samp>): |
− | <source lang="c#"> | + | <syntaxhighlight lang="c#"> |
| if (building.indoors.Value == null) | | if (building.indoors.Value == null) |
− | </source> | + | </syntaxhighlight> |
| | | |
| Or convert the value before comparison: | | Or convert the value before comparison: |
− | <source lang="c#"> | + | <syntaxhighlight lang="c#"> |
| GameLocation indoors = building.indoors.Value; | | GameLocation indoors = building.indoors.Value; |
| if(indoors == null) | | if(indoors == null) |
| // ... | | // ... |
− | </source></li> | + | </syntaxhighlight></li> |
− | <li>For a value type (i.e. one that can't contain <tt>null</tt>), check if the parent is null (if needed) and compare with <tt>.Value</tt>: | + | <li>For a value type (''i.e.,'' one that can't contain <samp>null</samp>), check if the parent is null (if needed) and compare with <samp>.Value</samp>: |
− | <source lang="c#"> | + | <syntaxhighlight lang="c#"> |
| if (item != null && item.category.Value == 0) | | if (item != null && item.category.Value == 0) |
− | </source></li> | + | </syntaxhighlight></li> |
| </ul> | | </ul> |
| | | |
Line 92: |
Line 109: |
| ===An instance of analyzer ... cannot be created=== | | ===An instance of analyzer ... cannot be created=== |
| Update to the latest [https://visualstudio.microsoft.com/vs/community/ Visual Studio]; the NuGet package uses a recent feature that isn't available in older versions. | | Update to the latest [https://visualstudio.microsoft.com/vs/community/ Visual Studio]; the NuGet package uses a recent feature that isn't available in older versions. |
| + | |
| + | ===Feature 'global using directive' is not available in C# 9.0=== |
| + | Go to your solution's project file (the .csproj file) and change the <ImplicitUsings> property from "enable" to "disable". |
| | | |
| ==Other issues== | | ==Other issues== |
− | ===Can't target .NET Framework 4.5=== | + | ===Can't target .NET 5=== |
| If the target framework list has options starting with... | | If the target framework list has options starting with... |
− | * ".NET Core" or ".NET Standard": you created the wrong type of project. Make sure you create a .NET '''Framework''' project for your mod. (It's a bit confusing.) | + | * ''.NET Framework'': you created the wrong type of project. Make sure you create a .NET 5 project for your mod instead. (The naming is a bit confusing.) |
− | * ".NET Framework" (but none for 4.5): you can use .NET Framework 4.5, 4.5.1, or 4.5.2. If you don't have any of those, you can install the [https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers .NET Framework 4.5.2 Developer Pack] to add it. | + | * ''.NET Core'', ''.NET Standard'', or ''.NET 5+'': use .NET 5 for compatibility with the game. If you don't have that option, you can install the [https://dotnet.microsoft.com/en-us/download/dotnet/5.0 .NET 5 SDK] to add it. |
| | | |
− | ===Visual Studio can't find the game/SMAPI/XNA DLLs=== | + | ===Visual Studio can't find the game/SMAPI/MonoGame DLLs=== |
| + | <span id="Visual_Studio_can.27t_find_the_game.2FSMAPI.2FXNA_DLLs"><!--old section name--></span> |
| Common solutions: | | Common solutions: |
| * Restart Visual Studio. | | * Restart Visual Studio. |
| * Make sure the game and SMAPI are correctly installed and work fine. | | * Make sure the game and SMAPI are correctly installed and work fine. |
| * Check for an error like "''Failed to find game install path''". If it's present, you need to [https://smapi.io/package/custom-game-path specify your game path]. | | * Check for an error like "''Failed to find game install path''". If it's present, you need to [https://smapi.io/package/custom-game-path specify your game path]. |
− | * Make sure you created a .NET Framework project, '''not''' .NET Core or .NET Standard. (See [[Modding:IDE reference#Set the target framework|how to set the target framework]]; if you see options like .NET Standard or .NET Core, delete the project and create a .NET Framework project instead.) | + | * Make sure you created a .NET 5 project, '''not''' .NET Framework. (See [[Modding:IDE reference#Set the target framework|how to set the target framework]]; if you see options starting with .NET Framework, delete the project and create a .NET 5 project instead.) |
− | * Make sure you target .NET Framework 4.5, 4.5.1, or 4.5.2 (see [[Modding:IDE reference#Set the target framework|how to]]). | + | * Make sure you target .NET 5 (see [[Modding:IDE reference#Set the target framework|how to]]). |
| | | |
| If those didn't fix it: | | If those didn't fix it: |
Line 114: |
Line 135: |
| ==Ask for help== | | ==Ask for help== |
| See [[Modding:Help]] for how to get help! | | See [[Modding:Help]] for how to get help! |
| + | |
| + | [[es:Modding:Guía del Modder/Prueba y solución de problemas]] |
| + | [[pt:Modificações:Guia do Modder/Teste e Solução de Problemas]] |