Custom Maps

Creating a Custom Map

Required Software

Mod Setup

Follow the Mod Setup Tutorial to begin setting up your mod.

Create the following folders inside your mod folder. The Maps folder should be next to the everest.yaml file:

Celeste
- Mods
  - MyExampleMod
    - Maps
      - MyName
        - MyExampleMod

⚠️ "MyExampleMod" and "MyName" must be replaced with the name of your mod and your name/nickname

Creating your map

Creating and editing your map happens in Lönn:link:.

⚠️ Every playable room must contain at least one Player Spawn Point entity.

Playtesting your map

If you have set up the folders for your map correctly (see Mod Setup), your map should be playable right away.

From the Chapter Selection Screen (where you can navigate between different chapters), press the Up and Down arrows to switch between modded map campaigns, or press Tab to open a search menu.

ℹ️ It is recommended to enable Debug Mode and use the ~DEBUG~ save file (available from the main menu with Debug Mode enabled) when testing your map.

Adding Custom Entities

Custom entites can be added to the game using "Helper" mods. Many helper mods are already available for use on GameBanana:link:. A full list of all currently registered custom entites can be found in the Custom Entity Catalog:link:.

To use a helper mod in your map, make sure you have it installed, reload Lönn, and any custom entities or triggers should automatically be loaded by the editor.

⚠️ Keep track of the helper mods you use and add them to your everest.yaml file. This will make sure that they are installed for anyone who wants to play your map:

- Name: MyExampleMod
  Version: 1.0.0
  Dependencies:
  - Name: Everest
    Version: 1.3471.0
  - Name: SomeOtherMod
    Version: 2.4.7

Changing the In-Game Text

When you start testing out your map, you may notice that the name is set to something like {MyName_MyMapName_MyMapFileName}. To change this and all of the other placeholders, we need a "Dialog File".

Dialog Files are all placed in a Dialog folder, and are text files named with the language they apply to. For English translations, that means creating a file called English.txt:

Celeste
- Mods
  - MyExampleMod
    - Dialog
      - English.txt

Within the dialog file, you can assign any text value to a "Dialog Key".
⚠️ Dialog Keys can only contain Alphanumeric characters (A-Z and 0-9) and underscores (_). Any other special characters, including spaces, should be replaced with underscores when used in a Dialog Key.

For example:

MyName/MyExampleMod becomes MyName_MyExampleMod
Words with spaces becomes Words_with_spaces

As a general rule, whenever there is text in-game surrounded by braces ({}) or square brackets ([]) it can be added (without the brackets) to the Dialog File as a Dialog Key.

For example, if your map name is displayed as {MyName_MyExampleMod_MyMapName} it can be customized like this:

MyName_MyExampleMod_MyMapName= My Map Name

⚠️ There cannot be any whitespace between the Dialog Key and the equals sign (=).

Adding Custom Graphics

The process for adding custom graphics to your map depends on what those graphics are for. Following are some common scenarios:

Mini Table of Contents

Click to expand

Decals and Stylegrounds
Entities
Overworld UI
Endscreens

Decals and Stylegrounds (Backgrounds)

If you have not already, add the following folders to your mod folder:

Celeste
- Mods
  - MyExampleMod
    - Graphics
      - Atlases
        - Gameplay

Within the Gameplay folder, custom decals should go in a decals folder, and stylegrounds should go in a bgs folder.

ℹ️ When adding any custom assets to your map, make sure to include your name/nickname and the name of your mod in the path. This helps prevent conflicts with other mods.
In this case, decals would go in decals/MyName/MyExampleMod, and stylegrounds in bgs/MyName/MyExampleMod, with "MyName" and "MyExampleMod" replaced with your name/nickname and the name of the mod.

Entities (Vanilla and Modded)

Entities can be given custom textures in a few ways, which are detailed in the Reskinning Entities Guide.

Overworld UI

Many parts of the map selection panel can be customized for your mod. These textures will all go in a Gui folder in the Atlases folder:

Celeste
- Mods
  - MyExampleMod
    - Graphics
      - Atlases
        - Gui

A full reference for the UI elements that can be customized is available in the UI Customization Guide.

Endscreens

Endscreens must be defined in your map's .meta.yaml file. Please see the Additional Metadata section for details.

Additional Metadata

Custom Endscreens, your map's position on the overworld mountain, as well as some other customization for your map, need to be defined in your map's metadata. However, adding fields for every bit of customization to Lönn would be cluttered and very difficult to use.

For these features, we can use a special metadata file that uses the YAML:link: format, similar to the everest.yaml file.

This file must be placed next to your map .bin file. It must have the same name, but with the .meta.yaml extension instead of .bin.

For example, a map file called MyAwesomeMap.bin would need a metadata file called MyAwesomeMap.meta.yaml.

A full list of the currently available options for the metadata file are available on the Map Metadata Page.
If you are looking to replicate a vanilla chapter's metadata, they are available in the .meta.yaml format on the Vanilla Metadata Reference.