====== Welcome to the Foundation Modding Wiki ======

**Warning**

Modding capabilities are very embryonic. Expect a lot of improvement and changes in the future.

This documentation is a draft with a few guidelines, it will evolve gradually with the development of modding features.

  * ** [[changelog|Changelog]] **
  * ** [[migration|Migration Notes]] **
  * ** [[guides|Community Guides]] **

===== More info on: =====
  * [[data-types|Data types]]
  * [[enumerations|Enumerations]]
  * [[annotations|Annotations]]
  * [[example-mods|Example Mods]]
  * [[texture-usage-policy|Game texture usage policy]]
  * [[debugging-mods|Debugging mods]]

  * [[foundation-library-functions|Foundation library functions]]
  * [[mod-management-functions|Mod management functions]]
  * [[version-library|Version library]]
  * [[mod-io-functions|Mod IO functions]]

  * [[dependencies|Mod Dependencies]]
  * [[custom-classes|Custom classes]]
  * [[components|Components]]
  * [[asset-override|Game asset override]]
  * [[behavior-trees|Behavior trees]]
  * [[events|Events]]
  * [[building-asset-processor|Building asset processor]]
  * [[level-of-detail|Level Of Detail (LOD)]]

  * [[workplaces|Create workplaces]]
  * [[monuments|Create monuments and bridges]]
  * [[walls|Create walls]]
  * [[particle-effects|Create particle effects]]
  * [[construction-steps|Construction steps]]
  * [[material-sets|Material sets]]

===== Where do I start? =====
  * Create a new folder in ''Documents\Polymorph Games\Foundation\mods''.
  * In your mod folder, create a ''mod.json'' file and the main LUA script for your mod: ''mod.lua''

===== The mod.json file =====
The json file is loaded early and give basic information on your mod, without having to load your LUA scripts.

In addition, this file contains the list of your mod's custom maps and their info, if any.

<file json mod.json>
{
    "Name": "Simple Example Mod",
    "Author": "Leo",
    "Description": "A very simple mod example",
    "Version": "2.0.0",

    "MapList": [
        {
            "Id": "MY_MAP_ID_01",
            "Name": "My Custom Map",
            "Description": "This is a simple description of my map.",
            "PreviewImage": "metadata/my_map_preview.png"
        }
    ]
}
</file>

===== metadata folder =====

For files that don't need to be loaded, you can add those files to a ''metadata'' folder at the root of your mod. This can be used for example to contain the map thumbnail images listed in the ''mod.json'' file.

===== The mod.lua script =====
First, you have to create your new mod instance:
<file lua mod.lua>
local myMod = foundation.createMod();
</file>
You can then include other script, declare new assets, [[asset-override|override existing assets]], etc...

===== Including other LUA files =====
''mod.lua'' is the only script file from your mod that will be automatically loaded.

In order to include another LUA file, you can call the ''dofile'' function on your mod:
<code lua somescript.lua>
myMod:dofile("anotherscript.lua")
</code>

This will execute the script ''anotherscript.lua'' from your mod folder. This will also pass the mod variable ''myMod'' to the script. So you will be able to access ''myMod'' from ''anotherscript.lua'' this way:
<code lua anotherscript.lua>
local myMod = ... -- retrieve arguments passed to the script

-- do stuff with myMod
-- ...
</code>

In addition, you can pass any number of variable to the called script:
<code lua somescript.lua>
myMod:dofile("anotherscript.lua", 42, "A Super String", { 1, 4, 12 })
</code>

<code lua anotherscript.lua>
local myMod, anInteger, aString, anArray = ... -- retrieve arguments passed to the script
</code>

===== Enabling / Disabling a mod =====
You can enable / disable mods from the ''Mods'' menu.

Be aware that even when a mod is disabled, most of the mod assets are loaded anyway, but are not active.

If you want to fully ignore a mod, you can either remove it from your mods folder, or rename the ''mod.lua'' file into something else (''mod_.lua'' for instance).
===== Logging / Debugging =====

==== Log ====

You can log your own logs into foundation log file:

<code lua>
myMod:log("Hello World!") -- creates an INFO log entry
myMod:logWarning("This is a warning!") -- creates a WARNING log entry
myMod:logError("This is an error!") -- creates an ERROR log entry
</code>

In order to isolate mods related logs, Foundation will log most of mod related information in a specific log file located in ''Documents/Polymorph Games/Foundation/mod-%NAME%.log''

However, keep in mind that a mod can interact with the game in various indirect way, and some valuable information could still  be hidden in the global game log in ''Documents/Polymorph Games/Foundation/foundation.log''.

==== Message box ====

You can also open a blocking message box for debugging purpose. This function is recommended for mod development only.

<code lua>
myMod:msgBox("Hello there!")
</code>

For this function to work, the user must manually set the field ''ModMsgBoxEnabled'' to ''true'' in the user settings file (''usersetting.config''). Otherwise, it will only create a new log entry, like the ''log'' function.

===== What is this generated_ids.lua file? =====

Internally, Foundation uses random unique IDs (GUID) to identify most objects and resources. 
When a new asset is added to the mod, Foundation will create a new ID for it, and will store the association between the "modding name" and the ID of the asset.

The ''generated_ids.lua'' file is where the association is stored. When you distribute your mod, it's important to distribute this file too. It will ensure that all your assets have the same ID from one player's computer to another, hence allowing them to share a save-game for instance.

===== Sharing a mod =====

Modders are encouraged to use **mod.io** to share their mods. Mods shared this way can be found and downloaded from the in-game mod browser.

Here is the Foundation page: [[https://foundation.mod.io]]

You'll have to upload a zip of your mod. Make sure the zip contains directly the mod files (''mod.lua'' needs to be at the root of the zip).

===== Quickly reload mods =====

When developing and testing a mod, you can quickly reload your game by pressing ''Ctrl + Shift + R''.