Common Mod Hooks

Table of Contents

• Loadout Menu registration methods in Data.gd
• Mod Initialization: modInit()
• The level_ready Signal
• Using prepareGameMode()
• Parsing YAML Files: parseUpgradesYaml() / parsePropertiesYaml()

---

Loadout Menu registration methods in Data.gd

We provide different methods to register mod content for displaying it in the loadout stage. Choose one of the methods fitting to your content and the item will be displayed in the loadout selection in the corresponding menu:

• registerDome(domeId:String)
• registerKeeper(keeperId:String)
• registerGameMode(gameModeId:String)
• registerGadget(gadgetId:String) (Primary Gadgets)
• registerRunModifier(runModifierId:String)
• registerPet(petId:String)
• registerSkin(keeperId:String, skinId:String)

If you want your mod content to be shown in the loadout screen, call the method from your mods modInit() like this:

func modInit():
   Data.registerGadget("your_id")

Mod Initialization: modInit()

The initialization of a mod can be complex, as it's not always clear when a mod has finished loading or when it's safe to execute certain code that interacts with Dome Keeper's code. A typical instance is the parsing of additional YAML files for your mod.

To simplify this process, we provide a function named modInit(). Your mod's mod_main.gd script must be in the mod_init group to use this function. To add your mod to this group, you need to include the following line in the script's _ready() function:

func _ready():
   add_to_group("mod_init")

You can then include the modInit() function and add your necessary codes:

func modInit():
	Data.parseUpgradesYaml("res://mods-unpacked/Your-ModName/yaml/upgrades.yaml")
	GameWorld.unlockElement(UPGRADE_NAME)

The level_ready Signal

Often, you want your mod to run code when a level is "ready" and loaded. StageManager offers a useful signal for this: level_ready. An example of its usage can look like this:

func modInit():
   StageManager.connect("level_ready", self, "testMod")

func testMod():
   Level.stage.applyGadget(UPGRADE_NAME)

Using prepareGameMode()

This function is particularly significant if you plan to modify anything related to game mode with your mod (or even if you want to add your own game mode!). When a new game starts, GameWorld.gd will call a method named prepareGameMode() on all nodes in the gamemodes-prepare group.

The method is invoked with two parameters: modeId:String, which is the game mode's "name/id", and levelStartData:LevelStartData, which contains numerous information needed for generating the level. Here is an example of its usage:

func _ready():
   add_to_group("gamemodes-prepare")

func prepareGameMode(modeId:String, levelStartData:LevelStartData):
   if modeId == "your-mods-game-mode-name":
      # change the loadout

Parsing YAML Files: parseUpgradesYaml() / parsePropertiesYaml()

A significant amount of information in Dome Keeper is stored in its original upgrades.yaml file in the top-level project folder. This includes game modes, keepers, domes, upgrades, and much more. Every property is defined in upgrades.yaml.

We've added a function to parse additional YAML files to make it easier for mod creators to modify the vanilla content or add new content. You can find this function in Data.gd.

To see how a new gadget can look, check the Hydra Launcher's yaml file.

You can then use this file's path as a parameter in the Data.parseUpgradesYaml(path:String) function:

func modInit():
	var pathToModYaml : String = ModLoaderMod.get_unpacked_dir() + MYMODNAME_MOD_DIR + "yaml/"
	Data.parseUpgradesYaml(pathToModYaml + "upgrades.yaml")

Dome Keeper will parse the file, add it to the gadgets, and even display the tech tree in-game!

Similarly, parsePropertiesYaml(path:String) is used to modify or add game properties. We recommend examining both vanilla YAML files to understand when and where to change or use these two files and their corresponding functions.

💡 You can read much more about parsing yaml files and upgrades here