This is a guide focused on mod development for Toziuha Night.

You’re authorised to use this decompiled project for the purposes of developing mods, however please be mindful of the rules in the Modding Rules.

Prerequisites

1. Get Toziuha Night: Order of the Alchemists in Steam or Itchio
2. Read through the Modding rules and make sure you agree to its terms.
3. Download Godot 3.6-stable. Later 3.x versions are untested, and 4.0 is incompatible.
4. Download the latest version of Godot RE Tools for your OS.
5. Read through the Mod User Guide so you’re familiar with how mods are used.

Decompiling Toziuha Night

1. Run Godot RE Tools
2. Go to RE Tools > Recover Project
3. Navigate to Toziuha Night’ install directory and open tn_oota.pck
4. GDRE will run for about 1 minute, and will likely report a "checksum error". These errors can be generally ignored.
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.  When it’s done you can close GDRE and open Godot 3.6.0.
7. In Godot’s project manager, import the project that GDRE created.

You can now run Toziuha Night project 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. Running the game from the editor can be helpful for testing your mods, but shouldn’t be considered ‘fully playable’.

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 ‘ModData (mod_data.gd)’ resource type and click Create.
4. Name the new resource ‘metadata.tres’

After the game has loaded all the mod pck's 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.

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

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.

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.

Testing your mod

To test your mod inside the Godot Engine editor, you will need to disable a few lines of code in the “res://src/scripts/mod_loader.gd” file to make it possible to load mods into the editor.

Exporting your mod

After you’ve created your mod you can export a pck to try out in the real game. An editor plugin is included in the decompiled project to do this, don't use the Godot export window 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

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

You can use the Toziuha Night Steam Workshop to share mods. Inside the game folder in its Steam version you can find an executable in EXE format to upload mods to the Steam Workshop.

Using the workshop utility will not update (even if the program says that the item was updated) unless the loaded mod file has changes.

You can also upload your mods to other platforms, as long as they are in PCK format and follow the folder structure defined above.

Sharing mod source code

It's common in modding to issue mods under an open source license. 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.

• 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

Toziuha Night 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.

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.

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.

Use cheats

The game has a command console built and cheats menu in that is automatically enabled when running from the editor and appears when you press "ESC" key. This can be useful for debugging your mods.

Running a script at startup

The ModData 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.