Thunderkit - Using the DOTS framework in Modding

The Data Oriented Technology Stack (otherwise known as the DOTS framework) is a development philososphy and technology tools designed for creating fast performant code by utilizing Data oriented programming. which allows for highly efficient and performant code.

The DOTS framework is built on three key pillars, of which 2 are accessible and one is unknown if it can be used in modding.

Framework Part	Description	Availability
ESC - Entity Component System	The ECS is a framework that works on a purely data driven design, where it has Entities that populate scenes, but lack data and behaviour, components which hold the data in an Entity, and Systems, which transform the data of components in a deterministic way	Unknown
Burst Compiler	Burst is a compiler that can be used alongside the Job system to create code that improves performance by translating your IL/.Net bytercode into native CPU code using the LLVM compiler.	Available, known method via Unity and ThunderKit
C# Jobs	Allows you to create multithreaded code for performance intensive tasks, such as multiple transform modifications, complex mathematic operations and more. Has built in guard rails for development of safe multithreaded code	Available

This guide will not cover how to use the Burst Compiler or how to Write C# jobs, it'll only cover how to get access to the framework on a ThunderKit context and how to compile your mod

Burst and Jobs in RoR2

Utilizing Jobs is an already by default implemented feature of the current unity version, however, We've made the mod BurstsOfRain for the purposes of extending the development potential by including extra libraries for running burst compiled Jobs and access to improved Native Collections such as Native Lists, Native Hash Maps and more.

Bursts of Rain is a thunderstore package that contains a lightweight assembly that can be used for loading burst-code assemblies, however, it also comes with re-distribution of specific unity DLL's that are loaded which can be used in jobs.

Redistributed Assembly	Description	Version
System.Runtime	Required for the collections package.	Not Applicable
Unity.Burst	The runtime front-end of the Burst compilation system, this runs the bursted code when applicable.	1.8.18
Unity.Collections	A package that contains multiple, thread safe, native collections that can be used within jobs, such as Lists, Queues, Hashmaps and more.	1.5.1
Unity.Mathematics	A light-weight math library with a shader-like syntax which can be safely used within jobs.	1.2.6

As a note, it is NOT recommended to install Bursts of Rain directly with the ThunderKit package manager for the following reasons:

Unity will not recognize the redistributed unity assemblies, this is an intentional feature.
You'll have to manually install the selected versions of Burst, Collections and Mathematics.
The collections package has a dependency on Mono.Cecil, which makes modding difficult.

For these reasons, this guide will cover installing Bursts of Rain using the RoR2 Thunder Burster package.

Installing RoR2 Thunder Burster

It is recommended to do a full game re-import once the package is installed. to do this, select all folders within your project's Packages folder (ProjectRoot/Packages) except for manifest.json and packages-lock.json. and Delete the folders.

Go to Window/Package Manager to open the Unity Package Manager

Go to the RoR2ThunderBurster Repository. Taking a look at the website you can see a big green <> Code button. Clicking it and then clicking the copy url button will copy the link to the repository.

On the Package Manager window, hit the + button, and click the Add package from Git URL... option

Paste the git URL copied beforehand. As a side note, it is recommeneded to install only the latest tagged release from the repository. To install a specific release tag, append the Tag's name preceded by a # character.

For example, to download the version 0.0.2 of RoR2 Thunder Burster to your project, you must use the git url https://github.com/risk-of-thunder/RoR2ThunderBurster#0.2.2

Once installed, you may get a popup regarding missing dependencies, clicking on "Install All" will install all the listed packages. it may take a while for the editor to finish installing your dependencies.

You may stumble upon this popup once the packages are installed, click "Ok" to proceed. If this popup does not appear or your project ends in an invalid state, refer to the next section.

Open the ThunderKit settings window, and go to the import config, you may notice that a new import step for installing Bursts of Rain has appeared, reimport your game and youre ready to go.

Project Troubleshooting

If you installed RoR2ThunderBurster after you've imported the game your project might end up in an unstable/unusable state, this is because the Collections package comes with an explicit dependency to Mono.Cecil, which gets installed and conflicts with our BepInEx mono.cecil assemblies. To fix this, you can do the following steps.

Go to ProjectRoot/Library/PackageCache find the folder com.unity.collections@1.5.1

Copy this folder and paste it on ProjectRoot/Packages and remove the substring @1.5.1, this Embeds the package into your project and can now be modified.

Download this Zip file, which contains modified files. Open the zip file and drag all its contents inside the com.unity.collections folder. Replace all files.

Your project should be back to an usable state, if not, ask for help in the RoR2 modding community's ThunderKit channel.

Using RoR2 Thunder Burster

RoR2 Thunder Burster consists of 2 new Compossable Objects added.

Compossable Object	Compossable Type	Description
BurstAssemblyDefinitionsDatum	Manifest Datum	A subclass of the AssemblyDefinitions Manifest Datum, it's used by the following pipeline job to burst the specified assemblies using the Burst compiler.
BurstStagedAssemblies	Pipeline Job	A custom pipeline job, that takes the main manifest's BurstAssemblyDefinitionsDatum and bursts the defined assemblies.

Begin by modifying your manifest and replacing it's "Assembly Definitions" datum for the "Burst Assembly Definitions Datum". You can lick on the cogwheel next to the manifest datum to remove it.

To burst your assemblies, add the Burst Staged Assemblies pipeline job to your build pipeline, this pipeline job should run After Stage Assemblies. It also contains a field that you must assign the previously executed Stage Assemblies job. this is used to obtain necesary metadata for the burst compiler to work.

Executing your pipeline will build your assembly, and then burst said assembly thru the burst compiler. The bursted assemblies will be staged on the same folder as your Assembly.

Enabling your assembly ingame

To enable your assembly ingame, add a Precompiled Assembly Reference to Bursts of Rain.

Somewhere during your mod's initialization routine, you can utilize the main class of Bursts of Rain for loading your bursted assembly. Here it's being done in my mod's Awake call.

Your bursted assembly is now loaded at runtime, and burst-compiled jobs will be used instead of their native C# jobs.