Modding:Mod Developer Guide

This guide is intended for developers of mods. For more information about using Cassette Beasts mods, see the Mod User Guide.

Overview

The steps this guide will take you through are:

1. The prerequisite software
2. Decompiling Cassette Beasts to create an editable Godot project
3. Creating a mod .pck file from the Godot project
4. Best practices and tips

How to use Godot, and how to write GDScript are outside the scope of this guide. If you need help with Godot, GDQuest has a lot of great guides - just make sure you’re following guides for Godot 3.5, not 4.0.

Prerequisites

1. Own Cassette Beasts on Steam.
2. Download Godot 3.5.1. Later 3.x versions are untested, and 4.0 is incompatible.
3. Download the latest version of Godot RE Tools for your OS.
4. Read through the Mod User Guide so you’re familiar with how mods are used.

Decompiling Cassette Beasts

1. Run Godot RE Tools
2. Go to RE Tools > Recover Project
3. Navigate to Cassette Beasts’ install directory and open CassetteBeasts.pck
4. GDRE will run for about 5 minutes, and will likely report a lot of errors. These errors are for certain compressed textures it can’t decompile, and for our JSON-format pixel art animations. These errors can be generally ignored unless you’re intending to mod these particular resources.
5. When it prompts you for a destination folder, create a new folder, and make sure “Full Recovery” is selected. GDRE will extract all the game’s resources, scenes, and scripts into this folder. This will be your workspace for developing mods.
6. It’ll run for a few more minutes. When it’s done you can close GDRE and open Godot 3.5.1.
7. In Godot’s project manager, import the project that GDRE created.

You can now run Cassette Beasts from within the Godot editor, but note that the decompiled game can have some odd bugs and crashes that aren’t in the official builds. Also, the engine binary that Cassette Beasts ships with has some customisations - without which performance and stability are reduced. Running the game from the editor can be helpful for testing your mods, but shouldn’t be considered ‘fully playable’.

You’re authorised to use this decompiled project for the purposes of developing mods, however please be mindful of these rules:

1. ⚠️ Do not distribute Cassette Beasts in binary or in decompiled form - this includes the pck! If you want to keep your workspace under version control, then either use a private repository, or add only your modded files to the repository.
2. ⚠️ Do not distribute versions of Cassette Beasts built for other platforms (homebrew, mobile, etc.).
3. ⚠️ Do not implement malware in your mods.
4. ⚠️ Do not spoil the game for other players. Part of the experience of Cassette Beasts is the mystery of not knowing precisely what can occur in the game. Certain information may be revealed to you in the decompiled project that would spoil those secrets. We ask that you don’t reveal that information.

Creating your mods

Example

Bytten Studio has created two examples to show how mods are created. You can download and extract the following zip into your workspace: example_mods.zip

These files provide two mods:

1. Extra File Slots - adds an additional 7 save file slots to the file menu.
2. Example Mod - adds a new monster species as a replacement starter.

These examples show how multiple mods can be developed within the same workspace.

Mod metadata

The first step to creating your own mod is to set up its metadata file.

1. Create a folder for your mod in res://mods/, e.g. res://mods/your_mod_name/
2. In the FileSystem dock, right click your mod’s folder and choose ‘New Resource…’
3. Select the ‘ContentInfo (ContentInfo.gd)’ resource type and click Create.
4. Name the new resource ‘metadata.tres’

After the game has loaded all the mod pcks it has detected, it scans res://mods/ for files named metadata.tres.

1. Double-click your metadata.tres resource to edit it in the inspector.
2. Fill in the fields as below:

ID: A unique string identifying your mod. You can query the existence of another mod by calling DLC.has_mod() using that mod’s ID string as a parameter.

Name: A human-readable name for your mod. This displays on the title screen, below the game’s version number.

Version Code: An integer representing a machine-readable version number. Each time you release an update to your mod, you should increment this. This version code can also be queried alongside the ID with DLC.has_mod().

Version String: The human-readable version number of your mod, shown on the title screen.

Author: Who to attribute the mod to. This is also shown on the title screen.

Save File Format Tag & Save File Format Tag Version: You should provide this if save files created with your mod loaded cannot be loaded in the vanilla (modless) version of the game. If your mod doesn’t affect anything that would introduce an incompatibility with the vanilla game (e.g. if it’s purely cosmetic), you can leave this blank.

The save file format tag and version are used to determine whether a save file can be loaded with different versions of your mod. See best practices for how to update these values when releasing updates to your mod.

Network Protocol Tag: Cassette Beasts doesn’t have network multiplayer at the moment, but one day it might - or it could be modded in! This tag is for a similar purpose to Save File Format Tag - to determine compatibility in network multiplayer games. If your mod is purely cosmetic and doesn’t affect gameplay, you can leave this blank. Otherwise you need to provide a unique string here. Please be forward thinking and define a tag for your mod even though there’s no multiplayer feature at the moment!

There is no ‘Network Protocol Tag Version’ because there can be no backwards compatibility. If you break network compatibility with previous versions of your mod, you need to choose a new unique tag.

