This guide was made for IL2CPP version of Core Keeper and no longer applies. Please refer to: https://mod.io/g/corekeeper/r/core-keeper-mod-sdk-introduction
This guide provides step by step guide on how to setup your Unity project to create custom assets or view game assets
With the release of Quality of Love update devs have changed Unity version to 2021.3.14 and switched to Universal Rendering Pipeline. Both of these changes complicate Unity project setup.
With the release of the Desert update devs have changed Unity version to 2020.3.37 and also have refactored their assemblies. These changes will heavily break existing setups.
If you have setup Unity project before and there was Unity version update, I HIGHLY recommend to back it up, and start from scratch. After you setup the project from scratch you will need NG Tools Missing Script Recovery tool to fix scripts in your assets.
With release of the mono build of the game it is now possible to use ThunderKit to setup our Unity project.
Install Unity Hub from https://unity.com/download
Install Unity version 2021.3.14f1 from the Unity Download Archive: https://unity3d.com/get-unity/download/archive using Unity Hub
Go through the standard Unity installation and wait until it's done.
Make sure that you have git installed and it's executable is in your PATH environment variable. After installing git make sure to close Unity and Unity hub completely!
Install Core Keeper mono version
Create a new project from 2D Core template using Unity Hub. Wait until project is created and imported.
Now in the menu bar click on Window/Package Manager. A window will appear. In the top left corner click install button, select add package from git URL and paste in this link: https://github.com/kremnev8/ThunderKit.git#master
Wait for ThunderKit to be installed
In the menu bar go to Tools/ThunderKit/Packages. Now install Core Keeper Import Extensions package.
Once it is installed in the ThunderKit settings tab Import Configuration. You should see a bunch of new importers.
In ThunderKit settings tab ThunderKit Settings. Click on the Browse button. Select the executable of your Mono Core Keeper. Now click on the Import button
This step might take a while to complete. Once it's done, you will be asked to restart Unity, click Restart Project
At this point your project is functional. You can create custom assets and export them. Next steps are optional.
Download the latest version of AssetRipper from their GitHub repository at https://github.com/AssetRipper/AssetRipper. The name is pretty descriptive of what it does.
Extract the zipfile and open AssetRipper.exe.
Leave all the settings on default except for Script Export Format and Script Content Level, these should respectively be set to Dll Export Without Renaming and Level 2
Then drag and drop your game folder (The whole folder called Core Keeper) into AssetRipper.
Wait until AssetRipper is done loading the game content and then click on Export > Export all files in the left upper corner, and select a temporary folder.
You should now have a folder with all the assets of the game.
In the extracted folder look for Assets folder. From it you want every folder APART from Plugins.
In your project Assets folder create a folder to house these assets, for example Core Keeper and move all files from exported Assets there.
Now Unity will start to import these. This will take a while to complete.
There might be missing script references. This tool will help with the missing script references.
Previous version of this guide can be found here
This guide was made for IL2CPP version of Core Keeper and no longer applies. Please refer to: https://mod.io/g/corekeeper/r/core-keeper-mod-sdk-introduction
To start modding this game follow these steps. This guide assumes you know C# language and familiar with it's tools.
Install Visual Studio or Jet Brains Rider IDE. Both of these will work fine, however I personally would recommend Rider as its much better if you can get it.
Follow BepInEx staring guide to setup your basic .NET project
Install DnSpy and setup source viewing
Make sure to use CoreLib in your mod. It will make adding custom content easier
If you intent to make custom blocks, enemies, etc follow Unity project setup guide
Also below you can find the list of commonly used libraries and tools.
BepInEx is a plugin framework for Unity and .NET framework games. We use BepInEx to load the mods into the game.
Be sure to select the IL2CPP code examples when you're creating your mod!
Link: https://docs.bepinex.dev/master/articles/user_guide/installation/index.html
Download the latest IL2CPP build here: https://builds.bepinex.dev/projects/bepinex_be
CoreLib is a modding library made specifically for Core Keeper. It provides a lot of features that make it easier creating your mods. This includes, but not limited to:
Custom items, blocks, enemies, NPC, etc.
Adding items using JSON
Easier access to Rewired input system, localization
Custom chat commands
To use it in your mods just add the NuGet to your project references
Link: https://github.com/Jrprogrammer/CoreLib
Harmony is a library for patching, replacing and decorating existing classes and methods in the game. The patching is done in runtime, which means you don't have to change the existing code! We use harmony to run our code before or after game methods. This allows us to modify game behavior.
It is recommended to read through the Introduction, basics, patching and annotations chapters. Also please note that transpilers are not apllicable with Il2Cpp
Link: https://harmony.pardeike.net/articles/intro.html
DnSpy is a tool that allows to read .NET assemblies code with ease. Unfortunately Core Keeper is made with the IL2CPP backend. This means we can't use DnSpy itself to view the source code. However it can be useful to view assemblies generated with Cpp2Il.
Important! If you look for a dnSpy tutorial, most will tell you to look for Assembly-CSharp.dll. This is NOT the case with Core Keeper and the relevant DLLs all begin with Pug (Pug.Core, Pug.Other and PugWorldGen)
Link: https://github.com/dnSpy/dnSpy
Cpp2Il is a tool that attempts to reconstruct game assemblies, such that DnSpy would be able to read them. The tool is currently WIP and does not provide full and accurate output, however it is still useful.
Link: https://github.com/SamboyCoding/Cpp2IL
Ghidra is a free and open source reverse engineering tool developed by the National Security Agency (NSA) of the United States. This tool allows us to read the GameAssembly.dll directly. This assembly contains compiled machine game code. To make it easier to find relevant code we can add Il2Cpp metadata. To do so we can use Il2CppInspector or Il2CppDumper
Link: https://github.com/NationalSecurityAgency/ghidra/releases
UnityExplorer is a BepInEx plugin that lets you inspect game objects and classes at the runtime. The main use for this tool is to figure out how to change something or check if your code worked correctly. It also has a C# REPL console which allows to execute code right in the game.
All guides in this section are outdated as the game is now Mono built.
Recently Pugstorm released a mono version of Core Keeper. You might need it to reference it's assemblies. Here is how to get it.
This guide was made for IL2CPP version of Core Keeper and no longer applies. Normal build of the game already uses mono
Right-click the game's name in Steam and select Properties from the menu
Select Betas
Enter the following password: monobuildsmightnotbeuptodate
Click Check Code
Click the dropdown menu, select the mono branch, and click opt in
Wait for the game to automatically update (or manually update it yourself)
If you wish to have both the mono build and il2cpp one use steamcmd to install and update the mono build. Follow this , replacing values for Core Keeper. Core Keeper appId is 1621690
You can use DnSpy to view game code. To set this up follow these steps:
Using DnSpy navigate to the game's asseblies, which can be found in <game path>/CoreKeeper_Data/Managed folder
This guide was made for IL2CPP version of Core Keeper and no longer applies. Please refer to:
can generate .NET assemblies which can be open with DnSpy.
To generate these assemblies you need to use the tool in the command line with following options: .\Cpp2IL.exe --game-path "<path to your core keeper installation>" --just-give-me-dlls-asap-dammit
Note that the source code is divided into three assemblies (Pug.Core, Pug.Other and PugWorldGen) and to let Cpp2Il know you want to analyze them you need to use one of these:
--run-analysis-for-assembly <assembly name>. When using it you will need to run the tool three times and combine the output.
--analyze-all. This option will analyze all the assemblies, but it will take much longer.
After running the tool you will see new folder cpp2il_out. You can now use DnSpy to read the source code.
Using a binary reverse engineering tool we can get more precise output. You can use both Ghidra and IDA for this, but since Ghidra is free this guide will be focused on it.
GameAssembly.dll is the executable file you need, and you will find global metadata file in Core Keeper\CoreKeeper_Data\il2cpp_data\Metadata\.
After the tool is done executing you should see il2cpp.h, dump.cs and script.json files. These files contain metadata information we need. To import it into Ghidra first open the GameAssembly.dll with ghidra.
NOTE: For best results, choose No when Ghidra asks if you would like to perform auto-analysis when the binary is first loaded. If you receive a Conflicting data exists at address error when running the script below, re-load the binary into the project and choose No at the auto-analysis prompt.
NOTE: To significantly speed up analysis for ELF files, set the image base to zero (0x00000000) in the load options for the binary.
To import metadata into an existing Ghidra project:
From the Code Browser, choose File -> Parse C Source...
Create a new profile and add the generated C++ type header file. This is il2cpp.h.
Ensure the Parse Options are set exactly as follows:
-D_GHIDRA_
Click Parse to Program and accept any warnings. This may take a long time to complete.
Open the Script Manager and add the output folder of the Il2CppDumper.
Click Refresh to make the script appear in Script Manager.
Right-click the script and choose Run. The script is going to ask for script.json file, which you can find in the Il2CppDumper output folder. This may take a while to complete.
This guide was made for IL2CPP version of Core Keeper and no longer applies. Please refer to:
Unfortunately using these tools alone would also provide bad results. We need to add Il2Cpp metadata (Which contains information about all types, methods and fields) to the Ghidra. To do so we will use , in your command line type: