Making Gamemodes from in‐game or and custom levels - monksilly/Custom-Gamemodes GitHub Wiki

This page is your guide to creating your very own custom gamemodes, mixing and matching levels from the game itself with levels you have created.

The Folder Structure

Before you write any JSON, you need to set up your gamemode's folder. Think of it as a dedicated space for all your gamemode's files.

YourChosenFolderName/
├── Assets/
│   ├── capsule_icon1.png     <-- This is your gamemode's small display image
│   ├── custom_levels         <-- This is your gamemode's custom AssetBundle, only used if you want to have custom levels
│   └── screen_icon1.png      <-- This is your gamemode's background(screen) art
└── config.json               <-- This is the main file that tells the mod all about your gamemode

YourChosenFolderName: You can name this folder anything you like! This is what you'll place inside the mod's Custom Gamemodes directory or better yet, in the plugins folder of BepInEx itself.
Assets/: This folder must be named Assets. All your image files (.png, .jpg, etc.) for icons go here, as-well as AssetBundles.
config.json: This file must be named config.json. It's the brain of your custom gamemode.

Understanding `config.json`

The config.json file is written in a format called JSON (JavaScript Object Notation). It's essentially a way to organize data using key-value pairs, similar to a dictionary.

Let's break down each part of the config.json file.

Basic Gamemode Information

These are the fundamental details about your gamemode, like its name, who made it, and what general rules it follows.

