Crossplatforming a SMAPI modThis page explains how to make a mod compatible with Linux, Mac, and Windows. This guide assumes you're already familiar with SMAPI development; if not, see creating a SMAPI mod instead.
Differences between Linux/Mac and Windows
Stardew Valley uses MonoGame on Linux/Mac, and XNA Framework on Windows. Although MonoGame is highly compatible with XNA Framework, the mapping isn’t perfect — some APIs are slightly different, and their internal implementations are often different. This has several implications for mods:
- The mod needs to reference the right framework (e.g. a mod that references XNA won’t work on Linux/Mac).
- In some cases, the mod code needs to use the right method signature (which means it needs to be compiled in the target OS).
- Any mod that uses reflection to access private MonoGame/XNA code may need to handle differences in their implementation.
In addition, there are differences between Linux, Mac, and Windows themselves which affect mods (for example, file paths are formatted differently).
What you need to do
Most mods will work fine no matter which platform they were compiled on. SMAPI uses dark magic to dynamically rewrite the compiled mods for compatibility with the player’s computer, so you often don’t need to worry about it. However, SMAPI only handles the common cases — it doesn’t try to handle every possible difference. Rarely, you may need to adjust your code for compatibility or even compile two different versions (one for Linux/Mac and one for Windows).
Here’s how to maximise compatibility:
- Always use
Path.Combineto build file paths. Don’t hardcode path separators like
/, since that won’t work on all platforms.
- Use the crossplatform build config package to automatically set up your project references. This makes crossplatform compatibility easier, and makes it easier to compile your code on any platform.
- Avoid using reflection to access internal MonoGame/XNA code when possible.
- Ideally, test your mod on both Linux (or Mac) and Windows. (See the next section.)
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 VirtualBox.
- Add this premade Linux virtual machine
(requires a 64-bit computer).
In VirtualBox, click Machine » Add and choose the downloaded
.vboxfile. This is a Manjaro virtual machine with Chromium (web browser), Steam, and MonoDevelop preinstalled.
- Launch the virtual machine, and install Stardew Valley from the Steam client (preinstalled) or GOG website.
Tip: don’t change the default install path, or you’ll need to customise the mod’s build configuration.
If your main computer is Linux or Mac
- Install VirtualBox.
- Create a VM with Windows.
- Install Visual Studio Community in your VM.
- Install Stardew Valley in your VM.
Compile per-platform packages
You usually don’t need to do this! Only do this if your mod isn’t rewritten correctly by SMAPI.
Using a virtual machine
- Compile one version on your main computer.
- Compile another version in your virtual machine (see previous section).
- Create three archives with your mod’s name, version, and platform. (To reduce confusion, it’s better to create separate packages for Linux and Mac even though they’re identical.)
You should end up with three archive files like this:
PineappleMod-1.2-Windows.zip PineappleMod/ PineappleMod.dll PineappleMod.pdb manifest.json PineappleMod-1.2-Linux.zip PineappleMod/ PineappleMod.dll PineappleMod.mdb manifest.json PineappleMod-1.2-Mac.zip PineappleMod/ PineappleMod.dll PineappleMod.mdb manifest.json
Done! For more information on releasing your mod, see creating a SMAPI mod: releasing your mod.
Using experimental cross-compiling
Instead of compiling your packages using a virtual machine, you can cross-compile from the same machine. This works on any platform, but hasn’t been extensively tested. Note that you may still need a virtual machine to test your mod on both Linux/Mac and Windows.
For more information, see the SDVCrosscompile project. The rest of this section shows one way of using it, but there are other options including integrated into Visual Studio or MonoDevelop.
- Install Mono.
- Install Python 3. Make sure to enable the option that adds it to your path or environment variables.
- Download SDVCrosscompile into its own folder somewhere.
- In the mod folder, create the compile script:
On Linux or Mac, create a
compile-packages.shfile containing this command:
/path/to/xcompile.sh --output "compiled-packages"
Don’t forget to
chmod +xthe file so it’s executable.
On Windows, create a
compile-packages.batfile containing this command:
C:\path\to\xcompile.bat --output "compiled-packages"
Preparing a mod release
When you want to compile the mod, just run the
compile-packages script you created above. This
will create three mod packages in a folder named
For more information and for support, see the SDVCrosscompile project.