Skip to content

TEMP_PR33

Jump to bottom
KANAjetzt edited this page Jun 12, 2023 · 1 revision

This page is temporary. It contains content updates from PR #33 by Ste/Qubus0, via:

https://github.com/GodotModding/godot-mod-loader/blob/b90ed1d016689ea139da72870f4c393a1a84b8bf/README.md

Once this content has been integrated into the wiki, this temporary page can be deleted (Edit > Delete).

A general purpose mod-loader for GDScript-based Godot Games.

Table of Contents

For Mod Users

Mod Loader Setup

If the game you want to mod does not natively use this ModLoader, you will have to complete two steps to set it up:

  1. Place the /addons folder from the ModLoader next to the executable of the game you want to mod.
  2. set this flag --script addons/mod_loader/mod_loader_setup.gd
    • Steam: right-click the game in the game list > press properties > enter in startup options
    • Godot: Project Settings > press Editor > enter in Main Run Args
    • Other: Search for "set launch (or command line) parameters [your platform]"

If the game window shows (Modded) in the title, setup was successful. This renaming of the game will also move all logs, saves and other game data to a folder inside app_userdata/<game name> (Modded). If the game had settings (like keybindings) in that folder, don't forget to copy them over.

In more detail:

The mod loader comes with a little helper script to properly install itself without having to recompile a game's source. This works by using Godot's functionality to override project settings with a file named override.cfg. Since the override also saves all other Project settings, it's important to recreate this file after the game is updated (This can be done with one button press in the mod selection screen).

Use this flag to skip the mod selection screen (or tick the box in the selection screen) --skip-mod-selection

Holding ALT during startup will invert the behavior: skip selection screen without the skip flag and show it with the skip flag

Installing mods

Mods come in the form of ZIP files. To use them, simply put your mod ZIP in a folder named "mods" in your game's main folder (ie. the place where the game EXE is -- see Folder locations for more info).

You should not unzip the mod. If you do, it won't work.

Security Basics

When downloading a mod, always keep the basics in mind:

  1. Always confirm your sources are trustworthy
    • Games usually have a modding channel on their official Discord.
    • Be very cautious when downloading mods from Discord. Even a friend's account can be hacked. If it sounds sketchy, it probably is.
  2. Check the mod sources yourself, or have a trusted community member check it. Potentially malicious mods may include:
    • Random executables (.exe files)
    • A mod using the OS class (has access to your computer system)
    • Something that's not an asset
    • Something that's not game code (not .gd or .tres)
  3. If unsure, better ask the community!
  4. If in doubt, don't download it.

Legitimate sources include the Steam Workshop and Thunderstore, but note that even those can contain malicious mods.

For Mod Developers

Development Setup

Prerequisites

Running the game from the Godot editor

When opening the project for the first time:

  • select import (on the right) and navigate to the destination folder you previously selected. Select the project.godot file and press open and edit.
    • To run the game, press the Play triangle button in the top right.

Developing a Mod

First off, if the game you want to mod does not have this ModLoader installed already, consider bringing it up to the developer for them to consider. Second off, there are some limitations if that's the case. There is no way to modify autoload (singleton) behavior, since the load order of them can't be overridden due to some strange behavior in Godot's way of overriding them.

To get started, download the starterkit mod fitting your game from this repository Starter Kit Mods [link pending] place it inside the mods-unpacked directory alongside the game executable (see Folder locations)

Note: Due to packs overriding stuff when loaded in the editor, you will have to unzip and place all mods that you want to have active during development (dependencies and so on) in /mods-unpacked

For Game Developers

To integrate the ModLoader into a game, register the ModLoader script as an autoload. All helper classes will automatically be set as global classes by Godot. See Godot Project Setup for more info.

If the ModLoader is integrated into the source, the --script flag to use and set up the mod loader will not be necessary. This is the most optimal way to use it. To do that, you only have to add the ModLoader as the first autoload.

For Mod Loader Developers

Download the files from the repo and add them to your project, as per the guide in See Godot Project Setup.

Alternatively, you can clone the repo and create a symlink to it. To do this, and symbolically link (symlink) the addons/mod_loader directory into the addons folder of any Godot project. Or you can symlink the addons folder besides any Godot game executable.

In these examples, <MOD_LOADER_PATH> is the path to your cloned repo's addons/mod_loader directory, while <ADDONS_PATH> is the path to the addons directory in your project.

Windows:

Note: Symlinks can have some issues with Godot on Windows.

mklink \d <MOD_LOADER_PATH> <ADDONS_PATH>

Mac/Linux:

ln -s <MOD_LOADER_PATH> <ADDONS_PATH>

This way you can edit the mod loader any game (even multiple at once) while source control and all the other documents can stay in the directory you cloned them into.

Miscellaneous

Folder locations

Game Executable:

Right-click the game in Steam > Click Manage > Browse Local Files. This will open the game's folder.

Note: For macOS, the actual executable is in /Contents/MacOS within that folder, but you are still at the right place. Only the override needs to be placed there, everything else goes right here.

User Data:

  • Windows: %appdata%\Godot\app_userdata\<game name>
  • Linux: ~/.local/share/godot/app_userdata/<game name>
  • Mac: ~/Library/Application Support/Godot/app_userdata/<game name>

Note:

  • Opening the Godot Project with the override.cfg file present can lead to Godot setting all those values in the project settings, especially in 3.4.
  • This is a bug (https://github.com/godotengine/godot/issues/30912). Opening the project after that will not revert those changes. It is the quickest way to set up the loader, but can also lead to confusion.

Clone this wiki locally