Modding Guide
To get started with creating mods you don't need to do anything special! You just need a basic understanding of LUA and your favourite code/text editor, as well as our handy API Reference.
However to make your mod "official" you will need to apply to become a Mod Creator and get your mod approved - this will give you access to all the mod creator resources on Guilded as well as the mod uploading tools. Although players can choose to side-load APICO with any mod they download, they will get shown a warning around the mod when activated.
Modding
Getting Started
Language
As mentioned earlier, mods are written in LUA! All standard LUA libraries are available to use except io and os for security reasons. If there is something you specifically need let us know and we can look into a way of exposing it through the API! The LUA interface we are using into GameMaker is Apollo.
If you haven't written LUA before there are definitely a few quirks you'll have to get used to! Here's some common gotchas we have come across:
- In LUA "not equals" is ~=, not !=. Using != will cause a compile error with no useful message
- IF statements follow the format of if SOMETHING then SOMETHING end - missing the "then" will throw a compile error with no useful message
- Lists start at 1! If you use list[0] somewhere you'll probably get "invalid key to 'next'" as you need to be using list[1] instead
- If you see an "attempt to add a 'string' with a 'string'" error it means you used + instead of .. for string concatenation.
We recommend using the Online Lua Compiler to test the syntax of your LUA code before running it in APICO
Process
In the game, a player can choose the mods they want to load from the home screen. They'll be able to download any of the official mods and choose which downloaded mods they want to activate or deactivate. When they load their game the mods will be loaded in the following processes:
- First when the game loads it checks that the mods folder exists (where saves are stored), and if not it creates one
- Then the game gets all the currently "active" mods from the players settings.json file
- When the player picks a save the game then goes through each of the active mods and calls it's register() and init() methods, adding in any Hooks your creator has specified
- Once all mods have loaded the game calls the ready() hook for any mods that have subscribed to it, and then finally loads the save.
- Any "undefined" instances in the player save file (created by mods) are refreshed at this point
Mod Structure
Modding Console & In-Game Console
The Modding Console is a debugging tool available by pressing . and it shows all messages from both the Modding API itself as well as any logs or errors from individual mods
When enabled with api_set_devmode() the In-Game Console is an inline command runner you can use while playing the game by typing / followed by a command.
For example to spawn in 5 logs you'd use /gimme log 5
Getting Started
To get started you just need your favourite IDE! You don't need to compile your LUA code in advance, the game does this when it loads your mod, so outside of any LUA extensions you might find useful you don't need any other resources
When modding is properly live, a player will be able to see all mods from the "Modding" section thats accessible from the home screen. They'll be able to pick the mods they want and download them, which will save the mod into the /mods directory, as well as update their settings.json file. For now you'll need to do this manually.
For example if your mod is called "sample_mod", you'll need to set the "downloaded_mods" key inside settings.json as ["sample_mod"], as well as add your mod in a folder called "sample_mod". Your directory will look like this:
<img/>
If done correctly, when you go to the "Modding" section you'll see your mod in the right-hand section, just inactive.Pressing the "tick" button will activate the mod, and now any time you start a game you'll see a "Loading mods..." screen
Mod Structure
For mods to work they need to follow a basic structure so that APICO can register and load mods correctly, as well as handle any errors that might occur when trying to compile your code.
Every mod needs to start with a mod.lua file at the root of your mod folder. This is the main file that initially gets loaded - a basic mod file would look something like this:
function register()
return mod_id
end
function init(working_directory)
api_create_log("init", "Hello world!")
return "Success"
end
function clock()
api_create_log("clock", "1 second has passed!")
return "Success"
end
When the game loads, it'll retrieve the player's mod settings to get a list of all active mods. It will then try and init these mods through the sc_init_mod() method that you'll see in the Modding Console.
This method will first try and call a register() method in your mod, which will check for duplicate names, and will then call an init() method.
Your init() method is a place for you to setup all mod code you need at the start, and needs to return either Success or an error message - this lets the game know if your mod loaded correctly.
If there are any errors while trying to define an item you'll see one of the following codes logged in the Modding Console
This means your mods code could not be compiled correctly! You'll also see related LUA errors logged after this error message that should help narrow down the issue
Error: Duplicate Mod Registered
This means the mod id you have provided is already registered by the game, try a different mod id!
Error: Mod Failed To Load
This is called if your init() method does not return "Success", allowing you to debug your mods setup