Editing Modding

Desynced is a highly moddable game with a very flexible Lua based scripting system that can modify anything from small numerical parameters to custom user interfaces up to entirely new scenarios and game modes which can be completely different from the original game.

== Overview ==
In Desynced, the game itself is a mod which defines what kind of units and components are defined, how they exist in the world and how they interact with each other. It also defines the entire user interface of the game and therefore anything the player sees or can do. This means any part of the game can be customized or even completely replaced.

== Getting Started ==
An easy way to get started is by picking one of the [[Modding/Templates|Modding Templates]] and copying the files to a sub-directory with a custom name in your <code>mods</code> directory.

While in the game, go to <code>Options</code> → <code>System</code> then click the "Open Mods Folder" to open a file browser to the directory where the game's mods are stored. As an alternative, you can browse to the game's installation directory and go into the <code>Desynced\Content\mods\</code> sub-directory. Here by default you will only find a file called <code>main.zip</code> which is a ZIP file that contains the code of the main game.

To make a new mod create a new directory and add a [[Modding/def.json|def.json]] file to it (copy it from one of the [[Modding/Templates|templates]]). Besides <code>def.json</code>, which contains basic description of your mod, you will need at least one .lua file next to it (except for translation mods where there will be one or more .json files).

IMPORTANT: When setting up a new mod, make sure inside the <code>def.json</code> you set the field <code>"id": "MyModId"</code>. The <code>MyModId</code> needs to be a unique identifier which does not start with a number and only contains alphanumeric or _ characters. Be sure to have a unique identifier because it is not possible to run multiple mods that share the same id simultaneously.

