Modding/Introduction

This guide is an introduction to making mods Griftlands. These will help you get started with modding.

## Prerequisites

Before you start modding Griftlands, you need to make sure that you meet these following requirements:

1. A copy of Griftlands on your computer. Any operating system should work, as long as the operating system can run Griftlands.
	* You may wish to keep the game files ready for easy reference. On Steam, they can be found by right clicking Griftlands in your steam library and selecting "Properties... -> Local Files -> Browse...". The scripts of the game can be found in "data\_script.zip". You may unzip the files to anywhere you can access.
2. A basic understanding of Lua. Lua is the programming language used to run Griftlands, and all of its core logic is written in it. If you are unfamiliar with Lua, check out the Lua documentation first. You can make mods by copy and pasting existing code without understanding much Lua, but it is a lot less flexible, and it is harder for you to understand what went wrong in your code.
3. A code editor. Any code editor will do. Some of the most popular code editors are VS Code, Sublime Text, or Notepad++, but you can use Notepad if you don't have access to these code editors, or if you are masochistic enough.
4. It is strongly recommended that you enable debug mode for Griftlands, as it enables more options and makes modding easier and more efficient.
	* If you are on Steam, debug mode can be enabled by right clicking Griftlands in your steam library, going to "Properties... -> General -> Launch Options", and entering `"--debug`" as a launch option (without the quotes). It enables debug options in the game, such as CTRL+R for quick restart, ~ (tilda) for debug menu, and CTRL+~ for debug console.
	* If you are on Epic, debug mode can be enabled by going to "Settings -> Griftlands -> Additional Command Line Arguments" and entering "`--debug`" (without the quotes).

## Creating a New Mod

To create a new mod, perform these following steps:

1. Find the save folder for Griftlands. On Windows, if you have the Steam version, the folder should be located at "%APPDATA%/Klei/Griftlands/steam-<steamID>/", and if you have the Epic version, it should be located at "%APPDATA%/Klei/Griftlands/<EpicID>/ ". If you are on the experimental branch, replace "Griftlands" in the filepath with "Griftlands\_testing". You will know that you are in the right folder if you see a "saves/" directory, "profile.lua", "log.txt", and other auto-generated files.
2. If "mods/" directory does not exist already, create it.
3. Go to the directory "mods/" and create a new folder, naming it whatever you like. This folder will contain all the files for your mod.
4. Create "modinit.lua". This is the file that will be loaded by the game. Open that file with the code editor of your choice, and return a table containing these attributes (see the example below):
	* `title`: (Mandatory) The title of the mod.
	* `description`: (Mandatory) The description of the mod.
		+ Alternatively, `description_file`, which specifies the path to the file containing the description of the mod.
	* `previewImagePath`: The path to the workshop preview image of the mod. If you do not specify this, there will be no preview image for your workshop item, and you have to manually add it later.
	* `version`: (Mandatory) The version of your mod, following the "major.minor.patch" format. For example, "1.0.0", or "0.3.2".
	* `alias`: (Mandatory) The "alias" for your mod, useful for specifying relative paths within your mod and the ordering of the mod.
	* `OnLoad`: (Mandatory) The function to run after the game has loaded its core contents. It takes in one parameter: the mod table, and may return an additional function that will load after `OnLoad` is called for every enabled mods, following the same format as `OnLoad`. This function is where you should load the majority of your contents.
	* `OnPreLoad`: The function to run before the game has loaded its core contents. It takes in one parameter: the mod table. If your mod has additional languages or other localization options, they should go here. Anything you do that can change how contents load should go here too.
	* `load_before`: An optional list of alias(es) representing which mods should your mod load before. By default, the mod is loaded in the order of their ID, but if you want to make sure your mod is loaded before another mod, you should list the other mod's alias here. Circular dependencies will cause problems, so don't do that.
	* `load_after`: Same as `load_before`, except it specifies which mods should your mod load after.
5. Save the mod and run Griftlands. You should be able to see your mod as a local mod under the "Manage Mods" option, or CTRL+5 under Debug Mod List (if debug mode is enabled).

And well done! You have created your first mod! It doesn't do anything yet, but as you continue to develop your mod, it will actually start to do more and more things, and potentially changing how the game works entirely.

Below is a sample code for the `modinit.lua` file.

```
local function OnLoad( mod )
    print("Hello, world!")
end

return {
    title = "Example Mod",
    description = "This is an example mod showcasing how to make your first mod.",
    previewImagePath = "preview.png",

    version = "0.0.1",
    alias = "EXAMPLE\_MOD",

    OnLoad = OnLoad,
}

```