Field Name	Type	Required?	Description	Example Value(s)
`gamemodeName`	`string`	Yes	The name of your gamemode that players will see in the game's menus. Make it catchy!	`"Cats are cool"`
`author`	`string`	No	Your name, or the name of the creator. This is optional, so you can leave it out if you prefer to be anonymous.	`"Your Name"`
`category`	`string`	No	If you have more than one gamemodes, this field helps organize your gamemodes to their own category. Optional.	`"Powerline"`
`introText`	`string`	Yes	A short message that players will see when they start.	`"ASCEND"`
`isEndless`	`boolean`	Yes	Set to `true` if your gamemode doesn't have an end, or `false` if it has a clear end.	`false` (for a mode with a clear end), `true` (for endless)
`hasPerks`	`boolean`	Yes	Set to `true` if your gamemode allows players to use perks, or `false` if perks are disabled.	`true` (if perks are available), `false` (if perks are disabled)
`hasRevives`	`boolean`	Yes	Set to `true` if players can revive in your gamemode, or `false` if they cannot (e.g., permadeath).	`true` (if revives are available), `false` (if players can't revive)
`capsuleIcon`	`string`	Yes	The filename of the capsule image for your gamemode. This file must be in your `Assets/` folder.	`"capsule_icon1.png"` (assuming you have `YourChosenFolderName/Assets/capsule_icon1.png`)
`screenIcon`	`string`	Yes	The filename of the screen image for your gamemode's screen. This file must be in your `Assets/` folder.	`"screen_icon1.png"` (assuming you have `YourChosenFolderName/Assets/screen_icon1.png`)
`assetBundleFileName`	`string`	No	Only include this if you have custom levels in a Unity AssetBundle. This is the name of your asset bundle file (if your AssetBundle has a extension, e.g. `.unity3d`, it needs to be included in the field). If you're only using in-game levels, omit this field.	`"my_custom_levels_bundle"`
`gameType`	`string`	No	An internal identifier for the type of gamemode. Usually optional unless specified by advanced modding guides.	Valid options are: `"endless"`,`"standard"`,`"playlist"`,`"playlist-shuffle"`,`"single"`
`regions`	`list of objects`	Yes	This is where you define which levels your gamemode will use, organized into logical groups. This is crucial!	See "Organizing Your Levels" below.

Organizing Your Levels (`regions` and `subregions`)

This is the most important part for defining the actual gameplay content. You organize levels into regions, and then further into subregions within those regions.

A. Regions

A region is a broad grouping of levels. You can have multiple regions, like "Underworks", "Air Exchange" or "Custom Content".

Field Name	Type	Required?	Description	Example Value(s)
`regionName`	`string`	Yes	The display name for this group of levels.	`"Underworks"`
`subregions`	`list of objects`	Yes	A list of `subregions` within this larger region. This is where you pick the actual levels.	See "B. Subregions" below.

B. Subregions

A subregion is a more specific way to select levels. You must use either levelNameContains OR levels within a subregion to specify levels.

Using both at the same time is not supported yet.

Field Name	Type	Required?	Description	Example Value(s)
`subregionName`	`string`	Yes	The display name for this smaller group of levels.	`"Silos"`
`levelNameContains`	`string`	No	When to use: If you want to automatically include any level (in-game or from your custom asset bundle) whose name contains this specific text. This is great for broad categories. Leave out if: You are only listing specific `levels`.	`"Silos"` (will include "M1_Silos_Storage_07", "M1_Silos_Broken_01", etc.)
`levels`	`list of strings`	No	When to use: If you want to hand-pick a very specific list of levels. The game will only use the exact level names you list here. Leave out if: You are using `levelNameContains` to find levels.	`["M1_Silos_Storage_07", "M1_Silos_Broken_05"]` (exact level names)
`blacklist`	`list of strings`	No	When to use: If you're using `levelNameContains` but want to exclude a few specific levels that match the name but shouldn't be included. These levels will never be included in this subregion. Leave out if: You don't need to exclude any levels.	`["M1_Silos_01"]` (prevents this specific level from being chosen)

Minimal Custom Gamemode Example

This is the simplest possible config.json for a custom gamemode, using only the absolutely required fields and no custom asset bundles or advanced level selection. It will only use in-game levels.

{
  "gamemodeName": "Cat's mode",
  "introText": "meow all the way up",
  "isEndless": false,
  "hasPerks": true,
  "hasRevives": true,
  "capsuleIcon": "capsule_icon1.png",
  "screenIcon": "screen_icon1.png",
  "regions": [
    {
      "regionName": "Custom Underworks",
      "subregions": [
        {
          "subregionName": "The miss-n-match",
          "levels": [ "M1_Silos_Broken_01", "M1_Silos_Storage_14" ]
        }
      ]
    }
  ]
}

Examples of Level Selection

Here are different ways to select levels using levelNameContains, levels, and blacklist:

Example 1: Using `levelNameContains` (Automatic Inclusion)

This subregion will include any level (in-game or custom) that has "M1" in its name.

{
  "subregionName": "All M1 Levels",
  "levelNameContains": "M1"
}

Example 2: Using `levels` (Specific Hand-Picked Levels)

This subregion will only use the two exact levels specified.

{
  "subregionName": "Short Habitation Lab",
  "levels": [ "M3_Habitation_Lab_Lobby", "M3_Habitation_Lab_02" ]
}

Example 3: Using `levelNameContains` with `blacklist` (Filtering)

This subregion will include any level containing "M1", but specifically exclude "M1_Intro_01".

{
  "subregionName": "M1 No Intro",
  "levelNameContains": "M1",
  "blacklist": [ "M1_Intro_01" ]
}

Full Example: Custom Gamemode with Custom Levels

This example demonstrates a gamemode that uses both in-game levels and levels from a custom AssetBundle.

{
  "gamemodeName": "The Purritory",
  "author": "MeowMaster0w0",
  "category": "Meow's Custom's",
  "introText": "Purr n' Meow Right Neow~",
  "isEndless": false,
  "hasPerks": true,
  "hasRevives": true,
  "capsuleIcon": "meow_capsule.png",
  "screenIcon": "meow_screen.png",
  "assetBundleFileName": "meows_custom_levels",
  "gameType": "playlist-shuffle",
  "regions": [
    {
      "regionName": "The Starting Zone",
      "subregions": [
        {
          "subregionName": "Broke The silos, ooops",
          "levelNameContains": "Silos_Broken",
          "blacklist": [ "M1_Silos_Broken_05" ]
        },
        {
          "subregionName": "The Air is Exchanging",
          "levels": [ "M1_Silos_Air_01", "M1_Silos_Air_05" ]
        }
      ]
    },
    {
      "regionName": "Deep into the Purritory",
      "subregions": [
        {
          "subregionName": "My Meows",
          "levels": [ "Meow_House", "Meow_Nest", "Meow_Ending" ]
        },
        {
          "subregionName": "The Meowvelous Toys",
          "levelNameContains": "Meow_ToyHouse",
          "blacklist": [ "Meow_ToyHouse_Dev" ]
        }
      ]
    }
  ]
}