Find Core Keeper mods on the mod.io website!

You can browse available mods via the in-game UI (accessible via the main menu) or the mod.io site:

Use the Filters system to focus what mods are displayed. For example, filter by only the latest Game Version to see only mods compatible with the current version of the game. There is a chance that mods without the latest version tag could still be working, but you'd be trying them at your own risk.

DO NOT get mods from Thunderstore!

All mods on Thunderstore (https://thunderstore.io/c/core-keeper/) are outdated and will not work on modern Core Keeper versions.

Next up: Installing Mods

The following approaches are available:

Using the In-Game mod.io Integration

The in-game mod integration can be rather finicky, so you may want to try another approach instead. It has the following problems:

• Does not show you the list of mod dependencies (mods that must be installed for other mods to function)

• Sometimes does not automatically install mod dependencies for you

• Poor UX - for example, in order to scroll the screen, you must click and drag the mouse, as the mouse wheel does nothing

If you still want to use this approach, simply launch the game and access the Mods screen from the main menu. To start using a mod, Subscribe to it. The game should automatically check for and install mod updates every launch.

It is highly suggested that you subscribe to each mod dependency individually to ensure it is downloaded correctly. You will have to view the mod on the mod.io website to see what they are.

For the best results, relaunch your game after installing or removing mods.

Core Launcher

Core Launcher is a 3rd party tool that makes it easy to manage mods. Check out its page on GitHub for further directions.

Once you have installed it and set it up, create a Profile with the + button to start installing mods.

Core Launcher has a dedicated discussion thread on the Core Keeper discord.

Manual File Management

If you'd rather manage mod files manually, you can download them from the mod's mod.io page and place them in the mods folder yourself. Mods installed in this manner will never be automatically updated.

To do this:

1. Unsubscribe from all mods you are subscribed to on mod.io to prevent conflicts between the two approaches

2. Open your game installation folder

   • On a default windows Steam installation, this is:

     Copy

     C:\Program Files (x86)\Steam\steamapps\common\Core Keeper\

   • If that path doesn't work for you, use the above link to find out where that is on your system

3. Go to the CoreKeeper_Data\StreamingAssets\Mods subfolder, creating any folders along the way if they do not already exist.

   • On a default windows Steam installation, this is:

     Copy

     C:\Program Files (x86)\Steam\steamapps\common\Core Keeper\CoreKeeper_Data\StreamingAssets\Mods

4. Download the mods you want from the mod.io website using the Download File button
5. Unzip each of the mod zips you downloaded inside the folder so that each mod is in its own subfolder.

   • The name of each mod folder does not matter as long as it is unique, but you probably want it to include the name of the mod for later reference.

6. Ensure that each mod subfolder has a ModManifest.json file.

7. Good to go - launch the game and start playing!

Alternative Entry Point Mods

Some mods do not use Core Keeper's modding system to interface with the game and cannot be installed using the means described above. In this case, it is up to the individual mod developer to explain how to install the mod.

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.

How do I make changes to the wiki?

So you want to contribute to our wiki! Great!

Step 1: Follow 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 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!

If you want to uninstall mods, try these different approaches in order from top to bottom. Each step is more "drastic" than the last, but you might need to use a more drastic solution if your install is broken.

Unsubscribe via the main menu's mods screen

As long as you can open the game, you can use the in-game mods menu to Unsubscribe from the mod you wish to uninstall.

It's best practice to restart the game after changing your installed mods in case some of the effects from a mod linger during the game session.

Launch the game in "No Mods" mode then unsubscribe from mods

You might need to use this approach if one of your installed mods is making the Mods screen inoperable or inaccessible.

In Steam, open the game's Properties, then choose the following launch variant: Play Core Keeper (no mods). This will force the game to not load any mods when it opens.

In this state you will be able to unsubscribe broken mods from the main menu and return your game back to working state. Remember to switch back after you're done, or any mods you install later won't load!

Unsubscribe from all mods via mod.io website

If unsubscribing from mods in-game isn't working, try unsubscribing from them on the mod.io website. The "My Subscriptions" filter makes it easy to find them.

Deleting mod files from your computer

First, how are you playing the game?

First, here's a few things to know about Core Keeper modded multiplayer:

• In general, all players (and the server) should have exactly the same mods installed.

  • Some mods only need to be installed client side (or server side), refer to the mod's "Application Type" tags, if they exist. If they don't, it's up to the mod developer to tell you this somehow - usually in the description text. If it's not 100% clear, just assume it should be on all sides.

  • The easiest way to achieve this is to use manual mod installation and for the host to create a zip file of their installed mods and share it with players containing all of the mods they are using.

• In cases where mods mismatch, the game will give the error message "Game version mismatch"

  • If you see this message, make sure your server and client have exactly the same mods and mod versions. Ensure all mods loaded successfully by checking the logs - sometimes one of the mods fails to load on one side.

  • Check out the Troubleshooting page for more help with this issue.

Next, select your game type:

Max at Pugstorm maintains a guide for accessing and installing the modding SDK on mod.io guides.

Follow Max's guide up until you reach the "Creating new objects" header. You can keep reading from there if you'd like, but it may not make sense without further context. This site will walk through some more specific examples in the next few pages.

As Max is the only person with edit permissions, the mod.io guide can easily fall out of date. If something needs to be updated, discuss it in the #mod-creators channel on the official Core Keeper Discord.

Additional Steps

There are a few extra steps you need to take that Max's guide doesn't mention.

Disable Assembly Updater

In the Unity Hub, add the -disable-assembly-updater command line argument to your SDK project. If you don't do this, the Pug.Other.dll and Pug.ECS.Components.dll will not load correctly, meaning you will be missing some important script components.

These tutorials and guides are only capable of covering so much. If you want to become a real modder you will have to learn how to inspect other mods and the base game's files to implement your ideas.

Opening Mod Files

Core Keeper mods are compiled at runtime, so you can simply open a mod's files to view contained C# code. Download the mod from the mod.io website, open the zip file, and check out the Scripts directory. Or directly open the mod's directory on disk.

Open Source Mods

A number of mods have their sources posted on GitHub. Example: CoreLib. It's up to the individual mod developer to somehow provide links to their repositories, as mod.io does not have a "field" for communicating it.

Problems and Error Messages

I installed mods, but they don't seem to be doing anything

• #read-the-mods-documentation to find out how to access its features.

• Did you accidentally launch in "No Mods" mode?

• Check the tags on the mod.io page - is the mod not updated for this game version yet?

• #check-your-log-files-for-error-messages - sometimes mods can error in ways that don't get caught by Mod Reporter

• #ask-for-help-on-the-discord

• Reporting Bugs

Can't join my friend's multiplayer game

See below.

Game version mismatch when playing multiplayer

• Read the general multiplayer notes

• Ensure that all players have exactly the same mods installed

• If you're using mod.io interation, did it automatically update a mod on you? This means your installed mod version doesn't match the host's. One of you needs to update. Consider switching to manual mod installation to avoid the possibility of unexpected updates.

• #ask-for-help-on-the-discord

Help, my game is crashing

The most common cause of this is installing broken or outdated mods.

• #check-your-log-files-for-error-messages

• If you are playing from the Xbox Game Pass version, some mods can crash, even if they work on a normal PC install. Best solution if you want to play with these mods is to get the game on Steam.

• Uninstalling Mods - remove mods until the problem stops to track down what mod was causing the problem.

• #ask-for-help-on-the-discord

• Once you find out what mod in specific is the cause - Reporting Bugs

"Mods" menu on the title screen does not load (Failed to Fetch)

• #launch-the-game-in-no-mods-mode-then-unsubscribe-from-mods - remove mods until the problem stops to track down what mod was causing the problem.

• #ask-for-help-on-the-discord

Failed to create mod on mod.io: Api failed to complete the request

• Try uploading the mod manually.

Command give does not exist!

You did not properly install the chat commands mod, or something is preventing it from loading.

• Are you sure you've subscribed to Chat Commands and not just CoreLib.Commands?

• #manually-subscribe-to-all-of-a-mods-dependencies

• Try uninstalling the mod then installing it (and its dependencies) via another method.

• #ask-for-help-on-the-discord

Quantum Processor Error: Command <something> could not be found.

• Run chat commands in the game's chat window, not the debug Quantum Console. If you still want to use the quantum console, prefix your commands with the word chat so they are executed as chat commands.

Fix Approaches

This section contains troubleshooting approaches for the above problems to link to.

Install the Mod Reporter mod to check for loading errors

The Mod Reporter mod provides a GUI on the main menu to view the current state of your installed mods and see any issues easily.

Check your log files for error messages

Take a look at your game log files to see if any mods are reporting errors.

Read the Mod's Documentation

Check for directions on how to use the mod, known issues, etc. on the mod's page on mod.io.

Manually subscribe to all of a mod's dependencies

The game's mod.io integration often fails to download mod dependencies. Visit the mod's page on the mod.io website to see what they are and manually subscribe to each of them.

Ask for Help on the Discord

Join the Core Keeper discord and ask for help in the #modding-help channel. Make sure to:

• Include your log files! It will be the first thing people ask for if you don't provide it.

• Mention what mods you are using.

• Say what you expected to happen, and what actually happened. Screenshots help too.

• Say if you're playing in singleplayer, multiplayer, or a dedicated server, and if you're the host or the client.

Remember to communicate what you fixes have already tried. People are a lot more willing to help if you make it clear you've already put in some effort!

If you think you've found a bug with a mod, share it with the mod developer so it can be fixed!

Make sure you've followed the steps on the Troubleshooting page first to make sure it's actually a bug and not something specific to your setup!

Check the mod's page on mod.io to see if the developer has specified a specific place to report bugs. If you don't use the place they asked, there's a good chance they won't see your report.

Dedicated servers do not have mod.io integration, so mod files must be managed manually.

Manual File Management

1. Download the mods you want from the mod.io website using the Download File button

2. Open the game server installation folder and navigate to the mods folder: <server-install-folder>/CoreKeeperServer_Data/StreamingAssets/Mods/. You may need to create the Mods/ folder if it doesn't already exist.

3. Unzip each of the mod zips you downloaded inside the folder so that each mod is in its own subfolder.

   • The name of each mod folder does not matter as long as it is unique, but you probably want it to include the name of the mod for later reference.

   • Ensure that each mod subfolder has a ModManifest.json file.

4. Remember to read the general multiplayer notes if you haven't yet. Continue to the next section to help clients get their mods.

Distributing Mods to your Players

The easiest way to ensure that players have exactly the same mods as the server is to use manual mod installation. This means automatic updates don't cause problems with version mismatches.

1. Set up all of your mods on the server

2. Zip the server's mods directory

3. Have all players unsubscribe from every mod in the game's mod.io integration

4. Send your players the zip file and have them unzip it into their manual mod installation folder.

As you may have noticed when inspecting the ItemExample's SpawnItemOnStart script, in addition to spawning an item, it also prints "Spawn Sword1" to the game's debug logs. This section will explain how to view those logs.

Log Files

The Player.log file in your log files directory contains log messages from the active (or previous, if the game is currently closed) game session. Open it up and ensure you can find the "Spawn Sword1" message using your favorite text editor's Find utility.

Viewing Logs at Runtime

Use BepInEx to view logs

A recommend way to easily view logs in real time is using BepInEx console. It will open together with the game and you will be able to see all logs there.

Setup steps:

1. Download BepInEx 6.0.0-pre.2 from github (repo)

2. Open game installation directory, and extract downloaded archive into game folder.

3. Ensure you see CoreKeeper.exe and a folder on the same level called BepInEx

Note: BepInEx console has some limitations, specifically if you log from threads other than main (That often happens if you log from jobs) you won't see them. To see them you will have to watch Player.log

Use Text Editor to view logs

Viewing the logs in real time requires a text editor that can handle opening a file read-only without locking it. Consider Klogg or Notepad++.

Check out each tool's individual sub-page for more information.

See this message from the developers:

... there will not be any mod support on consoles at launch, and we will most likely never support mods on consoles in the same way we do on PC. The platform owners (Sony in this case) have strict requirements for all games that are released on their consoles, and there is no reasonable way to comply with them if players can modify the game to any meaningful extent. If there are mod features that you would like to have on consoles, feel free to post a suggestion in ⁠📋-feedback-suggestions to potentially have it added to the main game 🤠 -Herman on the Core Keeper discord

Discussions on the discord claim that attaching a traditional debugger is possible. But this guide has not been written yet! If you know how to do this, add it!

This section contains concepts that are utilized by multiple systems. They are here in one place to avoid duplicating information or having one section fall out of date.

Because of how the game is implemented and how modding API requires modders to define and register content, many concepts and ideas you have about modding from other games do not carry over well.

This game is implemented with ECS so most Object Oriented Programming principles do not apply. As you might have noticed when trying out the Item Example mod, if you want to make a tweaked copy of the Copper Sword, you can't just extend the base-game one and change some things. You must create a totally new copper sword from scratch and redefine all of its properties and behaviors on your version.

Hard Things to Mod

Things in this section are possible to mod, but are harder than they seem.

Texture Packs

Adding generic texture packs can be rather painful. The issue stems from the fact there is no single place you could replace the textures in. You will have to write specific code for each kind of object. Very specific texture altering mods however are relatively easy to create.

Prohibitively Difficult to Mod

Things in this section are technically possible to mod, but a massive pain.

World Generation

World generation in 1.0 is implemented with GPU shaders. Altering said shader atm is not possible. However custom world generation could theoretically be done after the fact.

If you are interested in this, here's a tip from game developer Fewes:

What you can likely do right now is use the new API functions PugWorld.RequestArea and PugWorld.RequestPoints, along with their callbacks PugWorld.onAreaRequestComplete and PugWorld.onPointsRequestComplete to sample the world generation shader and get data back which you can use however you want.

Bursted Code

A number of sections of the code are compiled with Burst for performance reasons, making modifying them a massive pain. More info here.

Basically Impossible to Mod

Limitations in the modding API make it basically impossible to modify these things. Have you found a way to modify them despite this? Contribute to the docs and explain how!

TODO - Put something here

There are definitely things that are impossible to mod but no one has written them down yet.

Visual Studio

Visual Studio is one of the IDE's you can use to develop mods. While basic in its features, it will allow you to make content. You probably already installed a copy of Visual Studio while installing Unity. If not, you can install one from the Unity Hub by modifying your installation.

A correctly configured Visual Studio project will give you intelligent suggestions and syntax checking as you write mod C# files.

To use it, in the Unity editor, open Edit > Preferences..., go to the External Tools heading, select Visual Studio in the "External Script Editor" dropdown.

Unity can automatically generate a Visual Studio solution file for you to work in. If you have issues with that, you can click Regenerate project files(In External Tools menu). This will create a .sln file in the root folder of your Unity project.

JetBrains Rider

JetBrains Rider is another IDE you can use. It is not free, however, students and some other people can get access to it for free. Rider features are much more advanced than Visual Studio, and it is recommended that if you can get access to it, you use it (IE you're a student).

Rider has smart auto-completions, code generation and a slew of suggestions on how to write your code better.

To use it, in the Unity editor, open Edit > Preferences..., go to the External Tools heading, select JetBrains Rider in the "External Script Editor" dropdown.

Due to the limited scope of the out-of-the-box functionality offered by the Mod SDK, a number of libraries have been created to assist with developing more complex mods. This section will cover some of those libraries and how to get started using them.

Asset Ripper will allow you to extract the base game's assets and load imitations of them in your modding SDK project.

After importing the assets you'll have to use the Missing Script Recovery Tool to be able to view components and their settings.

Usage Directions

1. Download AssetRipper from its releases page

2. Unzip the download and run AssetRipper.GUI.Free.exe

3. Follow the directions in the console window to access the GUI if it didn't already open in your browser automatically

4. Access File > Settings and ensure the following Options are checked, then click Save

   1. Skip StreamingAssets Folder - to avoid dumping mods

5. Use File > Open Folder to select your game install directory folder

6. Go to Export > Export All Files

7. Type or select (using the Select Folder button) a folder path to place the exported files at

8. Press the Export Unity Project button to start the export. The webpage displays no indication that anything is happening but the console window should be printing a bunch of stuff. Once the export is finished it will take you back to the Asset Ripper home page and the console log will end with "Export : Finished post-export"

9. Close the console window and browser tab

Exporting Audio Files

Audio Files are located in StreamingAssets\aa. If you want to export them, either un-check the "Skip StreamingAssets Folder" option, or directly open this subfolder of your game install directory: CoreKeeper_Data\StreamingAssets\aa

Navigating Exported Files

The ExportedProject folder contains all files we're interested in. Within this folder, you probably care about these subfolders:

• Textures can be found in Assets\Texture2D. Their respective sprites can be found in Assets\Sprite.

• Item and Entity prefabs can be found in Assets\PrefabInstance. These are usually not useful until they are imported into the Mod SDK project and have their missing scripts fixed.

• Sprite Assets can be found in Assets\MonoBehaviour, along with some other Scriptable Objects

• Audio files can be found in Assets\Audio (assuming you exported them)

As described in Max's guide on mod.io, the modding SDK comes with some examples packaged in a zip file. Let's take a look at some of them.

Extract the Examples

After your SDK project is set up, go to your file explorer and unzip the /Assets/Examples.zip file into the Assets folder such that you have a folder /Assets/Examples with a bunch of example subfolders.

Test the ItemExample Mod

In the Unity Editor, use a Project browser to navigate to the /Assets/Examples/ItemExample folder. Here you can see the files used by this example, which introduces a new weapon called "Sword1".

By inspecting SpawnItemOnStart.cs you can learn that the example is coded to create a dropped item instance of the custom item near spawn every time the game is loaded. This obviously is not what an end user would want, but it works well enough for our testing purposes.

To package the mod and try it out in-game, first open the Mod SDK tab. If you've lost it, you can open a new one via (Top bar) PugMod > Open Mod SDK Window.

Click the Mod Settings button to open the packaging UI, select ItemExample from the "Mod" dropdown, then click Install Mod. This will open a popup prompt and take at least a few seconds to execute. Once it's complete you'll see this popup:

Launch the game and notice that the main menu's Mods button says you have 1 mod loaded (assuming you don't currently have any other mods loaded). If you were to go into this mods menu, the ItemExample mod would not show up because it has been installed outside of the mod.io ecosystem. This is to be expected for locally installed mods.

If you want to remove this mod, go to your mod install directory and delete the ItemExample folder.

Load into a world and go near the Core - you'll find a Sword1 item on the ground.

CoreLib can be found on mod.io here:

Source code for CoreLib (and all submodules) is public on GitHub:

When creating a mod that depends on CoreLib, make sure to list every module dependency and the root CoreLib mod as a direct dependency of your mod. The game's mod.io integration sucks at downloading dependencies correctly, let alone transitive dependencies, and doing this helps ensure it correctly downloads everything.

Object Names and Tileset Ids

Unique string identifiers used to distinguish modded content.

These IDs must be unique across your mod AND all other mods. The easiest way to do that is to follow this naming pattern: ModName:ContentNameHere. This will reduce the possibility of cross-mod conflicts to pretty much zero.

Object IDs

Not to be confused with Object Names, Object IDs are integer identifiers used to refer to base-game items. You can find a list of all item IDs in your <game install directory>\CoreKeeper_Data\StreamingAssets\Conf\ID\ObjectID.json.

Note that mod content Object Names will be given IDs at runtime, but these IDs could change depending on what mods are installed, so never hardcode a modded Object ID.

Check these guides out if you are new to modding.

Do you know how to create something that isn't explained here? Please add it!

Follow the Item Guide

Follow the steps in the generic item guide first to define the other required properties of your item.

Armor

To make armor you need to:

• Set the ObjectType to armor type

• Add DurabilityAuthoring, ModEquipmentSkinAuthoring, GivesConditionsWhenEquipedAuthoring and LevelAuthoring component authorings and configure them correctly

Make a armor spite sheet. Examples of such sheets can be found in the Unity Editor. Now assign your texture to ModEquipmentSkinAuthoring (CoreLib feature). The component will automatically set everything up.

Follow the Item Guide

Follow the steps in the generic item guide first to define the other required properties of your item.

Creating Food

This guide has not been written yet! If you know how to do this, add it!

To a basic crafting recipe open Item Entity prefab and expand Required Objects To Craft. Increase the size of the list to the needed amount and then proceed to select each item.

To add a modded item as a crafting ingredient enter its Object Name in the field.

Follow the Item Guide

Follow the steps in the generic item guide first to define the other required properties of your item.

Creating Melee Weapons and Tools

To make a equipable item with use animation you need to:

• Set the ObjectType to tool or weapon type

• Add DurabilityAuthoring, GivesConditionsWhenEquipedAuthoring, CooldownAuthoring, WeaponDamageAuthoring and LevelAuthoring component authorings and configure them correctly

• Assign both icons to first sprite in item animation sheet.

Sprite sheets should be 120x120px and have 7 sprites showing item in different states. You can find such sheets for all base game weapons and tools by ripping game content via Asset Ripper.

Creating Ranged Weapons

To make a ranged weapon you mostly need to do the same as with any other weapon. Except for the fact that you will need a custom projectile entity added. To hook modded projectile entity use ModRangeWeaponAuthoring component instead of RangeWeaponAuthoring (CoreLib feature)

This guide has not been written yet! If you know how to do this, !

Tiles are special items whose appearance is defined by a tileset. Tiles are not entities and are grouped together by the Tilemap. Tiles cannot have any logic. Exception are tile-entities, which are entities with a tile as a visual

When placed they are displayed by a tile system instead of a graphical prefab. This is how one placeable (like walls, floors, bridges, fences, etc) can have many appearances depending on neighbor tiles.

To make custom tileset(s) create a ModTileset asset in your Unity project.

Layers is a reference to a tileset definition asset. CoreLib includes reference assets for three definition assets:

• tileset_main

  • Used by biome tilesets. Includes most tiletypes.

• tileset_base_building

  • Reduced tileset made specifically for player built things.

• tileset_extras

  • Contains various other tiles.

You can make your own Layer asset and assign it here. (Please note that assets provided with core lib are empty placeholders and are replaced at runtime.)

Tileset Texture is first texture field. It contains a reference texture for tileset, and contains a variety of different things. Look at vanilla textures to figure out what is what.

Adaptive Textures dict contains set of adaptive textures. These are important, as they store variations of your tile as it contacts other tiles. Usually these textures are autogenerated by the game developers of the game. Unfortunately, the modding community does not have info on how they are made, so you will need to reference some of existing ones to make yours.

After setting up the asset add following code to your ModObjectLoaded() method:

Now you can use ModTileAuthoring component to set the tileset and tile type in Editor.

Item are the simplest form of content you can add to the game. These range from things like wood to sword and armor.

Basic Item

To create an item, first create a new Prefab (Right click in the project tab, Create -> Prefab).

Open the prefab and add following components: ObjectAuthoring, InventoryItemAuthoring.

ObjectAuthoring

This component defines what this object is.

First field you must fill out is Object Name. Following the naming pattern: ModName:ItemName. Learn more about Object Names .

Next field you must set is the Object Type. This field defines the kind of item this is. For this example set it to Non Usable.

You may fill other fields on your own discretion.

InventoryItemAuthoring

This component defines information about the item for display in the inventory.

You must fill out fields Icon and Small Icon. These are the icons the player will see ingame. Both need to be 16x16 px.

Here you can also define item's crafting recipe, sell and buy values, and whether it can be stacked. Crafting recipes will be covered in another guide.

Item Localization

To set item's localized name create folder named Localization in your mod root folder. Now create a file in there called Localization.csv. This file will define all of your mod localization strings. Here you can add both English texts and other languages.

The file is encoded as Tab Separated Values (TSV). Initialize the file with the following content (Choose one of these two):

Add following content:

• Key: Items/ExampleMod:ExampleItem , English: Example Item

• Key: Items/ExampleMod:ExampleItemDesc, English: My first item.

Fill other fields on your own discretion. Please note that ExampleMod:ExampleItem here is your Object Name as set in ObjectAuthoring.

Trying Out Items In-Game

Once you have created your new item you will need to get it to test the mod.

Unfortunately, at the moment, the only way to get an item if it wasn't explicitly added to a workbench, drop table or other source is by using cheats like Chat Commands.

With Chat Commands you can acquire any item like so: /give ExampleMod:ExampleItem [optional amount]

Core Keeper is a server authoritative game. This means for an action to occur, the server must be aware of it and approve. When we write mods we must be able to create logic that allows for Client-Server communication to occur.

Ghost Components

Ghost component is one of the simplest ways to transfer data between Client and server. In its essence Ghost Component is just a normal ECS component that is synced over network.

To make a Ghost Component first Create IComponentData deriving ECS component:

public struct ExampleCD : IComponentData
{
    public int importantField;
    
    public float normalField;
}

To make this component a Ghost Component all you have to do is add a GhostComponent attribute to it. Additionally you must mark every field you want to be synced with GhostField attribute:

[GhostComponent]
public struct ExampleCD : IComponentData
{
    // This field will end up synced
    [GhostField] 
    public int importantField;
    
    // This field isn't marked, so it won't be synced
    public float normalField;
}

Making Ghost Components is just as easy as this. Now any data set to this component of the server will be automatically replicated to all clients. Refer to this guide to learn more

Remote Procedure Calls

Remote Procedure Calls (or RPC's) are a way to send information to the Server or clients in one-shot manner. They allow you to send arbitrary data or commands to the other side, be it requests or data

This example will focus on Client to Server communication, as that is the most common scenario, however you can send RPC from Server to Clients or even both ways

To make a RPC first add RPC command data definition:

public enum MyModCommandType : byte
{
    UNDEFINED,
    DO_VERY_IMPORTANT_THING,
    ANOTHER_IMPORTANT_TASK
    
    //etc
}

public struct MyModCommandRPC : IRpcCommand
{
    // This enum will define what kind of command this is
    public MyModCommandType commandType;
    
    // This is bundled request data.
    // This can be target entities, such as players
    // Or any other neccessary data
    public Entity entity0;
    public int value;
    
    // you can add more fields as needed
}

Now define two systems. One for Clients:

[UpdateInGroup(typeof(RunSimulationSystemGroup))]
[WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation)]
public partial class ClientModCommandSystem : PugSimulationSystemBase
{
    private NativeQueue<MyModCommandRPC> rpcQueue;
    private EntityArchetype rpcArchetype;

    protected override void OnCreate()
    {
        UpdatesInRunGroup();
        rpcQueue = new NativeQueue<MyModCommandRPC>(Allocator.Persistent);
        rpcArchetype = EntityManager.CreateArchetype(typeof(MyModCommandRPC), typeof(SendRpcCommandRequest));

        base.OnCreate();
    }

    #region Commands

    // This is the most important section
    // Here you can make send functions to have 
    // easy interface with the rest of your code
    public void DoVeryImportantThing(Entity target, int value)
    {
        rpcQueue.Enqueue(new MyModCommandRPC()
        {
            commandType = MyModCommandType.DO_VERY_IMPORTANT_THING,
            entity0 = target,
            value = value
        });
    }

    #endregion

    protected override void OnUpdate()
    {
        EntityCommandBuffer entityCommandBuffer = CreateCommandBuffer();
        while (rpcQueue.TryDequeue(out MyModCommandRPC component))
        {
            Entity e = entityCommandBuffer.CreateEntity(rpcArchetype);
            entityCommandBuffer.SetComponent(e, component);
        }
    }
}

And one for Server:

[UpdateInGroup(typeof(SimulationSystemGroup))]
[WorldSystemFilter(WorldSystemFilterFlags.ServerSimulation)]
public partial class ServerModCommandSystem : PugSimulationSystemBase
{
    protected override void OnUpdate()
    {
        var ecb = CreateCommandBuffer();

        Entities.ForEach((Entity rpcEntity, in MyModCommandRPC rpc, in ReceiveRpcCommandRequest req) =>
            {
                switch (rpc.commandType)
                {
                    case MyModCommandType.DO_VERY_IMPORTANT_THING:

                        // Do very important thing
                        // This code will be executed on the server
                        break;
                }
                ecb.DestroyEntity(rpcEntity);
            })
            .WithoutBurst()
            .Schedule();

        base.OnUpdate();
    }
}

Now to use these systems you just have to add this code in your IMod class:

public static ClientModCommandSystem clientSystem;

// You might already have this method
// if so, just add method body to your code
public void EarlyInit() 
{
    API.Client.OnWorldCreated += ClientWorldReady;
}

private static void ClientWorldReady()
{
    var world = API.Client.World;
    clientSystem = world.GetOrCreateSystemManaged<ClientModCommandSystem>();
}

Now you can use MyMod.clientSystem.DoVeryImportantThing() from anywhere in your code

Prediction

This guide has not been written yet! If you know how to do this, add it!

This section covers how to look at how content built into the base game was implemented. Use this knowledge to build your own content, understand where to hook the code to implement new behaviors, etc.

This guide has not been written yet! If you know how to do this, add it!

This guide has not been written yet! If you know how to do this, add it!

This guide talks about how to release a mod for end users to download on mod.io.

Existing Crafting buildings

One way to make your item obtainable is to add it to already existing workbench. Please be aware that each workbench can have AT MOST 18 slots. You cannot exceed this value. As such this approach isn't too scaleable.

To do so add the following code to your IMod class:

public const string MODNAME = "Example mod";
public const string VERSION = "1.0.0";

public static Logger Log = new Logger(MODNAME);

// You might already have this method
// if so, just add method body to your code
public void EarlyInit() 
{
    Log.LogInfo($"Mod version: {VERSION}");

    API.Authoring.OnObjectTypeAdded += EditWorkbench;

    Log.LogInfo($"{MODNAME} mod is loaded!");
}

private static void EditWorkbench(
    Entity entity, 
    GameObject authoring, 
    EntityManager entityManager
){
    ObjectID objectID = authoring.GetEntityObjectID();
    
    // This will determine what workbench we are targeting 
    // In this case it is Solarite Workbench
    if (objectID != ObjectID.SolariteWorkbench) return;
    
    // This is the item we will be adding
    var targetItem = "ExampleMod:ExampleItem"

    var canCraftBuffer = entityManager.GetBuffer<CanCraftObjectsBuffer>(entity);
    var item = API.Authoring.GetObjectID(targetItem);

    for (int i = 0; i < canCraftBuffer.Length; i++)
    {
        if (canCraftBuffer[i].objectID == item) return;
        if (canCraftBuffer[i].objectID != ObjectID.None) continue;
        
        Log.LogInfo($"Adding itemId {targetItem} to {objectID}");
        canCraftBuffer[i] = new CanCraftObjectsBuffer
        {
            objectID = item,
            amount = 1,
            entityAmountToConsume = 0
        };
        break;
    }
}

Please note that values returned by API.Authoring.GetObjectID() are not static and will change between game launches. Do not try to hardcode it or save it.

Adding a custom workbench

CoreLib.Entity submodule allows to easily add custom workbenches. All you have to do is define it via a special Scriptable Object.

Create a new Workbench definition by right clicking in project tab and selecting Create -> CoreLib -> New Workbench Definition

Workbench Definition fields

There are following fields to fill out:

• Item ID - the same as Object Name in Object Authoring, refer to this

• Icons - two sprites the player will see in inventory

• Asset Skin - An Asset skin for a workbench, defines how the workbench will look in the world

• Recipe - What is required to make the workbench

• Can Craft - Most important section. Here you can list everything players will be able to find in the workbench. You can only at most 18 slots!

• Related Workbenches - Any workbenches listed here (Modded via Workbench Definition) will be considered related and ingame you will see up and down arrows that allow switching between these.

• Titles - Text that will be displayed on top of workbench UI. Must be localized, refer to this

• Skin - Visual appearance of workbench UI

Ensure you have added localization texts for your workbench as described here

Create Sprite Asset Skin

To create Sprite Asset Skin open create menu and select Create -> 2D -> Sprite Asset Skin. Assign Target Asset property. The sprite you want to select is Workbench, and is bundled with CoreLib Package.

Assign main texture (Emmisive optionally) and three variants textures. Refer to original Sprite Asset for how these should look like.

Register Workbench Definitions

In order for CoreLib to find your mod workbenches add following code to your IMod class:

public void EarlyInit()
{
    CoreLibMod.LoadModules(typeof(EntityModule));
}

public void ModObjectLoaded(Object obj)
{
    if (obj == null) return;

    if (obj is WorkbenchDefinition workbenchDefinition)
    {
        EntityModule.AddModWorkbench(workbenchDefinition);
        return;
    }
}

You are done! Now you should see your workbench in CoreLib's Root Workbench, which can be crafted in player inventory.

This game is using a few tools that are important to understand while modding. Specifically these are DOTS, ECS, Jobs system and Burst

Unity concepts

Game Object

Game Object represents anything which can exist in a Scene. Please note that in Core Keeper only graphical prefabs and UI uses Game Objects at runtime. Players, placeables and enemies are NOT Game Objects, they are ECS Entities.

Mono Behaviour

Mono Behaviour is a class that can be attached to Game Objects. This component can give Game Objects behaviour.

Scriptable Object

A data container that you can use to save large amounts of data. Scriptable objects live outside of scenes and can be accessed by any code. In this game many lookup tables are stored as Scriptable Objects. Another notable Scriptable object are Sprite Assets.

DOTS

Data-Oriented Technology Stack (DOTS) is a feature of Unity, which is currently 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.

ECS

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

Resources:

Authoring

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.

Job Systems

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

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.

Ghosts / Ghost Authoring

Ghosts part of the multiplayer client/server communication system. A ghost is a networked object that the server simulates. Read more on the Unity docs.

Harmony

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.

Core Keeper already ships with a version of Harmony included. Any class with the [HarmonyPatch] annotation will be used as a patch.

Placeable Object

A placeable object is a item with a graphical prefab that can be placed into the world. Player can interact with said object, and it can do various things in the world.

Making the item

First, follow the steps in the generic item guide to define the other required properties of your entity.

Set the Object Type to Placeable Prefab.

Assigning components

Add following components:

• Placeable Object Authoring. This component allows to set various properties of the object. For example here you can make the object take up more than one tile. It also allows to set on what the object can be placed.

• Physics Shape. This will define the collision of the object

• Ghost Authoring Component. This is a component that controls your object ghost settings. Ghosts are a NetCode concept and really mean networked object. For most objects keep setting as defaults.

• Mineable Authoring

• Health Authoring. Set Health and Max Health to 2

• Health Regeneration Authoring

• Damage Reduction Authoring. Set Max Damage Per Hit to 1

• State Authoring

• Idle State Authoring

• Death State Authoring

• Took Damage State Authoring

• Animation Authoring

• Ignore Vertex Offsets

Optional components:

• Interactable Authoring. Enables your object to be interacted with. Ensure your graphical prefab has a Interactable Object component

• Rotation Authoring. Allows your object to be rotated

• Electricity Authoring. Allows your object to be powered and to power things

• Supports Pooling (CoreLib). Fixes issues you will encounter with Graphical Prefabs. HIGHLY recommended.

Making the graphical prefab

Graphical prefab is a Game Object that represents the entity on screen. It is important to understand that Graphical prefabs live only on clients, and are only responsible for visual appearance of an entity. They should never encode core behavior of an entity. The only exceptions to this are UI and inventory logic.

To make a graphical prefab create a new Prefab. On the root of it you need to place a EntityMonoBehaviour deriven class.

Then in the hierarchy create a GameObject called XScaler. Then inside of it create two GameObjects: SpriteObject, ShadowSprite and particleSpawnLocation. Optionally you can create GameObject Interactable, if your object will need to be interacted with. The resulting prefab should look like this:

On sprite GameObjects add a new component called SpriteObject. On the root component assign fields X Scaler, Shadow and set list Sprite Objects

Making the Sprite Asset

Now create two Sprite Assets (Create -> 2D -> Sprite Asset), one for main sprite, one for shadow. In the main one assign your main texture, and in the shadow one assign a shadow texture. Now set these Sprite Assets as the Asset field on each of the sprites.

If you want the object to be rotatable create 3 more static variations: up (When facing away from camera), side (Facing right) and side2 (Facing left). Assign their texture to relevant textures. To the root of the prefab add component Sprite Variation From Entity Direction. Assign both sprites.

Intractability

If you want the object to be interactable, on the Interactable GameObject a new component Interactable Object. Assign field Entity Mono, set sprites in Sprite Objects field (Except shadow) and wire up Unity Events On Use Actions and On Trigger Exit Actions to your root component methods. On the root component assign its field Interactable.

At the end the root of the prefab should look something like this:

Once you are done with the prefab, link it to the Object Authoring component.

Ensure CoreLib knows about the prefab

Also don't forget to add following code to ModObjectLoaded() method in order to fix issues caused by lack of pooling support by default: (CoreLib)

if (obj is not GameObject gameObject) return;

var entityMono = gameObject.GetComponent<EntityMonoBehaviour>();
if (entityMono != null)
{
    EntityModule.EnablePooling(gameObject);
}

Also ensure you have requested CoreLib to be loaded:

Make sure to call CoreLibMod.LoadModules(typeof(EntityModule)); to in your mod EarlyInit() function, before using the module. This will load the submodule.

Troubleshooting

Nothing appears (Can't find the item)

Firstly ensure that your mod is indeed is loading. For that make your IMod class log this, and look for logs

If you have Chat Commands installed try watching logs for a log from CoreLib in a format like this: objectName -> number. If you see your name in here, your object is ingame.

You might have some issues with the object name working from Chat Commands, to fix this either add a localized name or try using the number you see in that log message from CoreLib.

My entity seems to be still present after destruction

This is a known issue that devs could fix, but so far don't. Your only way to solve this is to use CoreLib's Entity module, and it's component SupportsPooling.

Ensure you have added this component to your entity prefab, and that the grahpical prefab has a unqiue root script that derives from EntityMonoBehaviour. (Note: this script MUST be custom, you CANNOT reuse existing scripts)

Lastly ensure you have done this

Example Cases

Fixing an imported MinecartEntity prefab by looking at the real one in game

This example talks about fixing an imported prefab ripped from the game using info in Unity Explorer.

1. Install Unity Explorer and relaunch the game

2. Open the "Object Explorer" window from the newly added top bar
3. Switch to "Object Search" mode and type MinecartEntity into the "Name contains:" search box, then press Search
4. Find the entry "MinecartEntity" (UnityEngine.GameObject) and double click it
5. In the "Components" column you can see a list of script components on the prefab. The default sorting order should be exactly the same as the sorting order of the scripts in the Unity editor.
6. Use NG Tools Missing Script Recovery to fix as many Perfect Matches as you can, then use the entries in the Components column to specify what the rest of the scripts are.

First, run Asset Ripper to export assets from the game.

Next, time to import them into your editor. Close the Unity editor first to keep it from wasting time hot refreshing as stuff is still being imported.

Go to the <export folder>\ExportedProject\Assets\ folder and copy only the following folders into your SDK project's assets folder. Copying anything not listed here risks bricking it.

• AnimationClip

• AnimatorController

• AnimatorOverrideController

• Font

• Material

• MonoBehaviour

• PrefabInstance

• Scenes

• Shader

• Sprite

• Texture2D

TODO what in the Resources directory is safe to bring in?

Reopen the Unity editor to allow it to rebuild its records, which will take a while.

Fix Imported Prefabs

You will probably want to access the Prefabs you have imported. However, on prefabs, all scripts will be broken. Use the NG Tools Missing Script Recovery to restore them. Follow this guide to install it and use it:

You'll also have to use Unity Explorer to inspect the prefabs in-game to figure out what things are when Missing Script Recovery doesn't have enough context to work.

This guide has not been written yet! If you know how to do this, !

After updates to the Modding SDK repository (usually announced on the Discord) you will probably have to update your local copy for mods to work on the latest version.

Unfortunately, arbitrary things breaking between releases seems to be a very common occurrence in Core Keeper modding. Instead of trying to update your modding SDK, it is best to clone and set up a new one from scratch every time an update is released.

Read the Modding SDK Changelog to see what things Pugstorm is confident have changed between versions!

Manual Mod SDK Update Guide

In the case you still want to manually update your mod SDK, follow these steps:

2. In your old Unity project delete following folders from the root of the project (It contains Assets folder): Packages, Assets/Graphics, Assets/ModSDK, Assets/Resources, Assets/Unity. If you have stored anything in there first move your files somewhere else.

3. Now proceed to copy all files from downloaded archive into your project folder (It contains Assets folder). Replace any existing files.

4. You're done. Try to open the project and see if it works. If you're getting errors you don't recognize, try cloning a fresh SDK instead.

This guide has not been written yet! If you know how to do this, !

Use the Mod SDK's Upload Mod utility.

TODO: How to upload files manually so the zips don't get an awful auto-generated name?

It sounds like you can zip the file produced by the mod SDK package task yourself and upload that, just make sure it contains the mod manifest file in the root of the zip file.

Game Install Directory

Steam

Xbox Desktop Application

Log Files

Save Files

Character Save Files

World Save Files

Mod Files

There are 2 locations where mod files are stored:

Auto-Downloaded via mod.io

This is where the game's mod.io integration downloads the mods you are subscribed to.

The folder contains:

• state.json , a file that encodes subscribed mods and their state.

• mods/, a folder which contains all downloaded mods. The folder names are mod.io IDs and are not human readable unless you lookup the IDs using the API. You can edit or delete files in this folder to remove or unsubscribe from mods.

Manually Added Mods

If you want to downloads mods manually, this is where you should put them. This is also where mod developers can find the mods packaged by the Unity editor during mod development.

Mod Configuration Files

You should have already created a mod.io account as part of . Now it's time to create a page for your mod. This is what end users will see when they are looking at your mod for the first time, so make it professional if you want to leave a good impression.

Read the mod.io Guidelines

Make sure that your mod complies with the guidelines described here:

Write a Description

Here is the bare minimum information you should describe in your mod page description:

• Directions on how to access and configure your mod's features.

  • What crafting bench are the items made in?

  • Where do you configure keybinds, and what are the defaults?

• How users should report bugs

  • A GitHub issue tracker? Contact you on discord? The mod.io comments section?

• If the mod is required by all users in multiplayer, just the client, or just the server

Here is other stuff to consider including:

• Screenshots of the mod in action. People like pictures!

• Known bugs (or a link to a bug tracker)

• Link to mod source repository (ex. GitHub)

• "Special Thanks" to list other people that helped your mod come to be

Apply Tags

Tags help categorize your mod and assist users with finding it. Some tags also have special functionality.

Game Version

Use the "Game Version" tags to indicate what versions your mod supports. If a user doesn't see the latest game version tag on your mod, they might think it's broken, and the game may report the mod as out of date to the user.

Type

Use the "Type" tags as categories for summarizing what kinds of content your mod adds and changes it makes. You can select as many or as few as you want.

Application Type

Access Type

"Access Type" tags control mod loading behavior. Only one should be selected at a time.

Dependencies

List any other mods or libraries that your mod depends on. The Mod SDK upload utility might have automatically filled this out for you.

Guide Deprecated

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

To start modding this game follow these steps. This guide assumes you know C# language and familiar with it's tools.

1. 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.

2. Follow BepInEx staring guide to setup your basic .NET project

3. Install DnSpy and setup source viewing

4. Make sure to use CoreLib in your mod. It will make adding custom content easier

5. 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.

Libraries

BepInEx

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

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

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

Tools

DnSpy

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

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

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

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.

Link: https://github.com/sinai-dev/UnityExplorer

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

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:

 [HarmonyPatch(typeof(Manager))]
 internal class ManagerPatch
 {   
     [HarmonyPatch("Awake")]
     [HarmonyPostfix]
     static void ManagerUpdatePatch(Manager __instance) {
         // Your code here, use __instance to get access to the Manager Instance
     }
}

Ensuring the game is in its main loop

Use this boolean to see if the game is in its main loop: Manager.currentSceneHandler.isInGame

Listening to Input

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:

RewiredKeybinds.AddKeybind("KeyBindUniqueId", "My Key Bind", KeyboardKeyCode.K);

Then in your MonoBehavior Update() method you can check the button:

public class UpdateMono : MonoBehaviour
{
    private Player player;

    private void Awake()
    {
        RewiredKeybinds.rewiredStart += OnRewiredStart;
    }

    private void OnRewiredStart()
    {
        player = ReInput.players.GetPlayer(0);
    }

    private void Update()
    {
        if (player != null)
        {
            if (player.GetButtonDown("KeyBindUniqueId"))
            {
                // Do something
            }
        }
    }
}

Changing a recipe

It is possible to change the recipe of an item by changing the requiredObjectsToCraft value.

foreach (var objectType in PugDatabase.objectsByType) {
    if (ot.Value.objectID == ObjectID.CopperMiningPick) { // ObjectID can be anything!
        List<CraftingObject> newList = new List<CraftingObject>(); // Create a new list of Crafting Objects

        CraftingObject newCO = new CraftingObject(); Create a new Crafting Object
        newCO.objectID = ObjectID.Wood; // Set the ObjectID to wood (can be anything)
        newCO.amount = 1; // Set the required amount
        newList.Add(newCO); // Add the requirement to the recipe

        ot.Value.requiredObjectsToCraft = newList; // Set the new recipe
    }
}

Running MonoBehaviour classes through IL2CPP

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.

public class Plugin : BasePlugin {
    public override void Load() {
        AddComponent<CustomMono>();
    }
}

public class CustomMono : MonoBehaviour {
    public CustomMono(IntPtr handle) : base(handle) { }

    private void Update() {
        CoreLib.Logger.LogInfo("Every update"); // This will run on every frame!
    }
}

Guide Deprecated

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

Quality of Love Update Warning

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.

Desert Update Warning

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.

Backup your project

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.

ThunderKit based Guide

With release of the mono build of the game it is now possible to use ThunderKit to setup our Unity project.

Step 1: Install Unity

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!

Step 2: Install Mono version of Core Keeper

Install Core Keeper mono version

Step 3: Setup the project

Create a new project

Create a new project from 2D Core template using Unity Hub. Wait until project is created and imported.

Install ThunderKit

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

Install Core Keeper Import Extensions

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.

Import game assemblies

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

Optional steps

At this point your project is functional. You can create custom assets and export them. Next steps are optional.

Add game assets to your project

Install Asset Ripper

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.

Extract Assets

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.

Move Assets

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.

Other Utilities

There might be missing script references. This tool will help with the missing script references.

Old (Legacy) Guide

Previous version of this guide can be found here

All guides in this section are outdated as the game is now Mono built.

Guide Deprecated

This guide was made for IL2CPP version of Core Keeper and no longer applies. Normal build of the game already uses mono

Steps

• 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

Step 1: AssetRipper

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.

Step 2: Preparing the folder for Unity

Set up project manifest

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:

{
  "dependencies": {
    "com.unity.2d.sprite": "https://github.com/kremnev8/ModifiedCoreKeeperPackages.git?path=/com.unity.2d.sprite@1.0.0",
    "com.unity.assetbundlebrowser": "1.7.0",
    "com.unity.entities": "https://github.com/kremnev8/ModifiedCoreKeeperPackages.git?path=/com.unity.entities@0.51.1-preview.21",
    "com.unity.ide.rider": "2.0.7",
    "com.unity.ide.visualstudio": "2.0.16",
    "com.unity.ide.vscode": "1.2.5",
    "com.unity.netcode": "0.51.1-preview.21",
    "com.unity.performance.profile-analyzer": "1.1.1",
    "com.unity.physics": "https://github.com/kremnev8/ModifiedCoreKeeperPackages.git?path=/com.unity.physics@0.51.1-preview.21",
    "com.unity.platforms": "0.10.0-preview.10",
    "com.unity.postprocessing": "3.2.1",
    "com.unity.profiling.core": "1.0.2",
    "com.unity.render-pipelines.universal": "12.1.8",
    "com.unity.rendering.hybrid": "0.51.1-preview.21",
    "com.unity.scriptablebuildpipeline": "https://github.com/kremnev8/ModifiedCoreKeeperPackages.git?path=/com.unity.scriptablebuildpipeline@1.19.2",
    "com.unity.shadergraph": "https://github.com/kremnev8/ModifiedCoreKeeperPackages.git?path=/com.unity.shadergraph@12.1.8",
    "com.unity.test-framework": "1.1.29",
    "com.unity.textmeshpro": "https://github.com/kremnev8/ModifiedCoreKeeperPackages.git?path=/com.unity.textmeshpro@3.0.6",
    "com.unity.ugui": "1.0.0",
    "com.unity.modules.ai": "1.0.0",
    "com.unity.modules.androidjni": "1.0.0",
    "com.unity.modules.animation": "1.0.0",
    "com.unity.modules.assetbundle": "1.0.0",
    "com.unity.modules.audio": "1.0.0",
    "com.unity.modules.cloth": "1.0.0",
    "com.unity.modules.director": "1.0.0",
    "com.unity.modules.imageconversion": "1.0.0",
    "com.unity.modules.imgui": "1.0.0",
    "com.unity.modules.jsonserialize": "1.0.0",
    "com.unity.modules.particlesystem": "1.0.0",
    "com.unity.modules.physics": "1.0.0",
    "com.unity.modules.physics2d": "1.0.0",
    "com.unity.modules.screencapture": "1.0.0",
    "com.unity.modules.terrain": "1.0.0",
    "com.unity.modules.terrainphysics": "1.0.0",
    "com.unity.modules.tilemap": "1.0.0",
    "com.unity.modules.ui": "1.0.0",
    "com.unity.modules.uielements": "1.0.0",
    "com.unity.modules.umbra": "1.0.0",
    "com.unity.modules.unityanalytics": "1.0.0",
    "com.unity.modules.unitywebrequest": "1.0.0",
    "com.unity.modules.unitywebrequestassetbundle": "1.0.0",
    "com.unity.modules.unitywebrequestaudio": "1.0.0",
    "com.unity.modules.unitywebrequesttexture": "1.0.0",
    "com.unity.modules.unitywebrequestwww": "1.0.0",
    "com.unity.modules.vehicles": "1.0.0",
    "com.unity.modules.video": "1.0.0",
    "com.unity.modules.vr": "1.0.0",
    "com.unity.modules.wind": "1.0.0",
    "com.unity.modules.xr": "1.0.0"
  }
}

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 game assemblies

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.

Delete project settings

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

Step 3: Installing The right Unity version.

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.

Step 4: Opening the project.

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.

Step 5: Adding Script Assemblies

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!

Step 6: Adding Editor Kit

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.

Step 7: Restart Unity

Restart Unity to fully get the project assembled.

Step 8: Profit

You should now be able to see the assets in the Unity editor.

Enjoy and make some cool stuff.

Utilities and helpful tools

There might be missing script references. This tool will help with the missing script references.

You can use DnSpy to view game code. To set this up follow these steps:

1. Using DnSpy navigate to the game's asseblies, which can be found in <game path>/CoreKeeper_Data/Managed folder

Using Cpp2IL

Guide Deprecated

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

Cpp2Il 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 Ghidra / IDA

Guide Deprecated

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

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.

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 Il2CppDumper, in your command line type:

Il2CppDumper.exe <executable-file> <global-metadata>

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:

1. From the Code Browser, choose File -> Parse C Source...

2. Create a new profile and add the generated C++ type header file. This is il2cpp.h.

3. Ensure the Parse Options are set exactly as follows:

   -D_GHIDRA_

4. Click Parse to Program and accept any warnings. This may take a long time to complete.

5. Open the Script Manager and add the output folder of the Il2CppDumper.

6. Click Refresh to make the script appear in Script Manager.

7. 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.

Elevated-access mods have increased access to resources outside the game like user files and internet.

Mods that require elevated access should explain why they need it on their mod.io page.

When installed, these mods have increased access to resources outside of the game such as user files and the internet. Because of this, we strongly recommend that players only install mods from reputable sources such as trusted mod creators.

To support this, we have added a new category to Mod.io called “Access Type” and, any mod that needs to run with elevated access will require the Access Type “Script (Elevated Access)”.

Users will also experience a warning pop-up that appears when they subscribe to elevated-access mods that reads:

“Caution: 'Elevated Access' mods have increased access to resources outside the game like user files and the internet. For the best experience, install only from reputable sources.”