Modding

Get help: wick.itch.io/lancer-tactics or Discord

Mod Types

Lancer Tactics distinguishes between three mod types: Asset Packs, Content Packs and "Substantial" mods. Asset and Content packs' changes are standardized and reversible, so can be enabled and disabled without restarting the game. Substantial mods change the base scripts or scenes the rest of the game relies on so require a restart.

• Asset Pack: just images and tres files. Doesn't even have a mod_main.gd; just a json manifest and images in various places to get picked up by the appropriate resources. These can be required by combats/modules and they'll be treated as safe since not having scripts makes them risk-free. We allow tres files to be in asset packs as long as they do not contain any inline scripts.
  • Mods that do not contain any .gd files (including mod_main.gd) will be treated as Asset Packs.

• Content Pack: can have scripts and a mod_main.gd to do non-standard things, but are responsible for making sure anything off-standard they do is reversible without a restart. Since these allow arbitrary code execution, they will prompt additional warnings to the player before they are enabled.
  • Mods that contain .gd files and are marked as requires_restart as "false" in their manifest will be treated as Content Packs.

• Substantial Mod: as above, but the changes are not cleanly reversible so require a restart to turn off or on.
  • Mods that contain .gd files and are marked as requires_restart as "true" in their manifest will be treated as Substantial Mods.

Mod Loader

Lancer Tactics is using the Godot Mod Loader addon, but has made some changes to it:

Implicit Overrides

Instead of having to manually declare each asset you want to override in code (via an overwrites.gd that the Mod Tools would generate and put into an extensions/ or overwrites/ sub-directory), assets and resources are overridden implicitly by matching file paths and names from a mod's res/ directory. See the "replacing resources" section below for details. This should allow people to make texture asset pack mods fully outside the Godot editor by downloading a template, dropping images into a folder, and zipping it up.

Hooks and class_name scripts

Unfortunately, it ended up not being feasible to support their script Hook system, which means it's not possible to change class_name scripts (or is unreliable to do so). Hooks were designed to work around a bug in Godot that has been unaddressed since 4.3 and do some crazy preprocessing of scripts that involves decompiling them, editing names of functions, and swapping in the copies. For the time being, we decided to instead convert the most likely targets of mods (UnitCondition, UnitTile, UnitAction, etc) into autoloads so they can be accessed by normal script Extensions instead. This will provide better backwards compatibility for mods once the bug is addressed than having to go back and tear out all the Hook code.

TL;DR: You are NOT able to currently extend a script with a class_name. If you want to make a mod that extends a class_name script and it looks like it could be an Autoload, let me know and I'll see if I can convert it!

The engine bug necessitating hooks: github.com/godotengine/godot/issues/83542

A possible fix to the godot engine that'll solve all this: github.com/godotengine/godot/pull/116556

Formatting and Paths

Additionally, we've made some path and formatting tweaks for styling and ease of use:

• We're using res://unpacked/ instead of res://mods-unpacked/ for the directory in the godot project that mods are unpacked into. I don't like hypens in filenames, it's a bit shorter, and will be sorted alphabetically to the end of the project folders. Plus mod zips will be structured like unpacked/Author-ModName/manifest.json which is a bit cleaner than having an extra "mods-" at the start of it.

• Our manifest.json doesn't have the "extra": {"godot: {...}} keys, opting instead to just put all that stuff at the root.

• Mod config files are stored in user://mod_configs/ instead of straight user:// for mod-tool-plugin-save.json, mod_user_profiles.json, and mod_loader_cache.json. Keeps the user directory cleaner.