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

Rules

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 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.
4. ⚠️ Do not implement malware, griefing, or denial of service tools in your mods
5. ⚠️ Do not use the Cassette Beasts multiplayer servers for games other than Cassette Beasts, or attempt to bypass cross-play constraints.
6. ⚠️ If you need to report a security issue you've found in netcode, please do so privately, either via email (preferred if you're decompiling the game) or the official support portal only. Do not post about it in public - this gives us the best chance to make sure the fix is tested before it goes out.

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: This tag is for a similar purpose to Save File Format Tag - to determine compatibility in network multiplayer games. See Best Practices for how to use this.

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.

Testing your mod

You can quickly test changes to your mod in the Godot editor, but you should always test it in the game for real before publishing it. See the Mod User Guide for instructions for installing your mod.

Due to the way mod loading works, any resources that were already loaded before the mod is loaded (e.g. autoload scripts) won't be replaced by the mod's packed resources. If your mod relies on changes to one of these resources, it will appear to work fine in the editor, but break when loaded into the real game.

Publishing your mod

The community has started using ModWorkshop to share mods.

Uploading a mod to ModWorkshop is pretty straightforward - you can log in with your Steam account, and then immediately start uploading stuff. It's usually best to package your mod in a zip file so that you can include a README with authorship information and some installation instructions.

Somewhere in the description of your mod you should mention the version number(s) of Cassette Beasts that have been tested with your mod. Updates to the game could break your mod - so it's important to be clear about which versions of the game you know it works with.

Make sure to read ModWorkshop's rules carefully before publishing your work there.

Sharing mod source code

It's common in modding to issue mods under an open source license (in fact, this is required under ModWorkshop's rules). Here are a few guidelines for this:

• When sharing the source code of your mod, include only the files that you have changed. DON'T add the whole decompiled project to a public repo.
• Use a license compatible with Cassette Beasts' proprietary code (i.e. not GPL).
• Make it clear that your license applies only to the portions of the files that you have changed, not to the whole files.

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.

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

Keep an eye on upcoming changes

Updates to the base game may unavoidably break mods from time to time. It's a good idea to keep an eye on upcoming changes to the game.

One way to do this is to install the Steam Daily branch (if you own the game on Steam). This branch contains a preview of the next hotfix branch--but not any new features.

When new features and content updates release it's advised to check your mods and update them, if necessary, as soon as you can.

Network Protocol Tag

A mod's Network Protocol Tag is used to determine which mods are compatible in multiplayer games. This should be a unique string that identifies your mod. Whenever you introduce a change to your mod that makes it incompatible with previous version in multiplayer sessions, you will need to change this string, so it's usually a good idea to append a version number to it.

Some mods can leave the Network Protocol Tag blank to remain compatible with the base version of the game. To decide whether a tag is required you'll need to understand what data the game shares over the network. If you're not certain, it's best to set a tag anyway!

Mods that require Network Protocol Tags:

• Any changes or additions to anything that affects the outcome of battle, including: monster species, moves, status effects, and items. Although items cannot be used in multiplayer battles at the moment, in a future update they will!
• Any additions to the player character's wardrobe, including: new colours, new clothes, hairs, etc.
• Any new game modes that are intended to be used in multiplayer, for example, 4-player battles, new raid types, etc.

Mods that do not require Network Protocol Tags:

• New locations.
• Purely cosmetic changes to existing resources or UI.

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.

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.

Modding discussions

The official Bytten Studio Discord server has a #modding channel for Cassette Beasts where mod development is discussed.