Modding

This page is the main hub for information regarding Thrive modding.

Note that a comprehensive modding guide for Thrive will be written at some point, however some of the early notes below should be relatively helpful.

If you have written / know of any community guides or tutorials, please let us know and we'll link them here.

Creating Mods

Before you can start you will need a few tools depending on the type of mod you want to make.

If you want to change anything more than the contained JSON files in the game, you will need the Godot editor.

Download Godot mono version. The latest is usually suitable but sometimes Thrive hasn't been yet updated to the latest version. You can refer to the setup instructions file in the main Thrive repository to find out which version is currently used.

Before diving in, you may want to check the example mods to see how they are created, or once reading through the instructions you can refer back to them to see a working example.

Just JSON Change

Thrive contains JSON files that define many aspects of the game, and some basic modding can be done by editing them. To start you should grab godotpcktool and the latest release of Thrive. With the godotpcktool you can then extract the Thrive files, for example:

godotpcktool --action extract -o extracted Thrive.pck

This will create a folder called "extract" containing the contents of the Thrive.pck file. Next you should look for the files you want to modify (note that graphics assets can't be changed here as they need to be imported through Godot, see the next section for info about that) and modify them. After this comes an important step: you need to delete any files you did not modify otherwise your mod's compatibility with other mods and Thrive changes will be greatly reduced as it would contain unnecessary files that are applied when your mod is enabled. Note that depending on which parts of the Thrive files you keep you may be required to license your mod under the GPL or creative commons licenses that Thrive is licensed under.

After you have created the folder structure for your mod changes, comes the time to repack it. This can also be done with the godotpcktool roughly like this:

godotpcktool --action add MyMod.pck --remove-prefix extracted extracted

This should create a compatibly structured .pck file for Thrive. To make sure, you can use the godotpcktool to list the contents in a .pck file and compare if the paths for the files you replaced look the same in the official version and in your mod. To list the contents of a .pck simply run:

godotpcktool PckFileName.pck

Note: in the future you may need to use the --set-godot-version 3.3.4 parameter to suppress warnings if Godot checks the engine version the .pck file claims to be made with

To find out how to get Thrive to be able to load your .pck as a mod check the Modding#Putting the Mod Together section on this page.

Simple Asset Changes

Create a new folder and use the Godot editor to start a new project in the folder. You should name the folder with PascalCase naming convention. And name your Godot project with spaces in the name like "Pascal Case". When selecting the name of the folder to have your mod in, you should use the same name as you used for the Godot project folder.

To get started find the path in the Thrive repo to the game asset you want to override and create similar file structure in your new Godot project. Then place a file with the same name as in the Thrive repository at that path. The Godot editor when your project is open should automatically import the file (if it is a type that needs importing), you can adjust the import options and re-import if desired.

If you make an icon please size it down to about 128x128 and name it at least a bit uniquely, otherwise the loaded mods all overwrite the icon path with their own, though this isn't very likely to cause a problem, still unique naming is not very hard to do so it is recommended. For example "disco_icon.png"

After you have added all the assets you want to replace and other files, add an export option to export to a desktop platform (Windows or Linux is recommended), and setup the export to include all the resources you need. When exporting make sure to not enable embedding the .pck file option as otherwise the file will be inaccessible. Now you should be able to export your "game", which is really a mod, from the Godot editor. This should created a game executable and a .pck file named after your mod in the folder you selected. You can use godotpcktool to inspect what was added to your .pck. For licensing and copyright reasons it would be good to check that you aren't accidentally including Thrive files or content you do not own in the mod.

Next see Modding#Putting the Mod Together to learn how to get Thrive to load your new mod.

Code Mods

Godot-based mods

This page or section contains outdated information. This often happens when plans are changed after something has been written.

This section needs to be slightly updated for Godot 4.

You should first follow the Godot project setup instructions in the above section. Then you can add a new C# script to your Godot project. Note that C# scripts attached to scenes in mods currently do not work, as such you need to make scene files that don't have any C# scripts attached. You can still make Godot Node type inheriting C# classes and manually construct their "scenes" in their _Ready methods.

When doing mods that have custom scenes or code files it is a good idea to put them in a subfolder named after the mod. So for example you would have "DamageNumbers/DamageNumbers" folder containing scenes if the "project.godot" file is in "DamageNumbers" folder (like "DamageNumbers/project.godot"). This way when multiple mods are loaded (or new files are added to the base game) they won't conflict with your mod's files.

You should try to keep your C# class names unique even though they currently probably work even with duplicate names, but in the future with C# scripts attached to nodes from mods, it may become a requirement for the names to be unique. For the primary class that runs first, it probably can't be in a namespace, but for other classes you should use namespaces to minimize the chance of conflicting class names.

In order to refer to Thrive classes and interfaces, you need to add a reference to your mod's .csproj file to it, for example:

<ItemGroup>
  <Reference Include="Thrive">
    <HintPath>..\..\Thrive\.mono\temp\bin\ExportRelease\Thrive.dll</HintPath>
  </Reference>
</ItemGroup>

This will assume that Thrive repo is cloned to 2 folder levels up from your mod's folder and has been exported at least once (that's when the mono/temp/bin/ExportRelease folder gets updated). You should edit the referenced Thrive assembly version in the template to match the Thrive version you are using. To export Thrive you need to follow the setup instructions to get Thrive compiling and exports working. Note that you should probably checkout a release tag in the Thrive repo so that you have the same code locally as is in the official release, otherwise your mod might not work with the current release, but only with the next release.

