Modding: Difference between revisions
Jump to navigation
Jump to search
Content added Content deleted
m (Protected "Modding" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))) |
No edit summary |
||
| (27 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
<div class="aw"> |
|||
This is a WIP page that I'm using to document the game's modding API as I go |
|||
<div class="aw-panel"> |
|||
Modder application form: |
|||
https://forms.gle/gaqa4S6jUcoxePrA6 |
|||
<div class="aw-panel--left"> |
|||
Mods for APICO are written in [https://www.lua.org/ LUA]. |
|||
<p>In APICO, you can add mods to expand your game and add new mechanics and features not available in the base game! If you're interested, you can even [[Modding Guide | start modding the game]] yourself!</p> |
|||
All standard LUA libraries are available except <span class="aw-inline--code">io</span> and <span class="aw-inline--code">os</span> 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 use into GameMaker is [https://yal.cc/r/17/lua/ Apollo]. |
|||
<p>Here you can find all the general information and resources around mods and modding.<br/>You can find a list of all mods on the [[Mod List]] page.</p> |
|||
</div> |
|||
<div class="aw-panel--right"> |
|||
When creating a mod you will need to decide on a unique mod ID, which is a lowercase name with no spaces (underscores are accepted) - this will be used as not only your mod directory folder within the game but also for identifying your game in various debugging (so we can see which one of you keeps breaking stuff :P). |
|||
<div class="aw-info"> |
|||
<p class="h"><i>Modding</i></p> |
|||
<p class="sh">Mods for APICO!</p> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
In all the documentation examples, we use <span class="aw-inline--code">sample_mod</span> which is also the name of the sample mod you can download to test out the various API methods. |
|||
<h1 id="Downloading Mods">[[File:Microscope_Item.png|32px]]Downloading Mods</h1> |
|||
All API methods can be found [[Modding API|here]] |
|||
<p>If you're playing APICO and want to download mods, you can do it right from inside the game! From the home screen you can click on "Mods" and the game will retrieve all the approved mods that are available. Once downloaded you can choose to activate or deactivate any of your mods before starting your game. Mods are not available in the [[Demo]].<br/><br/>[[File:Mods_Page_2.png|600px]]<br/><br/>You can also install mods not from the approved list by downloading them from the main [[Mod List]], and using the [[Mod Sideloading|Sideloader]].<br/><b>We cannot recommend these mods for security reasons so install unapproved mods at your own risk!</b></p> |
|||
<h1 id="Creating Mods">[[File:Stone_Hammer_Item.png|32px]]Creating Mods</h1> |
|||
<h1>Current Mods</h1> |
|||
<p>If you want to start creating mods, you can read our [[Modding Guide | Getting Started]] and get stuck in!<br/> To make your mod "official" you will need to upload it to [https://apico.mod.io/ mod.io] via our [https://apico-modloader.herokuapp.com/ APICO Modloader] tool and get it approved. Although players can choose to side-load APICO with any mod they download, they will get shown a warning around the mod when activated.</p> |
|||
sample_mod by @ellraiser |
|||
<h1 id="Modding API">[[File:Book1_Item.png|32px]]Modding API</h1> |
|||
<h1>Glossary</h1> |
|||
<p>If you've read out [[Modding Guide | Getting Started]] guide and are eager to get modding, check out our [[Modding API | API Reference]] which details all API methods along with example LUA code for a bunch of different use-cases.</p> |
|||
<b>Dictionary</b> |
|||
<p>You can also check out our [https://github.com/APICO-Modders APICO Modders Github] for ideas and inspiration!</p> |
|||
<p>In the game every single item, object, machine, NPC, or button has a definition in the Dictionary. If there is not a definition the game will not recognise what you are trying to reference. |
|||
<br/><br/> |
|||
You can add definitions through the <span class="aw-inline--code">api_define_*()</span> methods. |
|||
| ⚫ | |||
<br/> |
|||
<b>Modding Console</b> |
|||
<p>The Modding Console is a debugging tool available by pressing <span class="aw-inline--code">.</span> and it shows all messages from both the Modding API itself as well as any logs or errors from individual mods</p> |
|||
<br/> |
|||
<b>In-Game Console</b> |
|||
<p>When enabled, the In-Game Console is an inline command runner you can use while playing the game by typing <span class="aw-inline--code">/</span> followed by a command. |
|||
<br/><br/> |
|||
For example to spawn in 5 logs you'd use <span class="aw-inline--code">/gimme log 5</span> |
|||
</p> |
|||
| ⚫ | |||
<h1>Getting Started</h1> |
|||
<p>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<br/><br/>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.<br/><br/>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:</p> |
|||
<img/> |
|||
<p>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</p> |
|||
<h1>Mod Structure</h1> |
|||
<p>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.<br/><br/>Every mod needs to start with a <span class="aw-inline--code">mod.lua</span> 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:</p> |
|||
<div class="aw-code">mod_id = <span class="cs">"sample_mod"</span><br/><br/><span class="ck">function</span> <span class="cf">register</span>()<br/> <span class="ck">return</span> mod_id<br/><span class="ck">end</span><br/><br/><span class="ck">function</span> <span class="cf">init</span>(<span class="cp">working_directory</span>)<br/> <span class="cf">api_create_log</span>(<span class="cs">"init"</span>, <span class="cs">"Hello world!"</span>)<br/> <span class="ck">return</span> <span class="cs">"Success"</span><br/><span class="ck">end</span><br/><br/><span class="ck">function</span> <span class="cf">clock</span>()<br/> <span class="cf">api_create_log</span>(<span class="cs">"clock"</span>, <span class="cs">"1 second has passed!"</span>)<br/> <span class="ck">return</span> <span class="cs">"Success"</span><br/><span class="ck">end</span></div> |
|||
<p>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 <span class="aw-inline--code">sc_init_mod()</span> method that you'll see in the Modding Console.<br/><br/>This method will first try and call a <span class="aw-inline--code">register()</span> method in your mod, which will check for duplicate names, and will then call an <span class="aw-inline--code">init()</span> method.<br/><br/>Your <span class="aw-inline--code">init()</span> method is a place for you to setup all mod code you need at the start, and needs to return either <span class="aw-inline--code">Success</span> or an error message - this lets the game know if your mod loaded correctly.<br/><br/>If there are any errors while trying to define an item you'll see one of the following codes logged in the Modding Console</p> |
|||
<div class="aw-code">{{Error|err=Mod Failed To Init|desc=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}}<br/>{{Error|err=Duplicate Mod Registered|desc=This means the mod id you have provided is already registered by the game, try a different mod id!}}<br/>{{Error|err=Mod Failed To Load|desc=This is called if your init() method does not return "Success", allowing you to debug your mods setup}}</div> |
|||
<h1>General Notes</h1> |
|||
<p>The game completely trusts the save file when it loads - because of this your players save file will load with any mod content in the save (custom items, objects, etc). If it can't then find these items in the dictionary you'll end up with a bunch of pink cubes - basically undefined instances.</p> |
|||
<p>https://www.tutorialspoint.com/execute_lua_online.php</p> |
|||
<h1>Common Gotchas</h1> |
|||
<p>In LUA "not equals" is ~=, not !=. Using != will cause a compile error with no useful message</p> |
|||
<p>IF statements follow the format of if SOMETHING then SOMETHING end - missing the "then" will throw a compile error with no useful message</p> |
|||
<p>Booleans are not real! Anytime there's a boolean involved from GameMaker you should use 0 or 1 for your comparisons.</p> |
|||
<p>If a hook doesn't return "Success" then it will get ignored (intentionally) - make sure you are returning something!</p> |
|||
<p>Lists start at 1! If you use [0] somewhere you'll probably get "invalid key to 'next'" as you need to be using [1] instead</p> |
|||
<h1>Example Mods</h1> |
|||
<p>Here are some basic example mods to get you started, and to show you the sort of things you can achieve with the tools available to you in the [[Modding API]]</p> |
|||
<ul><li>Magic Biome Brush</li></ul> |
|||
Latest revision as of 07:27, 22 June 2022
In APICO, you can add mods to expand your game and add new mechanics and features not available in the base game! If you're interested, you can even start modding the game yourself!
Here you can find all the general information and resources around mods and modding.
You can find a list of all mods on the Mod List page.
Modding
Mods for APICO!
Downloading Mods
If you're playing APICO and want to download mods, you can do it right from inside the game! From the home screen you can click on "Mods" and the game will retrieve all the approved mods that are available. Once downloaded you can choose to activate or deactivate any of your mods before starting your game. Mods are not available in the Demo.
You can also install mods not from the approved list by downloading them from the main Mod List, and using the Sideloader.
We cannot recommend these mods for security reasons so install unapproved mods at your own risk!
Creating Mods
If you want to start creating mods, you can read our Getting Started and get stuck in!
To make your mod "official" you will need to upload it to mod.io via our APICO Modloader tool and get it approved. 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 API
If you've read out Getting Started guide and are eager to get modding, check out our API Reference which details all API methods along with example LUA code for a bunch of different use-cases.
You can also check out our APICO Modders Github for ideas and inspiration!