Mod Structure

Editor

When developing mods in Godot, create a folder named mods-unpacked and add your mods there.

Mod folder names must follow the convention of {AuthorName}-{ModName}:

res://
└───mods-unpacked
    └───Author-ModName
        ├───mod_main.gd
        └───manifest.json

See Mod Files for info on what those files do.

If you have any dependencies, unzip them and add them to res://mods-unpacked.

Note that a bug in the Godot editor prevents using zipped and unpacked mods at the same time (see ZIPs in the Editor below).

ZIPs

Mod ZIPs should have the structure shown below. The name of the ZIP is arbitrary.

ZIPs are added to a folder named mods in the root.

yourmod.zip
├───.import
└───mods-unpacked
    └───Author-ModName
        ├───mod_main.gd
        └───manifest.json

ZIPs in the Editor

Godot has a bug that, in short, means you can't use both unpacked mods (in res://mods-unpacked) and zipped mods (in res://mods). If you need to use a mod as a dependency, please unzip it and add it to your project.

You can still use mod ZIPs in the editor, eg. if you want to test your zipped mod. They will load as expected, but nothing from res://mods-unpacked will be loaded either.

Custom Assets (.import)

If your mod includes custom assets, such as PNGs and CSVs, these files should be included in your mod ZIP. Like in the editor, these go in a top-level directory called .import.

Your mod ZIP's .import folder should only include your custom assets. It should not include any vanilla assets.

For ease of use, it's highly recommended that you prefix all custom assets with your modname_*, eg explosionsmod_weapon1.png. This makes it much easier to find your custom assets in .import.

Custom assets can also be identified by sorting by date.

To clean up unused files, it's helpful to delete everything in .import that's not vanilla, then run the game again, which will re-create only the files that are actually used.

Next: Mod Files