When using C# code in a mod, you need to extract the created .dll file out of the exported .pck file in order for it to be loadable. Alternatively you can dive into the ".mono/temp" folder to find the created dlls in the "ExportRelease" folder. However, with the .pck approach you still need to trim out the files from your .pck that should not be in there, namely probably all of the .dll files, even the one for your mod as it won't be loaded from the .pck file. Trimming is important because your mod will become GPL licensed if you accidentally include the Thrive library in your mod's files, so this is important to trim out.

Note that you should not license your mods under a GPL license. This is because they will be license-wise incompatible with the Steam version of the game (and all other future versions that are on limited platforms that don't allow GPL licensing). So it is recommended to use LGPL if you must, but preferably a a less restrictive open license would be used for mods. If you don't know which license to pick, then use the MIT license.

You can use godotpcktool for example to extract a .pck contents and trim out contents. You can also use it to check what files are contained in your mod and Thrive to verify that the paths are correct to resources you want to overwrite. For example, the following extracts all .dll files:

godotpcktool ModName.pck --action extract -i '\.dll' -o extracted

Be careful with quoting if your .pck name has a space in it, also the part specifying the dll pattern to extract, different shells may require different quote characters around it. After the extract is successful look in the "extracted/.mono/assemblies/Release" folder, it should have the dll for your mod (named after your Godot project's name). Note that you only need to copy that single DLL *unless* you use C# dependencies not used by Thrive already.

Now you can then trim the .pck file in order to remove the Thrive code from it:

godotpcktool ModName.pck --action repack -e '\.mono/'

That command will remove any files with paths containing ".mono/" from the .pck (so any compiled dlls should be gone). You should still use the godotpcktool to verify that all the files that should be removed are gone in order to not violate copyrights.

Copy the trimmed .pck and the dll file to the mod folder when you are putting the mod together. As extra options in the mod info JSON you need to specify the dll file relative path in the "Mod Assembly" field and in the "Mod Assembly Main Class" field you need to put the name of your mod's main class that implements the IMod interface and acts as the entrypoint to your mod.

Exported C# code at least our example mod, works for also a different platform so no platform specific mod exporting is needed, just one export is enough.

Standalone mods

You can create C# mods that don't rely on the Godot editor at all. For these you can just create a new C# SDK project, just make sure to set the target runtime to be old enough. Currently net472 is a good runtime version to target. Other than that you just need to add a reference to the Thrive.dll as described above and if you use types from Thrive that depend on Godot, you'll also need to add a reference to ..\Thrive\.mono\assemblies\Release\GodotSharp.dll. After that is done you can just write your mod like a normal C# project, compile it into a .dll file and put it into a mod folder for distribution (see the section about bundling up a mod). This approach has the benefit that you can just directly and very easily find the created .dll file to include in the mod without requiring any extra tools.

Using Harmony

Thrive support using Harmony to make mods that modify existing Thrive code during runtime. This allows much more complex mods to be done that don't rely on having the necessary hooks in the Thrive codebase already to work. But that also makes it more complex to make mods, especially if you need to fine tune the behaviour of an existing method as then you need to dynamically change the IL bytecode. You can find general information about using Harmony here. Note that when using Harmony you need to patch the base class if a derived class doesn't overload a method, otherwise the method to patch won't be found. Just a quick tip if you run into null errors when your mod is loaded.

After making the Harmony compatible patch classes, there are two ways to load them into Thrive. The first is that you make a normal code mod as described above and manually call the Harmony patch and unpatch methods. There's an example mod showing how you can do that here. The second is to set "UseAutoHarmony": true in your mod's info file. After that you just need to set the mod assembly correctly and Thrive itself will automatically load all the Harmony patches in your assembly as needed and also unload them. There's an example mod Cell Autopilot that does it this way.

GDScript Mods

As an alternative to C# code mods, you can make GDScript mods.

TODO: write instructions once this works, see: https://github.com/Revolutionary-Games/Thrive/issues/2861

Putting the Mod Together

You can use the mod manager in Thrive to create a blank mod folder with an info file. You just need to hit "new", fill in the few required details and hit the button to create the mod. After creating the mod folder you should put the .pck and the extracted .dll files (if you are making a C# mod) into it. You should edit the info JSON file to refer to your .pck and other resources correctly, for example to the mod icon if you have one. For the mod internal name you should use the same name as for the Godot project you created in an earlier step, this will also be the name of the folder that contains your mod.

After the mod folder is populated you can start up Thrive and try to enable the mod to see if it works. Some mods may only work properly if the game is restarted in case the mod overwrites some resource that doesn't get reloaded without a restart.

Uploading Mods

If the mod works you can then zip up the mod folder for distributing to other people or upload it to the Steam workshop.

Steam Workshop

To upload mods to the Steam Workshop you just need to have the mod installed locally and detected by Thrive. Then you can just hit the "upload" button in the mod manager to begin the process. First select the mod you want to upload and then use the buttons and forms that appear to fill in the necessary details, and then hit the upload button.