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 and copying the files to a sub-directory with a custom name in your mods directory.
While in the game, go to Options → System 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 Desynced\Content\mods\ sub-directory. Here by default you will only find a file called main.zip 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 def.json file to it (copy it from one of the templates). Besides def.json, 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 def.json you set the field "id": "MyModId". The MyModId 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 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 which explains every Lua function and property available in the system. Detailed description of the 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 -moddev command line argument. In addition, a permanent logging console window can be opened next to the game window by specifying the -log 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 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 print() function. As mentioned above, it is also possible to specify the -log 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 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 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:
Desynced Lua Language Server Addon
This documentation covers the Lua API for Desynced and is to be used with Sumneko's Lua Language Server, using LuaCATS annotation system. VSCode is required.
Package a Finished Mod
A finished mod can be packaged into a .ZIP file by taking all files placed in the mods directory (where def.json is) and using any tool which can create .ZIP files (for example 7-Zip) to package them all into one file. This file can then be shared online or uploaded to the Steam Workshop.
Uploading to the Steam Workshop
To upload a finished and packaged mod to 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.1.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 or 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 def.json at the top level inside the ZIP) and .PNG image file, you can perform the upload with the following command:
DesyncedModUploader.exe MyMod.zip MyMod.png
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:
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}
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:
DesyncedModUploader.exe -u {MOD-ITEM-ID} MyMod.zip
DesyncedModUploader.exe -u {MOD-ITEM-ID} MyMod.png
You will need to pass the numerical item-id of your mod in place of {MOD-ITEM-ID}. The item-id can be found as part of the URL to your mod in the Workshop. Use the "Your Workshop Files" on the Steam Workshop top page to find all the mods you have uploaded.
Modding Details
- def.json Files (mod and package definitions)
- Startup Order (mod and dependency ordering)
- Package Object (mod interface)
- Code Context (simulation and UI context)
- Action System (how actions work and what they can do)
- Delay Functions (how to use)
- Map.Defer (how and when to use)
- UIMsg (UI messages sent by the game)
- MapMsg (map/simulation messages sent by the game)
- Components (how components work, component activations)
- data.settings Table (global settings)
- Map.GetSettings Table (scenario settings)
- Map.GetSave Table (scenario save data)
- Game.GetProfile Table (player options)
- Game.GetLocalPlayerExtra Table (scenario player data)
- Register Object
- Serialization
- UI
- Layout (layouting and properties available to all widgets)
- System Widgets (available widgets, properties exclusive to widgets)
- Custom Widgets (widget class table, property table, attributes)
- Attributes (attribute propagation)
- Events (widget events)
- Lua Debugging (attaching a debugger)
| Modding | |
| Templates | |