Code Mod Setup

Table of Contents

• Project setup
  • Prerequisites
• Module class
• Mod settings, session and save data

Project setup

Prerequisites

• Everest 🔗
• An IDE with C# language support, such as:
  • JetBrains Rider 🔗 (free for non-commercial use as of October 24th, 2024 🔗)
  • Visual Studio 🔗
  • Visual Studio Code 🔗 with the C# Dev Kit 🔗 extension
  • or other
• .NET 8.0 SDK or higher 🔗

Celeste is written in C# and runs on .NET Framework 4.5.2. Modern Everest versions convert Celeste to run on .NET 8.0, the modern successor to .NET Framework. Therefore, all new code mods start out as a C# class library targeting .NET 8.0.

Some old code mods don't target .NET Core 8.0. Mods made before Everest 5577 target .NET Core 7.0, and mods made before Everest 4465 target .NET Framework 4.5.2.
Mods targeting .NET Framework are called legacy mods, while those targeting .NET Core are called core mods. Core mods provide access to all modern C# features as well as a lot of other advantages.

Important

Everest uses semantic versioning 🔗.
This means that version numbers follow the format of MAJOR.MINOR.PATCH, and that changing the major version WILL break mods depending on your code mod.

So, if a mod depends on YourMod 1.3.5:

• installing YourMod 1.0.x won't work
• installing YourMod 1.3.0 won't work
• installing YourMod 1.3.5 will work (of course)
• installing YourMod 1.6.x will work
• installing YourMod 2.0.x won't work. The user will have to get YourMod 1.3.x or above instead.

The simplest way to set up a code mod is using the CelesteMod.Templates dotnet template 🔗.

Windows

First, you need to open your Mods folder in Windows Terminal. You can do that by i.e. opening Olympus, clicking on Manage under Installations, and then clicking on Browse. A File Explorer window should show up.

Right click the Mods folder and click Open in Terminal.

Note

If you don't have the Open In Terminal option, Shift+Right click the Mods folder and Open PowerShell window here instead.

If you have never made a code mod before, you need to install the template. Enter the below into Terminal and press Enter.

dotnet new install CelesteMod.Templates

Tip

Remember to run dotnet new update every now and then, to make sure your code mod template is up to date.

Then, to actually use the template, enter the following commands.
Remember to replace MyCelesteMod with your mod name.

md MyCelesteMod
cd MyCelesteMod
dotnet new celestemod

Tip

You can add parameters to the dotnet new celestemod command to adjust the template. They are documented in the template repository 🔗.

For example, dotnet new celestemod --Samples will give you some example entities; a normal entity, a solid, and a trigger. If you want to read up on those, take a look at the Custom Entities, Triggers and Stylegrounds wiki page!

You should get an output similar to this:

Close the Terminal window.
Then, open the MyCelesteMod folder that is inside Mods.

To open the mod project, double click the solution (.sln) file.

Linux/macOS

Open Terminal.

If you have never made a code mod before, you need to install the template. Enter the below into Terminal and press Enter.

dotnet new install CelesteMod.Templates

Tip

Remember to run dotnet new update every now and then, to make sure your code mod template is up to date.

Then, to actually use the template, navigate to your Celeste/Mods folder with cd, and enter the commands below.
Remember to replace MyCelesteMod with your mod name.

mkdir MyCelesteMod
cd MyCelesteMod
dotnet new celestemod

Tip

You can add parameters to the dotnet new celestemod command to adjust the template. They are documented in the template repository 🔗.

For example, dotnet new celestemod --Samples will give you some example entities; a normal entity, a solid, and a trigger. If you want to read up on those, take a look at the Custom Entities, Triggers and Stylegrounds wiki page!

Close the Terminal window.
Then, open the MyCelesteMod folder that is inside your Mods folder.

To open the mod project, open the folder with Visual Studio Code (make sure you have the C# Dev Kit extension installed) or open the solution (.sln) file with your IDE.

Code mod hot reloading

For convenience, Everest features a setting that automatically reloads code mods ingame after they are built. It can be enabled by opening modsettings-Everest.celeste in your Celeste/Saves folder and setting the option CodeReload_WIP to true.

Please note that this feature is a work in progress, so it may not behave correctly all the time. Restarting usually ensures that everything is loaded correctly.