Modified Files & Modified Dirs: This is how you declare to the mod export tool which files and directories to include in your mod pck. All files within your mod’s directory in res://mods/ are automatically included, so you only need to list files and directories added / replaced outside of that directory.

The metadata for Bytten Studio’s Example Mod looks like this:

Exporting your mod

After you’ve created your mod and tested it in the editor, you can export a pck to try out in the real game. An editor plugin is included in the decompiled project to do this - we do not use Godot’s normal project/pck/zip export tool for mods.

1. Make sure the paths to all the resources you’ve added/modified can be found either in the Modified Files and Modified Dirs paths in your mod’s metadata.tres file, or are located inside your mod’s directory. The pck that the export tool creates will contain only the resources in these paths.
2. Project > Tools > Export Mod… (not Project > Export…)
3. It’ll prompt you to open a metadata.tres file. Navigate to your mod’s directory and open metadata.tres.
4. Next it’ll prompt you to save a .pck file. Navigate to some directory where you would like to save your pck and click OK.
5. It will export your mod’s resources as a pck. This is very quick - almost instant - because it contains only the contents of your mod’s directory and the resources pointed to by your Modified Files and Modified Dirs metadata.

Now you can install your mod as per the Mod User Guide and check it works in the real game.

Running a script at startup

The ContentInfo class contains a stub function init_content. If you need to run some task after your mod has been loaded - as the game starts up - this is a good location to do it. You will need to extend the ContentInfo class with your own script, and attach that to your mod’s metadata.tres file.

Note that this function is called after all mods have been loaded by load_resource_pack, however, other mods’ `init_content` functions may not have been called yet.

Modding the mod export tool

If the mod export tool plugin doesn’t include files that your mod requires (for example, project.godot / project.binary), it’s very easy to modify the export tool itself: res://addons/export_mod/plugin.gd

However, this is not recommended, and 99% of mods will not need to do this anyway.

Best Practices

ProjectSettings, autoloads, and class_name

Because of the way project.godot changes overwrite each other, it’s only possible for one mod at a time to change it. If a player tries to load multiple mods that replace project.godot they will conflict, and won’t work properly.

Therefore the provided mod export tool does not pack project.godot changes.

If your mod needs to make changes to project settings, it should do so at runtime, from a script.

Autoloads, and class_name (in GDScript), rely on the path to the script being stored in the project.godot file. Therefore if you add autoloads or use class_name your mod will break when it is loaded into the game.

Replace as few of the base game's resources as possible

Cassette Beasts uses ProjectSettings.load_resource_pack to load your mod as it starts up. Unfortunately it doesn’t (and can’t) know if two mods replace the same resource before irreversibly loading them both. The more of the base game’s resources you replace, the more likely it is that your mod will conflict with other mods.

You should prefer to add new resources rather than replace existing ones where you can. Your mod’s directory in res://mods/ is the safest place for them.

New monster species don’t need bestiary indexes

A bestiary index is the number a monster species is given in the game’s bestiary. If the bestiary index is -1, the species’ number in game is given as ‘#???’.

The game internally identifies monster species by filename rather than by number. This means mods don’t need to allocate ranges of bestiary indexes to different mod creators. As long as each mod’s new species has a distinct filename and uses -1 as a bestiary index, you can be sure of your mod’s compatibility with other mods.

Save data compatibility

Try to maintain backwards compatibility with save files whenever you can!

If save data created with your mod can’t be loaded in the vanilla version of the game, then each time you release an update to your mod you need to consider:

1. With the new version of the mod, can the game load save data created with the old version of the mod (backwards compatibility)?
2. Can games with old versions of the mod load save data created with the new version of the mod (forwards compatibility)?

If your mod is both backwards- and forwards-compatible you don’t need to change your mod’s Save File Format Tag or Version.

If your mod is backwards-compatible but not forwards-compatible you should increase the Save File Format Tag Version but leave the tag alone.

If your mod is not backwards-compatible you need to choose a new Save File Format Tag.

Tips

Custom User Dir

If your mod doesn’t rely on any changes in project.godot, you can change the ‘user directory’ in project settings to isolate settings and save files you use for debugging in the editor from the ones you use when playing the game for real. This setting can be found in Project > Settings > Application > Config > Custom User Dir Name.

Testing battle system changes

There are a number of scenes already set up to help you test battle system changes quickly:

CustomBattle: res://tools/custom_battle/CustomBattle.tscn

Although it has some limitations, this will let you quickly set up and test a battle with any monster species and any moves. For new battle backgrounds to show up in here, they must be registered in res://battle/backgrounds/battle_backgrounds.tres.

MonsterPreview: res://tools/monster_preview/MonsterPreview.tscn

A little tool for previewing how monster battle sprites look in-game, with various settings for animations, coatings, and fusions. The greenscreen backgrounds can be useful for taking screenshots of fusions where you can easily key out the background.

BattleVfxPreview: res://tools/battle_vfx_preview/BattleVfxPreview.tscn

A more specialised tool for previewing VFX. Useful if you’re adding moves with new animations.

Use cheats

The game has a command console built in that is automatically enabled when running from the editor. This can be useful for debugging your mods. See Cheats for more information about how to use this.