Lua Architecture
Contents
Overview
The Lua architecture consists of a series of add-ons of two varieties, Gadgets and Widgets. Gadgets are add-ons to the gameplay itself, such as changes to unit behaviours and graphics, and are stored in the Zero-K/LuaRules/Gadgets/ folder. Similarly, Widgets are add-ons to the user interface (UI) that the player interacts with throughout the game, and are stored in the Zero-K/LuaUI/Widgets/ folder. Any modifications to Zero-K as part of a mod should be done via the addition and/or modification of widgets and gadgets, as this is the easiest and most reliable way to make these changes.
Gadgets
Gadgets should all be placed in the Zero-K/LuaRules/Gadgets/ folder. Gadgets are loaded and handled by the gadget.lua file in Zero-K/LuaRules/gadget.lua. You may review this file to understand how gadgets are handled by Zero-K, however you should not modify the file, as this has a high likelihood of breaking its ability to interface with existing gadgets.
For details on the Call-ins used by Gadgets, please refer to the Event Call-ins section
Widgets
Widgets should all be placed in the Zero-K/LuaRules/Widgets/ folder. Widgets are loaded and handled by the cawidgets.lua file in Zero-K/LuaUI/cawidgets.lua. You may review this file to understand how widgets are handled by Zero-K, however as with the gadgets.lua file, you should not modify this file, as this has a high likelihood of breaking its ability to interface with existing widgets.
For details on the Call-ins used by Widgets, please refer to the Event Call-ins section
Event Call-ins
Call-ins are events that trigger a gadget or widget to execute. A gadget or widget will not run until the specified call-in has been called in. Some examples of call-ins to use are "UnitCreated", which triggers when any unit is created, and "UnitDamaged", which triggers when a unit is damaged.
Gadget Call-Ins
See the table "callInLists" within the file Zero-K/LuaRules/gadget.lua
Widget Call-Ins
See the tables "callInLists", "flexCallIns", and "reverseCallIns" within the file Zero-K/LuaUI/cawidgets.lua
There are also a list of call-ins that originate from Spring, these may or may not be compatible with the aforementioned gadgets and widgets.
Spring Call-in Library: https://springrts.com/wiki/Lua:Callins
Function Call-outs
Call-outs are functions that either set or read some property about the game. For instance, the call-out Spring.SetTeamResource will set a team's resource to a given value, while the call-out Spring.GetTeamResources will return a table of statistics for a chosen resource of a chosen team. The majority of interactions with the game will be through the use of call-outs. Call-outs come in two varieties, Control and Read. Control call-outs such as Spring.SetTeamResource will set a property in the game based on the parameters given, while Read call-outs such as Spring.GetTeamResources will only read and return existing properties, such as in this case the team's resources, using the resource type and team number parameters that are given. These concepts are not Zero-K specific, but are inherit to Spring. The below pages of the Spring wiki will provide a list of valid call-outs you can use, the parameters they require, and the output information they will provide.
