Skip to content

Mod Files🔗

Every mod you create must have the following 2 files:

  • manifest.json, which contains metadata for your mod, and
  • mod_main.gd, which is the entrypoint for your mod to start everything it needs

manifest.json🔗

The manifest.json is a special metadata file that tells the ModLoader information about your mod. You can edit this file manually in Godot or in another editor of your choice, or by using the Mod Tool, which provides validation and some editing help for each field.

It includes a few relatively self-explanatory fields like the mod's name and description, as well as the namespace, which is usually the authors name, or the name of the group of people that maintain the mod. Both together create your final mod ID when attached together:
{namespace}-{name}, for example GodotModding-ExampleMod.
This is the identifier that the mod loader and other mods will use to manage your mod. It also includes multiple ways of setting dependencies, which you can learn more about in the using other mods guide.

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "name": "ModName",
    "namespace": "AuthorName",
    "version_number": "1.0.0",
    "description": "Mod description goes here",
    "website_url": "https://github.com/example/repo",
    "dependencies": [
        "Add IDs of other mods here, if your mod needs them to work"
    ],
    "extra": {
        "godot": {
            "authors": ["AuthorName"],
            "tags": ["tag1", "tag2"],
            "description_rich": "",
            "optional_dependencies": ["IDs your mod should load after if they are loaded"],
            "load_before": ["IDs your mod should load before"],
            "incompatibilities": [
                "Add IDs of other mods here, if your mod conflicts with them"
            ],
            "compatible_mod_loader_version": ["6.2.0"],
            "compatible_game_version": ["1.2.3"],
            "config_schema": {}
        }
    }
}
Tip

The manifest uses the structure of Thunderstore packages, which means you can use the same manifest.json for both your mod and your Thunderstore package.

mod_main.gd🔗

The mod_main.gd script is the entrypoint for your mod - that means it calls all the fancy ModLoaderMod functions to add script extensions, hooks, mod translations, and even act as a global class if need be.

See ModLoaderApi for more info on script extensions, translations and more.

The only thing required for the mod main to work is that it defines an _init() function for the mod loader to call and that it extends Node at the top. Technically you can even extend any type that inherits from Node, but it's rarely necessary.

The script below contains some boilerplate code to get you started. It is very similar to what you will get when creating a new mod with the Mod Tool. One thing it does here is define some path to your mod folder and extensions folder, just to avoid repeating the full path every time.

GDScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
extends Node


const GODOTMODDING_EXAMPLEMOD_DIR := "GodotModding-ExampleMod"
const GODOTMODDING_EXAMPLEMOD_LOG_NAME := "GodotModding-ExampleMod:Main"

var mod_dir_path := ""
var extensions_dir_path := ""
var translations_dir_path := ""

func _init() -> void:
    mod_dir_path = ModLoaderMod.get_unpacked_dir().path_join(GODOTMODDING_EXAMPLEMOD_DIR)
    # Add extensions
    install_script_extensions()
    # Add translations
    add_translations()


func install_script_extensions() -> void:
    extensions_dir_path = mod_dir_path.path_join("extensions")
    # ModLoaderMod.install_script_extension(extensions_dir_path.path_join(...))


func add_translations() -> void:
    translations_dir_path = mod_dir_path.path_join("translations")
    # ModLoaderMod.add_translation(translations_dir_path.path_join(...))


func _ready() -> void:
    ModLoaderLog.info("Ready!", GODOTMODDING_EXAMPLEMOD_LOG_NAME)
GDScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
extends Node


const GODOTMODDING_EXAMPLEMOD_DIR := "GodotModding-ExampleMod"
const GODOTMODDING_EXAMPLEMOD_LOG_NAME := "GodotModding-ExampleMod:Main"

var mod_dir_path := ""
var extensions_dir_path := ""
var translations_dir_path := ""

# Before v6.1.0
# func _init(modLoader = ModLoader) -> void:
func _init() -> void:
    mod_dir_path = ModLoaderMod.get_unpacked_dir().plus_file(GODOTMODDING_EXAMPLEMOD_DIR)
    # Add extensions
    install_script_extensions()
    # Add translations
    add_translations()


func install_script_extensions() -> void:
    extensions_dir_path = mod_dir_path.plus_file("extensions")
    # ModLoaderMod.install_script_extension(extensions_dir_path.plus_file(...))


func add_translations() -> void:
    translations_dir_path = mod_dir_path.plus_file("translations")
    # ModLoaderMod.add_translation(translations_dir_path.plus_file(...))


func _ready() -> void:
    ModLoaderLog.info("Ready!", GODOTMODDING_EXAMPLEMOD_LOG_NAME)
Note

The const variable you use to log (GODOTMODDING_EXAMPLEMOD_LOG_NAME in the example above) should always be unique to your own mod, in every file you use it. Otherwise, if another mod uses the same variable name (if they want to mod your mod for example), it will cause an error.

Tips & Best Practices🔗

GDScript has a style guide you can read here. Following the guide will help your code be more consistent, and make it easier to maintain and expand by other modders.

When naming files, use snake_case, and only use the characters A-z, 0-9, and _.

Note

ModLoader mods use hyphens (-) for mod names due to Thunderstore conventions, but they shouldn't be used for any other file names.