Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Welcome to the Core Keeper Modding wiki. Check the links in the sidebar to get started with modding this amazing game!
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.
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
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:
can generate .NET assemblies which can be open with DnSpy.
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:
This wiki is an accumulation of the work of several people. To keep this wiki in the best state possible we ask of you to contribute wherever you think possible.
So you want to contribute to our wiki! Great!
Step 1: Follow this link to join as an editor of the wiki.
Step 2: Sign into GitBook using whatever account you'd like your edits to be credited too
Step 3: Click the big EDIT button in the top right hand corner of your screen.
Step 4: Edit the pages to your hearts content. If you would like to bring your edits to the next level, consider reading up on the markdown format GitBook uses.
Step 5: Submit your changes for review using the button in the lower right corner.
If everything looks good to us, we'll add your changes to the wiki! Thanks for helping the community by spreading your knowledge!
This page includes instructions prior to release of Mono build of the game
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. It is recommended to copy this to your "projects" folder. The folder you need should have Assets
folder in it. You can also rename this folder to your liking.
Go into the folder in the project root and open folder with the name Packages
.
Create or open file with the name manifest.json
in the Packages
folder and paste this into the file:
Save manifest.json
and go back into project root. 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!
Move all the files in the Assets/Plugins
folder to somewhere safe and make sure the folder is empty.
Note: Plugins
could be called differently. Devs of Asset Ripper change it's name all the time. If you can't see it, look for a folder in Assets
folder with .dll
files in it.
To prevent your project from crashing go to ProjectSettings
folder and delete file named ProjectSettings.asset
. This file seems to contain some broken settings, so deleting it fixes the issue
Install Unity version 2021.3.14f1
from the Unity Download Archive: https://unity3d.com/get-unity/download/archive.
Go through the standard Unity installation and wait until it's done.
Open the Unity hub and select the folder you created when exporting the AssetRipper files.
Open the project with Unity version 2021.3.14f1
and wait for it to load. This can take a while.
Find the temp folder in where you placed files from Plugins folder earlier. Copy paste all contents from the script EXCEPT the following:
All Unity assemblies which start with Unity.
(errors will occur due to duplicate assemblies if these are pasted in)
Assembly-CSharp
back into Assets/MonoScript
.
Note: keep assemblies with Sentry
in the name, even if they have Unity
in the name
Make sure that you are doing this while Unity is RUNNING. Otherwise it will crash!
Download Editor Kit package from github: https://github.com/Jrprogrammer/CoreLib/releases and place it's contents in the assets folder.
In your project settings change URP rendering asset from PugRP to one in the Editor Kit package.
Restart Unity to fully get the project assembled.
You should now be able to see the assets in the Unity editor.
Enjoy and make some cool stuff.
There might be missing script references. This tool will help with the missing script references.
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 guide, replacing values for Core Keeper. Core Keeper appId is 1621690
This page is intended to serve as a reference while no other tutorials have been made. It is basically a pastebin.
Getting the main manager instance opens a lot of doors to the rest of the game's functionality! Almost everything related to the game is stored in this object instance.
Basic patch:
Use this boolean to see if the game is in its main loop: Manager.currentSceneHandler.isInGame
The normal Unity Input system works so it's possible to assign functionalities to keys that haven't been defined by the game itself. A Input.GetKeyDown()
in an Update
method should be enough.
Also CoreLib provides an API to add new Rewired keybinds. These keybinds will be rebindable by the user.
In your plugin Load()
method call:
Then in your MonoBehavior Update()
method you can check the button:
It is possible to change the recipe of an item by changing the requiredObjectsToCraft
value.
BepInEx allows to run normal MonoBehaviour classes through the IL2CPP BasePlugin.
The way it is set up is through an AddComponent<T>()
statement in the Load()
method. <T>
is your custom MonoBehaviour
class.
This is handy for when you need to run code every frame without patching into an existing class' lifecycle.
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 game is using a few tools that are important to understand while modding. Specifically these are DOTS, ECS, Jobs system and Burst
Data-Oriented Technology Stack (DOTS) is a new feature of Unity, which is currently is in pre release. It uses completely different way of thinking about game state than usual Game Object based approach.
With DOTS also come ECS, Job Systems and Burst
Entity Component System (ECS) is the main package for DOTS. It provides the core feature of DOTS: Entities, Components and Systems
Entities are containers for many Components. The class itself is just a identifier into the ECS state.
Components are structs, which hold component data. However they don't hold any behavior.
Systems hold the actual behavior. They can perform operations of group of components in bulk, utilizing Job Systems and Burst to do so in multi-threaded way
When making the game and it's prefabs, devs are using Hybrid system, which allows to author the content using typical game objects and MonoBehavior based components.
After the game is loaded each Authoring component performs conversion from game object world to ECS world and ECS components.
Jobs are the way devs write system behavior which allows to easy multi-threading.
Unfortunately for us, we can't create custom Jobs. And patching such jobs also currently poses an issue due to Burst compilation.
Burst compiler is very similar to Il2Cpp in the way it takes C# and converts it to Native code. This code is stored in a native library called lib_burst_generated.dll
. The difference is burst uses a very limited subset of the C# language, which allows it to have simpler and faster native code.
Unfortunately currently we are not able to patch Burst compiled methods.
If you are struggling to understand ECS, try or .