Mod development guide

This article is about Modding – changing the original game.
Please note that modding is not maintained by Nine Dots Studio.

This page is a guide for people who want to learn how to get started developing Mods. Outward is made in Unity, and uses the engine version 2020.3.26 for Definitive Edition and 2018.4.4 for Vanilla. The recommended way to make mods is either through SideLoader (C# and non-C# mods) and/or BepInEx (C# mods).

• For further help, join the Outward Modding Discord.

Resources

The following resources may help you with your mod development:

• Outward Modding Discord - a place to chat with other modders and ask for help
• Outward Mod Template - recommended starting point for making a C# mod
• Unity Scripting API reference - Unity's official C# API reference and articles

Tools

• dnSpy - a tool for looking at the source code of Outward (see Decompiling below)
• sideloader - a tool and library for making Outward mods (sinai-dev sideloader no longer found)
• Unity Explorer - a tool for exploring the game at runtime through a menu similar to the Unity Editor

GitHub Source Code Repositories

These are the GitHub repositories for Outward Mods. If you are a mod developer, feel free to add your repo here.

• Sinai's Mods Repo
• Vheos777's Mods repo
• Skully250's Mods Repo
• Lasyan3 Outward Mods
• McRoberts Grindward

Creating a non-C# Mod

The SideLoader is a community tool for Outward which can be used to simplify the process of changing or creating custom assets, and in a way that is friendly with other mods.

While SideLoader can be a powerful library for making C# mods, it can also be used through an in-game menu without any real knowledge of Unity or programming. See the Outward SideLoader Docs for more information.

Creating a C# Mod

If you have no experience with Unity or C#, it is recommended to check out these tutorials:

• Unity Basics tutorial
• Unity C# Scripting tutorial

You will need to install an IDE if you do not already have one. Visual Studio Community is a popular, free IDE. when installing, make sure to enable .NET Support in the installed features. Another option is Rider.

From here, see the Outward Mod Template and follow the instructions to complete your first mod. This template is recommended when creating mods, as it comes set up with the correct packages and references you will need for modding.

See also:

• BepInEx documentation
• HarmonyX documentation

Outward Modding Libraries

Adding the BepInEx NuGet feed with Visual Studio.

Note: if you are using the Outward Mod Template, all references (except SideLoader) are already added.

An essential part of C# mod development are your references, which can be added through NuGet Packages (recommended) or through direct DLL references (not recommended, but fine if you know what you're doing).

The Outward modding community has partnered with BepInEx to bring you all the references you should need through NuGet. First, you will need to add a reference to the BepInEx NuGet feed.

For Visual Studio:

1. Click Project > Manage NuGet Packages (if you don't see this option, select your CS Project in the Solution Explorer first)
2. On the top-right, change "Package Source" to "All"
3. Click the gear icon next to Package Sources to open the NuGet settings menu
4. Click the "+" icon to add a new source
5. Enter BepInEx for the Name, and https://nuget.bepinex.dev/v3/index.json for the source
6. Click Ok and close the window
7. In the "Browse" tab, tick the "Include prerelease" checkbox next to the search box
8. Important: Double-click on Properties (in the Solution Explorer) and select the Build tab, then enable Allow Unsafe Code.

You can now search for BepInEx and Outward NuGet packages (in the "Browse" tab in Visual Studio). Importantly, the Outward and Unity libraries have been publicized, meaning everything in the assembly has been made public. This means you can access all private/protected members in the assembly without having to use reflection.

The following packages are recommended to develop Outward mods:

• Outward.GameLibs
• BepInEx.BaseLib - choose the latest 5.X version available.
• HarmonyX
• Outward.SideLoader - optional, if using SideLoader.

After adding references, you should Shift-Select all references (expand the references list to see them all) and then in the Properties panel below, set "Copy Local" to false.

Viewing Outward source code

Using DnSpy. Click here for the full size image.

With software such as dnSpy, dotPeek or ilSpy you can look at the source code for Outward's assemblies to learn how the game works or find things which you would like to use.

This guide will cover how to use dnSpy with Outward. dnSpy is a popular, open-source decompiler.

• Get dnSpy here
• Drag the file Outward_Data\Managed\Assembly-Csharp.dll into dnSpy. This is the main Outward assembly.
  • Assembly-Csharp-firstpass.dll may also contain things you would like to use.
• Expand the { } - node, these are main game classes and do not have a namespace.
• From here, it is a process of exploration, and trial and error.
• In dnSpy, if you right-click any member or variable, you can click "Analyze" to view how the reference is used.

Debugging Outward at runtime

It is possible to debug Outward at runtime with dnSpy, with a bit of configuration.

• See this guide or this BepInEx guide for more instructions.
• You can also debug your mods in the same way.

Important Classes

These classes are some of the most important classes in the Outward assembly, which you will likely need to use at some point.

ResourcesPrefabManager

• This is where the game stores the prefabs for Items (including Skills and Quests), Item Visuals, and Status Effects.
  • Use ResourcesPrefabManager.Instance for the current instance of the manager
  • The functions GetItemPrefab, GetStatusEffectPrefab and GetEffectPreset can be used to get a handle on any item or status effect.
  • The private, static dictionaries ITEM_PREFABS, STATUSEFFECT_PREFABS and EFFECTPRESET_PREFABS contain all item and status effects.
• Check if ResourcesPrefabManager.Loaded is true before you try to use any prefabs.

Character

• The class used for all characters (players, allies and enemies). NOT used for NPC's.
• Contains most of the main fields and methods for controlling a character.
• CharacterStats and PlayerCharacterStats are used for stats
• CharacterAI is used for AI behaviour.
• CharacterManager is the manager for Characters, and SplitScreenManager is the manager for local players.

Item

• This class is obviously used for all Items and Equipment, but it is also used for Skills, Quests and other miscellaneous objects such as Loot Container objects.
• The ItemManager is used for managing currently active items in the scene.

Effect

• This class is used for things like projectiles and blasts, affecting stats, etc.
• There are many derived classes of Effect. See the derived classes using dnSpy or similar tools.
• This class is a useful one to override, as it is actually designed to be overridden. This is convenient for custom effects.

Some other important classes include:

• Global
• NetworkLevelLoader
• QuestEventManager

Harmony Patches

Harmony Patches are used to override Methods, either for an entry-point or to change the behaviour of the method. Harmony is a powerful hooking API, which comes with BepInEx. It can be accessed through the namespace HarmonyLib.

For full documentation on Harmony, see:

• The Official Documentation.
• For BepInEx, a slightly modified version of Harmony is used called HarmonyX. See the HarmonyX differences here.

For some detailed Outward-specific example of Harmony, see Mod_development_guide/Harmony.

Releasing mods on Thunderstore

Thunderstore is the recommended website to release your Outward mods. The Outward section of the website is maintained by members of the Outward modding community.

Required files

• First, using the information here (thunderstore.io), prepare the files necessary for your package such as the manifest.json, etc. You can "manual download" any package from Thunderstore and look at the contents to use as an example.
• With your Thunderstore manifest, you should at the very least have a dependency for BepInEx and/or SideLoader, unless your mod doesn't require either of these for some reason. Again, use existing mods as an example for how to do this if you are unsure.
• Double-check your manifest and ensure everything is correct. You should use a Json Validator to ensure the json is valid.

Put the release files in place

• Read this article (github.com) about how to structure your Thunderstore package for r2modman.
• Put your release files in your release folder following the instructions in the link above. Depending on the contents of your package it may vary slightly, read the guide closely if you are unsure.

If you have an SLPack folder the structure will be important - your release might look something like this:

MyPackage/
    manifest.json
    README.md
    icon.png
    plugins/
        MyPlugin.dll
        SideLoader/
            manifest.txt
            <SLPack contents here>

This will extract to:

BepInEx/
    plugins/
        <Author-ModName>/
            MyPlugin.dll
            SideLoader/
                manifest.txt
                <SLPack contents here>

Special considerations

• If you are using a SideLoader pack and you need to access your pack from C#, then you will need to use a SLPack manifest file to set the name manually, otherwise your SLPack name will change with every version you release.
• Your mod files cannot be installed anywhere other than the Outward\BepInEx\ folder, so make adjustments as necessary for that.

Make the release

• If you have not already, make an account on Thunderstore using your GitHub or Discord account.
• Double-check once more that your package is correct, you may find it helpful to compare it to an existing package.
• Upload your package and if everything was done correctly then Thunderstore will accept it, it will show up in r2modman within 5 minutes.

Other Tools

UnityExplorer

UnityExplorer is a powerful tool for debugging the game in a similar manner to the Unity Editor, and was designed by a member of this Community for Outward (although it works on almost any Unity game). It can be used to analyze the game at runtime to understand how Outward works and see how things work in an intuitive way.

UABE Mods

UABE can be used for exploring Outward's asset files, as well as exporting and even replacing assets (though, the SideLoader is probably a better option for most kinds of asset replacement or changes).

For more information on UABE, see this article.

See Also

• Modding
• Installing Mods