CollabUtils2 Home

Collab Utils 2 Documentation

The collab utils have a few entities that come in handy when making a collab, or any map with a similar structure, with hubs giving access to maps. But they also come with some extra behavior that requires you to follow a certain structure to make everything work as intended.

This doc will explain you how to set up that structure and how the entities work. Please read it before asking questions! Maybe the answers are in there. 😅

If anything is wrong or unclear, yell at Maddie (maddie480#4596 on the Celeste Discord) about that.

Setting up your mod as a collab

You will need a mod folder for this. Head to the Mod Structure page on the Everest wiki if you don't have that yet.

For the collab utils to fully function, you should organize your map .bins for it to be recognized as a collab, and to associate the lobbies to the maps that are in it.

Some features like speed berries don't require this, but if you plan to structure your mod like the Spring Collab (using mini hearts, lobbies, silver berries etc), you should definitely follow this.

As an example, we will set up the 2021 Season Collab, with 4 lobbies: Spring, Summer, Fall and Winter.

Pick a unique name for your collab, preferably with just letters and numbers (no spaces or symbols). For example, 2021SeasonCollab
Get an everest.yaml file (check the Mod Structure page if you don't know how to do that). Give your mod the Name you chose:

- Name: 2021SeasonCollab
  Version: 1.0.0
  Dependencies:
    - Name: Everest
      Version: 1.1375.0

Next to that everest.yaml, create a new file named CollabUtils2CollabID.txt containing just your collab name. This will tell the collab utils that this is a collab, so that it gets treated as such:

2021SeasonCollab

Create a Maps folder, then a folder named like your collab. So, Maps/2021SeasonCollab
This folder should have a folder named 0-Lobbies containing the lobbies, and one folder per lobby containing all maps that can be accessed from that lobby. For example:

Maps/
    2021SeasonCollab/
        0-Lobbies/
            1-Spring.bin
            2-Summer.bin
            3-Fall.bin
            4-Winter.bin
        1-Spring/
            map1.bin
        2-Summer/
            map2.bin
            map3.bin
        3-Fall/
            map4.bin
            map5.bin
        4-Winter/
            map6.bin

⬆️ Here, map 1 is in the Spring lobby, maps 2 and 3 in the Summer lobby, 4 and 5 in the Fall lobby, and 6 in the Winter lobby. Note that the lobby bins and the corresponding folders are named the same, and that's how the collab utils know they match.

In your English.txt, define your mod name:

modname_2021SeasonCollab= 2021 Season Collab
endscreen_collabname_2021SeasonCollab= 2021SC

⬆️ The first line defines your mod name in the updater (it's actually an Everest feature). The second line defines the collab name that will appear on the endscreen, along with the collab version, when the speedrun timer is enabled.

Your collab is now set up! When starting up the game, you should notice that all the lobbies are unlocked right away, and that only them are visible in chapter select.

Some extra features depending on folder structure

If you want a prologue, put it in the 0-Lobbies folder and name it 0-Prologue.bin. By doing so, players will have to complete it before unlocking lobbies.
If you want something similar to gyms (a map associated to a lobby that doesn't show up in that lobby's journal), you can create an extra 0-Gyms folder, and put bins that are named the same as the lobbies in it:

Maps/
    2021SeasonCollab/
        0-Gyms/
            1-Spring.bin
            2-Summer.bin
            3-Fall.bin
            4-Winter.bin
        0-Lobbies/
            1-Spring.bin
            2-Summer.bin
            3-Fall.bin
            4-Winter.bin

When in a lobby, session flags will be set for every map the player has beaten in this lobby. These flags are named CollabUtils2_MapCompleted_{binname}. In the example above, if you beat map3, the session flag CollabUtils2_MapCompleted_map3 will be set when you enter the 2-Summer lobby. For example, you can use this to make stylegrounds (dis)appear, or to trigger flag-controlled entities like flag switch gates (from Maddie's Helping Hand) or flag temple gates (from Pandora's Box), allowing you to open/close paths.

Map Metadata

Randomized session flags ("weather")

Collab Utils allow you to set randomized session flags in your map meta.yaml:

CollabUtilsRandomizedFlags:
    flag1: 0.2
    flag2: 0.5

With that setup, when entering the map, flag1 will have a 50% chance to be set, and flag2 will have a 20% chance to be set. Both cannot be set at the same time: in that example, that means there is a 30% chance no flag will be set.

Stickers on the journal

You can add stickers on the journal front page by adding the following to your lobby's meta.yaml:

Stickers:
  - Path: some/unique/path
    FinishedMaps:
      - foldername/mapname1
      - foldername/mapname2
    X: 150
    Y: 150
    Scale: 1.5 # optional
    Rotation: -20 # optional

This configuration will make the sticker at Graphics/Atlases/Stickers/some/unique/path.png appear on the journal front page at (150, 150) with 1.5x scale and -20 degrees rotation, if you finished foldername/mapname1 and foldername/mapname2.

Lazy Loading

Lazy Loading is useful for large collabs, to prevent the game from loading all of your mod's graphics, and instead only load what is required for the map you are playing.

You can set up Lazy Loading for your mod by creating a CollabUtils2LazyLoading.yaml file at the root of your mod, next to everest.yaml, that should look like this:

Enable: true
ExcludedPrefixes:
    Gui:
        - MyCollab/DoNotLazyLoad/
    Gameplay:
        - decals/DoNotLazyLoad/

The prefixes you list (relative to Graphics/Atlases/Gui and Graphics/Atlases/Gameplay) are sprites that should not be lazily loaded (for example, because they are used in the overworld).

By default, all Gameplay sprites are lazily loaded, and all Gui sprites except those located in areas/, emoji/ and CollabUtils2/skulls/ are lazily loaded (those are commonly used outside of maps). If you don't need to exclude any more sprites than that, you can omit ExcludedPrefixes entirely!

By doing that and restarting the game, the sprites that are set to be lazily loaded will not be loaded on startup anymore, speeding up the startup by a fair bit. Instead, textures will be loaded when you run into them in-game. This has a drawback though: loading the texture takes a bit of time, which can cause stutters during gameplay.

To help mitigate this, Collab Utils collects the list of textures it lazily loaded and saves them, so that next time you enter the map, they are loaded when you enter the map instead. No more stutter during gameplay! That list of textures is saved when you leave the map, in a file ending with .texturecache.txt in Mods/Cache/CollabUtils2.

But you probably don't want gameplay to be stuttery the first time players play each map! To prevent that, you should ship the .texturecache.txt files with your maps. You just need to move the files out of your Cache folder and to put them next to your map bins. You should play through the map in order to see every texture (including secrets) before doing that.

Note that if some textures are missing from the .texturecache.txt file you shipped with the map, Collab Utils will create the .texturecache.txt file in Mods/Cache/CollabUtils2 again, and you will find a warning in log.txt saying: Found X lazily loaded texture(s)! Saving them at [path]. This file only contains missing textures, so in order to add them to the .texturecache.txt file that ships with your mod, you should merge the files, rather than replacing the one shipping with your mod.

"Learn" tab in the chapter panel with gym teleports

You can add a second tab to your collab maps in the lobby, that lists the tech used in a map and allows the player to teleport to a room teaching it:

Here is how you can do this:

Making the gym

Make a separate bin for the gyms, putting it in the 0-Gyms folder: refer to above for more details.
Make one room per tech you want to teach, and put an Exit From Gym Trigger at the end of them. This brings up the chapter panel of the map the player was originally entering, similar to the Chapter Panel Trigger, and this allows them to either pick another tech, enter the map, or return to the lobby.
Put a Gym Marker in the room (this is an invisible entity), and change its settings to designate a difficulty and give the tech a name (only use letters, numbers and _ in that name!).

Setting up the chapter panel visuals

Put the image to display for the tech in the chapter panel in Graphics/Atlases/Checkpoints/{CollabName}/Gyms/{TechName}.png.
Add the name of the tech in your English.txt: {CollabName}_gym_{TechName}_name= The Tech Name

Listing tech used in each map

In order to make the "Learn" tab with the tech list show up in the chapter panel, just fill out the "Tech" option of the Chapter Panel Trigger. Separate the tech names with commas, and don't put spaces: wavedash,wallbounce.