## Publishing/Updating A Mod

Once you are happy with a mod, and you are on Steam, you may choose to publish that mod on Steam workshop. To do that, perform these steps (the same steps are performed for updating a mod):

1. While in debug mode, press CTRL+5 to bring up the Debug Mod List.
2. Select "Workshop" under the correct workshop item and click "Upload NEW item to workshop". Selecting a workshop item that already exist will instead bring up "Upload item <item ID> to workshop".
3. If your workshop item is uploaded successfully, you should be able to see "Submit succeeded!" in green at the bottom of the list. Otherwise, you will see "Submit failed!" in red with an error code. Look up the code to see what went wrong.
	* If you missed the message, you can bring up the debug console to see a messier output.

When your mod is initially submitted to Steam workshop, it will be private. You can change the visibility, title, and/or description of the mod. The title and the description will default to that of the mod table, but updating the mod will not cause the title and description to change in the workshop page.

## Loading Additional Files

Often, it is not enough to write all of your mod in one file. Sometimes your mod needs multiple files. To load the files in Lua, use `require "ALIAS:filename"`.

For example, suppose that you have the file "content.lua" in the mod folder containing the sample `modinit.lua` file, you can load it with this following code:

```
local function OnLoad( mod )
    require "EXAMPLE\_MOD:content"
    -- Insert the rest of your OnLoad function here.
end

```
However, loading each file individually can be tedious, so you might find it appealing to load every file in a folder at once. If you want to do that, you can use the following code to load everything in a folder:

```
local filepath = require "util/filepath"

local function OnLoad( mod )
    -- This loads every Lua files under the directory "code/", including Lua files in subdirectories.
    for k, filepath in ipairs( filepath.list\_files( "EXAMPLE\_MOD:code/", "\*.lua", true )) do
        local name = filepath:match( "(.+)[.]lua$" )
        if name then
            require(name)
        end
    end
    -- Insert the rest of your OnLoad function here.
end

```
While this is convenient, you lose control in terms of load order. This should only be used if you have a lot of files to load, and if you don't care about the load order of those files.

## Example Mods

Klei Entertainment has posted two example mods for modders to get started with modding:

* "Shel's Adventure": An example mod showcasing the various features for mods.
* "Havarian Mod": An example mod showcasing the addition of new languages.

They are both available on Steam workshop (sorry, people playing on Epic, I don't think you exist). Once you subscribe and update, these mods can be found in "/Steam/steamapps/workshop/content/601840". You may subscribe to other mods as well and take a look at them.

## Additional Modding Resources

* "Your First Mod" on Klei's forum: https://forums.kleientertainment.com/forums/topic/121803-your-first-mod/
* The modding section on Klei's forum: https://forums.kleientertainment.com/forums/forum/248-griftlands-mods-and-tools/
* The official Klei Entertainment Discord server: http://discord.gg/klei
* The unofficial Griftlands Discord server: https://discord.gg/GdrBVHF

## Modding Tips

* Do not be afraid to experiment. If you don't know what you are doing, the worst thing that you can do is crash Lua, and that's okay because the game will provide a nice stack trace that tells you where went wrong. Once you learned what you should do and shouldn't do, you are able to explore what you can do. Speaking of stack trace...
* Learn how to read the stack trace from the Lua crash screen. Lua is a helpful language for beginners, because in the error message, Lua will provide an explanation of the error, which file the error is located, and the line number the error occurred at. With it, you can easily find the error and fix it. Sometimes the error is not obvious, but generally speaking, if you find one of your mod files in the stack trace, you might want to pay attention to those files and the line numbers that the error occurred.
* Start by looking at what other people did. When you want to add a certain feature, such as a new card or a new graft, you may realize that similar features have already been added, possibly in the base game. You can start by copying the code where that feature is implemented, and editing the code until it fits into your vision. It is the best way of learning how the code of this game works and how to add unique features.
* Learn how to use debug tools. Debug tools are very useful for mod testing, and it can dramatically speed up the mod developing process once you know how to use it well. For example, you can use `print("message")` to print a message to the debug console, which you can bring up using CTRL+~. The ~ (tilde) key brings up a debug table, which, depending on where you are in the game, serves different purpose. Try experimenting with them.
	+ A helpful function in the game is `DBG(t)`. This function brings up the debug table for any table `t`. You can use it in the console, or in your mod code to visually inspect any table you want.