Adding invitation maps

About Translations of this page

Recently there has been some international interest in the tool. I only speak English myself, but I would love to post instructions in multiple languages.

Feel free to submit translations of these instructions, I'll post them on the wiki alongside this one.

Adding invitation maps

In all of the following instructions, "Template" is just a placeholder for your own map names and such.

Setting up the stage folders

In your mod Resource folder, you'll need two new folders.

The first is Stage, and the second is CustomAudio. You can find templates for these in the Resource folder in this github.

Stage Folder

You make a folder for every stage inside of this one.

Inside that folder, you have 6 image files. These can be PNG or JPG and are caps sensitive.

All images are now optional, you can even leave out the floor and background if you really want.

The image can be of any size and will be resized appropriately to fit the width of the screen. By default it centers on the screen. Generally you should let the utility, and by extension Unity, handle scaling of the Background, Floor, and FloorUnder since it already gets affected by game resolution settings.

Background: This is exactly what it sounds like.

Floor: This is also exactly what it sounds like.

FloorUnder: This is for things like pillars under the floor and such, and also counterintuitively renders over the floor. The important thing to remember is that this image will not flatten out like the floor will during the battle phase.

Scratch1: This is the scratch that appears on the floor sometimes when damage dealt is 1 to 16.

Scratch2: This is the scratch that appears on the floor sometimes when a damage dealt is 17 to 30.

Scratch3: This is the scratch that appears on the floor sometimes when a damage dealt is over 30.

If not all scratches are included, lower scratches will not be included at all, while higher scratches will default to the highest one available.

CustomAudio Folder

This folder includes all of your custom BGMs and other custom audio, which currently support most formats except AAC. OGG is preferred over MP3, although both are supported.

Currently does not support subfolders, all of the files go directly in the CustomAudio folder.

Making a CustomMapHandler instance

Most CustomMapHandler commands are no longer static, and must be called through an instance with your Mod ID. The instance used throughout this document will be:

CustomMapHandler cmh = CustomMapHandler.GetCMU("TemplateModId");

Initializing the map

The following method must be called somewhere, and only once. Generally via a StageManager or Passive in the OnWaveStart() method.

cmh.InitCustomMap<TemplateMapManager>("Template");

So, for example:

public override void OnWaveStart() {
    cmh.InitCustomMap<TemplateMapManager>("Template");
}

Activating the map

You call the following method, generally in OnRoundStart() as part of the same class you put the Init in. It needs to be called every turn.

cmh.EnforceMap();

So, for example:

public override void OnRoundStart() {
    cmh.EnforceMap();
}

If you feed it a value it will switch to the stage specified, but this is an advanced function and is discussed in Map Related Methods

Adding the map to your stage

In the StageInfo.xml, you need to add the following line in the stage definition.

<MapInfo>Template</MapInfo>

So, for example:

<Stage id="1">
    <MapInfo>Template</MapInfo>
</Stage>

Setting up the MapManager

The following is an example MapManager. For maps with Abnormality text there's also CustomCreatureMapManager, which has more overrides and such.

public class TemplateMapManager : CustomMapManager {
    protected override string[] CustomBGMs {
        get {
            // Put the file name of your BGM here, you don't need the full path.
            return new string[] {"MyBGM.ogg"};
        }
    }
}

CustomBGMs is just a string with the name of your BGM. If you put multiple strings in it'll change between them based on emotion level. (Emotion level 0, 2, and 4 respectively).

Template.cs

For ease of reading, I'll include the entirety of Template.cs below:

using CustomMapUtility;

namespace Template {
    public class EnemyTeamStageManager_Template : EnemyTeamStageManager {
        CustomMapHandler cmh = CustomMapHandler.GetCMU("TemplateModId");
        public override void OnWaveStart() {
            // This method must be called somewhere, and only once. StageManager or Passive in the OnWaveStart() method is recommended.
            // You MUST have <MapInfo>Template</MapInfo> inside your StageInfo.xml file. (Replace Template with your stage name)
            
            // When you call this method, you supply the stage name and then your map manager.
            cmh.InitCustomMap<TemplateMapManager>("Template");
        }
        public override void OnRoundStart() {
            // Calling this will inform the game that the custom map should be the active one. Should be called in OnRoundStart() in a stage manager or passive.
            cmh.EnforceMap();
        }
    }

    public class TemplateMapManager : CustomMapManager {
        protected override string[] CustomBGMs {
            get {
                // Put the file name of your BGM here, you don't need the full path.
                return new string[] {"MyBGM.ogg"};
            }
        }
    }
}