CollabUtils2 Home

What is CollabUtils2?

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 wiki 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 max480 (max480#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.

1. Pick a unique name for your collab, preferably with just letters and numbers (no spaces or symbols). For example, 2021SeasonCollab
2. 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

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

4. Create a Maps folder, then a folder named like your collab. So, Maps/2021SeasonCollab
5. 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.

6. 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 max480's Helping Hand) or flag temple gates (from Pandora's Box), allowing you to open/close paths.

Map Metadata

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.

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 enable Lazy Loading for your mod by creating an empty CollabUtils2LazyLoading.txt file at the root of your mod, next to everest.yaml.

By doing that and restarting the game, gameplay sprites that are included in your mod 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.