Lua Style Guide - BLKTower/TestWiki 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 vscode-lua 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.

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 data = {
    gold = 1000,
    gems = 1000,
}
function ExchangeGemsForGold(gems_spent)
    if data.gems < gems_spent then
        return
    end
    data.gold = data.gold + gems_spent * GOLD_PER_GEM
    data.gems = data.gems - gems_spent
end

File Structure

A trigger file generally consists the following parts in order:

• Module imports.
• Constant definitions.
• Data variable definitions.
• Function and event callback definitions.
• Intiailization and event registeration code.
• Module exports.

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},
}

-- Variables
local level_data = {
    player = {
        {"Goblin", 15, 15},
    },
    enemy = {
        {"Archer", 15, 15},
    }
}

-- 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.
• 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 with pairs.

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()
end

-- Bad: global functions.
function OnUnitDeath()
end

• Use function-prefix syntax when declaring functions.

-- Good
local function OnUnitDeath()
end
local mod = {}
function mod.ShowShopUi()
end

-- Bad
local OnUnitDeath = function()
end
local mod = {}
mod.ShowShopUi = function()
end

Comments

• Comments should start with -- and a single space.
• Separate inline comments by 2 or more spaces from the preceding statement.