Lua Style Guide - funovus/editor-wiki GitHub Wiki
This style guide contains a list of guidelines that you should follow when writing trigger Lua code to make the code more readable and consistent.
Indentation and Formatting
We recommend using Visual Studio Code when writing trigger Lua code and use the StyLua extension to automatically format the code. The extension takes care of indentation and formatting so you don't need to waste your time wondering about where to put a space or line-break. See here for setup instructions.
If you prefer formatting the code manually or using a different editor, follow these rules:
- Indent using tabs (tab size should be set to 4 spaces in your editor.)
- No trailing spaces.
- Keep line width under 120.
- Put opening curly braces on the same line as the preceding syntax element when creating multi-line blocks.
- Put a space before and after operators.
- Put a space after commas in tables and function calls.
local GOLD_PER_GEM = 5
local g_data = {
gold = 1000,
gems = 1000,
}
function ExchangeGemsForGold(gems_spent)
if g_data.gems < gems_spent then
return
end
g_data.gold = g_data.gold + gems_spent * GOLD_PER_GEM
g_data.gems = g_data.gems - gems_spent
end
File Structure
A trigger file generally consists the following parts in order:
- Module imports.
- Constant definitions.
- Global variable definitions.
- Function and event callback definitions.
- Initialization and event registration code.
- Module exports (generally only used for additional scripts or shared mods).
Example:
-- Module imports
local json = require("json") -- import built-in Lua libraries.
local core = require("core") -- import dependency mods.
-- Constants
local SCALING_FACTOR = 1.37
local SCALING_TABLE = {
{ 1, 1.1, 1.25, 1.5, 1.8 },
{ 2, 2.2, 2.5, 3, 4 },
}
-- Global variables
local g_level_data = {
player = {
{
unit = "Goblin",
x = 15,
y = 15,
},
},
enemy = {
{
unit = "Archer",
x = 18,
y = 18,
},
},
}
-- Functions
local function OnMapStart()
-- Initialize.
end
local function OnUnitDeath()
-- Handle unit death.
end
-- Initialization and event registration.
DCEI.TriggerAddTimerEventElapsed(OnMapStart, 0)
DCEI.TriggerAddUnitDiedEvent(DCEI.UnitAny, OnUnitDeath)
-- Module exports
local mod = {}
function mod.ShowShopUi()
-- Create shop ui.
end
-- This value will be returned when dependent maps import this module via the
-- require(#name) syntax.
return mod
Naming and Declaration
- Avoid abbreviations.
- Constants use
ALL_UPPER_CASE
. - Variables use
snake_case
. - Prefix global variables with
g_
. - Functions use
PascalCase
. - Always use
local
when declaring constants/variables/functions. - Use double quoted string literals. E.g.,
"hello world"
.
Tables
- Avoid using tables with mixed keys. A table should be used as a list (with integer indexes), a struct (with fixed named keys), or a dictionary (indexed with dynamic string keys) and be used consistently as the same type.
-- Table as a list.
local list_table = { "gold", "gems", "silver" }
DCEI.LogMessage("Table size: " .. #list_table)
-- Table as a struct
local struct_table = {
gold = 1000,
gems = 1000,
}
DCEI.LogMessage("Gold: " .. struct_table.gold)
-- Table as a dictionary
local dictionary_table = {}
for _, name in ipairs(list_table) do
dictionary_table[name] = 1000
end
DCEI.LogMessage("Gold: " .. dictionary_table["gold"])
- Iterate list table with
ipairs
and struct/dictionary tables withpairs
.
Functions
- Always use parentheses when calling a function.
- Avoid declaring global functions. This can be easy to overlook, but declaring a global function instead of a local one may result in unintentionally overwriting a function with the same name in a mod, dependency, or included lua file.
-- GOOD: local functions.
local function OnUnitDeath()
-- handle unit death
end
-- BAD: global functions.
function OnUnitDeath()
-- handle unit death
end
- Use function-prefix syntax when declaring functions.
-- GOOD
local function OnUnitDeath()
-- handle unit death
end
local mod = {}
function mod.ShowShopUi()
-- show shop UI
end
-- BAD
local OnUnitDeath = function()
-- handle unit death
end
local mod = {}
mod.ShowShopUi = function()
-- show shop UI
end
Comments
- Comments should start with
--
and a single space. - Separate inline comments by 2 or more spaces from the preceding statement.