IMPORTANT: While writing a mod, be sure to enable the [[#Mod Developer Mode|Mod Developer Mode]] to get access to developer features like log console and hot reloading.

== State of Documentation ==
As of now there is a detailed documentation of the [[#Lua Scripting API|Lua Scripting API]] which explains every Lua function and property available in the system. Detailed description of the [[#Modding Details|various files, definition tables and systems]] will be added to this Wiki in the future.

== Mod Developer Mode ==
While developing a mod, you are strongly encourage to enable the game's "Mod Developer Mode". To do so, start the game with the <code>-moddev</code> command line argument. In addition, a permanent logging console window can be opened next to the game window by specifying the <code>-log</code> argument. To do so in Steam, right-click the game in your Steam Library, then select "Properties" and add the command line arguments under "LAUNCH OPTIONS".

=== Hot Reload ===
To hot reload any changes made in .lua code, just press F7 while playing the game. As an alternative CTRL+ALT+/ (on the numpad) can also be used. Hot reloading is a very quick way to iterate on any code changes and is key to keeping mod development uninterrupted and fun.

=== Suspend ===
By pressing CTRL+ALT+* (on the numpad), the game will quickly save and then shut down. The next time the game is started (in mod developer mode) it will load the saved state and resume the game. This is similar to [[#Hot Reload|hot reload]] but it will also fully reload any changed assets (textures, models, sounds) from disk.

=== Logging Console ===
While running with mod developer mode, you will find a tiny gray triangle in the lower right side of the screen. By clicking it, the in-game logging console will show up and list any errors and warnings as well as output from the Lua <code>print()</code> function. As mentioned above, it is also possible to specify the <code>-log</code> command line argument to get a separate, always open logging console window.

=== Enhanced Warnings ===
With mod developer mode active the game will run stricter checks which Lua data tables get modified in what [[Modding/Code Context|code context]]. This is highly useful to prevent mistakes like writing to global variables in simulation context, modifying simulation data tables from UI context or changing data tables which are immutable after startup. Keep an eye on the [[#Logging Console|logging console]] while developing your mod and make sure not to release any mods to the public that print warnings or errors in mod developer mode.

== Lua Scripting API ==
You can find the Lua Scripting API reference manual at the following link:

https://modding.desyncedgame.com/syntax.html

== Package a Finished Mod ==
A finished mod can be packaged into a .ZIP file by taking all files placed in the mods directory (where <code>def.json</code> is) and using any tool which can create .ZIP files (for example [https://www.7-zip.org/ 7-Zip]) to package them all into one file. This file can then be shared online or [[#Uploading to the Steam Workshop|uploaded to the Steam Workshop]].
  
== Uploading to the Steam Workshop ==
To upload a finished and [[#Package a Finished Mod|packaged]] mod to [https://steamcommunity.com/app/1450900/workshop/ Steam Workshop], you need to use a command line tool called "Desynced Mod Uploader". You can download the current version for Windows here:

https://modding.desyncedgame.com/DesyncedModUploader-1.0.zip

To use it, open up a Command Prompt and run the tool with "DesyncedModUploader.exe" and it will print the usage help. The tool can either [[#Upload a New Mod|upload a new mod]] or [[#Update an Existing Mod|update an existing mod]]. 

=== Upload a New Mod ===
Besides the .ZIP for the mod, you also need to prepare a thumbnail PNG image which will show up in the mod list on the Workshop. Once you have prepared both .ZIP (your mod's files which includes <code>def.json</code> at the top level inside the ZIP) and .PNG image file, you can perform the upload with the following command:

<syntaxhighlight lang="bat">
DesyncedModUploader.exe MyMod.zip MyMod.png
</syntaxhighlight>

Make sure you have the Steam Client running and you are logged in with the user you want to upload the mod with. Once the upload finishes, you should see the following output:

<syntaxhighlight>
Creating private Workshop item ...
Uploading file 'MyMod.zip' to Workshop...

File 'MyMod.zip' successfully published to Workshop!

It is marked as private, make sure to finish the entry and then set file access to public through the web site:
http://steamcommunity.com/sharedfiles/filedetails/?id={MOD-ITEM-ID}
</syntaxhighlight>

It will output a URL you will have to visit to finish setting up how your mod will be presented to other users. Once you're happy with the title, description and images, you can change the visibility status of the item to "Public". Only then it will be publicly visible and can be downloaded by everyone.

=== Update an Existing Mod ===
To update either mod .ZIP or the thumbnail image you can use the Mod Uploader in the update mode. Use either of the following commands to update the ZIP or the PNG file:

<syntaxhighlight lang="bat">
DesyncedModUploader.exe -u {MOD-ITEM-ID} MyMod.zip
DesyncedModUploader.exe -u {MOD-ITEM-ID} MyMod.png
</syntaxhighlight>

You will need to pass the numerical item-id of your mod in place of <code>{MOD-ITEM-ID}</code>. The item-id can be found as part of the URL to your mod in the Workshop. Use the "Your Workshop Files" on the [https://steamcommunity.com/app/1450900/workshop/ Steam Workshop top page] to find all the mods you have uploaded.

== Modding Details ==
* [[Modding/def.json|def.json]] Files (mod and package definitions)
* [[Modding/Startup Order|Startup Order]] (mod and dependency ordering)
* [[Modding/Package Object|Package Object]] (mod interface)
* [[Modding/Code Context|Code Context]] (simulation and UI context)
* [[Modding/Action System|Action System]] (how actions work and what they can do)
* [[Modding/Delay Functions|Delay Functions]] (how to use)
* [[Modding/Map.Defer|Map.Defer]] (how and when to use)
* [[Modding/UIMsg|UIMsg]] (UI messages sent by the game)
* [[Modding/MapMsg|MapMsg]] (map/simulation messages sent by the game)
* [[Modding/Components|Components]] (how components work, component activations)
* [[Modding/data.settings|data.settings]] Table (global settings)
* [[Modding/Map.GetSettings|Map.GetSettings]] Table (scenario settings)
* [[Modding/Map.GetSave|Map.GetSave]] Table (scenario save data)
* [[Modding/Game.GetProfile|Game.GetProfile]] Table (player options)
* [[Modding/Game.GetLocalPlayerExtra|Game.GetLocalPlayerExtra]] Table (scenario player data)
* [[Modding/Register Object|Register Object]]
* [[Modding/Serialization|Serialization]]
* [[Modding/UI|UI]]
** [[Modding/UI/Layout|Layout]] (layouting and properties available to all widgets)
** [[Modding/UI/System Widgets|System Widgets]] (available widgets, properties exclusive to widgets)
** [[Modding/UI/Custom Widgets|Custom Widgets]] (widget class table, property table, attributes)
** [[Modding/UI/Attributes|Attributes]] (attribute propagation)
** [[Modding/UI/Events|Events]] (widget events)
* [[Modding/Lua Debugging|Lua Debugging]] (attaching a debugger)

{{ModdingNav}}