Modfiles | modfile.txt

Table of Contents

• General Info
• Sample Modfiles
• Commands
• Payload Commands

General Info

A modfile can be any plaintext file, but would typically be a .txt

Mods that are directly imported by the importer need to have a modfile.txt in its Mod Folder
Mods intended as modules for other mods / included by other mods may not need this main modfile.

The mod importer (modimporter.py) will read the modfile.txt file in your mod's folder and implement the changes described by commands in it.

Syntax highlighting for modfiles for Notepad++ UDL can be found here

Any modfile is read with the following rules:

1. The unignored portions of each line is a command
2. Empty commands are ignored
3. Any of the below is only relevant if not enclosed by quotes " on the same line
4. -: begins a multiline comment, everything including and beyond is ignored until and including :-
5. :: begins a line comment, the entire line from and including this point is ignored
6. ; forces the beginning of a new command on the same line
7. , acts like a space and are interchangable
8. Indentation and excess spacing is ignored

Sample Modfiles

The simplest file to import all the lua scripts in the folder Scripts in your mod's folder:

Import "Scripts"

A more complex modfile using multiple commands may look something like this:

Import "MyScript.lua"

To "Scripts/EncounterData.lua"
Import "encounterdata.lua"

To "Game/Obstacles/Backgrounds.sjson"
SJSON "MyBackgrounds.sjson"

The generic anatomy of a modfile may look something like this:

-: Mod Name - 
    Author(s) - 
  This mod does something...
  Installation:
    ...
    ...
:-

Include <optional modules>

To <files>
Load Priority <N>
<Payload Command> <files or folders>
...
<Payload Command> <files or folders>

Include <optional modules>

Commands

Include <filenames>
Parses the files as modfiles, executes everything in them in order before continuing to other commands.
You can use this to defer loading your mod to a separate file allowing users to quickly disable the mod from the main modfile.
Eg:
Include "subfile.txt"

To <filenames>
Sets any future payload commands to target these files
The filenames are specified by paths relative to the game's Content folder Defaults to the best generic choices for the game for lua scripts.

Load Priority <N>
Sets the priority of future payload commands
Default priority is 100, lower priority is loaded first.

Payload Commands

All file paths in this section are relative to the folder the modfile is contained in

Import <files or folders>
File Format: Lua
Adds the files as import statements to the target files.

SJSON <files or folders>
File Format: SJSON
Merges the SJSON of the files into the SJSON of the target files.

XML <files or folders>
File Format: XML
Merges the XML of the files into the XML of the target files.