Lua reference

The Lua API of a mod’s main script: the functions addon.dll registers before the script runs, and the callbacks the script defines. Lua says how the host runs the script. The declarations below are annotations for the Lua language server (LuaLS); the same text is the definitions file eix.lua, in the docs folder of the release package: editor setup says how to give it to the server for completion and type checks.

Types

The one type of this API that is not a Lua built-in.

Pointer

---@alias Pointer integer

A game address, passed as the 32 bits of the address read as a signed integer: an address above 2 GB is negative. Raw memory functions need an address that holds valid game memory. A record or slot index is zero-based and must lie inside the table or the slots.

Functions supplied by eix

Global functions that addon.dll registers before the main script runs. A signed 32-bit integer argument is read as Lua’s luaL_checkinteger reads it: a number or a numeric string, truncated. A bad argument raises LuaJIT’s usual argument error.

Round

---@param value number
---@return number
function Round(value) end

Rounds half away from zero.

IDiv

---@param a integer
---@param b integer
---@return integer
function IDiv(a, b) end

Signed integer quotient. A zero divisor or an overflow ends the game.

IMod

---@param a integer
---@param b integer
---@return integer
function IMod(a, b) end

Signed integer remainder. A zero divisor or an overflow ends the game.

GetEffectValue

---@param unit Pointer
---@param effect integer
---@return number
function GetEffectValue(unit, effect) end

The strength of an effect on a unit.

GetPerkModifierForServer

---@param stats Pointer
---@param perk integer
---@return number
function GetPerkModifierForServer(stats, perk) end

The modifier of a perk, read from a unit’s stats on the server.

GetPerkModifierForClient

---@param params Pointer
---@param perk integer
---@return number
function GetPerkModifierForClient(params, perk) end

The modifier of a perk, read from a unit’s parameters on a client.

Heal

---@param stats Pointer
---@param vitals Pointer
---@param amount number
function Heal(stats, vitals, amount) end

Heals the body slots and recomputes the total health.

RegenMp

---@param vitals Pointer
---@param fraction number
function RegenMp(vitals, fraction) end

Adds the maximum mana times fraction, capped at the maximum mana.

DistributeHp

---@param stats Pointer
---@param maxHp number
function DistributeHp(stats, maxHp) end

Sets the body slots’ maxima from maxHp and clamps their current health.

CollectHp

---@param stats Pointer
---@param maxHp number
---@return number
function CollectHp(stats, maxHp) end

Computes the total health from the body slots.

GetPerkRecord

---@param index integer
---@return Pointer
function GetPerkRecord(index) end

The perk record at index, or 0 past the table.

GetWeaponRecord

---@param index integer
---@return Pointer
function GetWeaponRecord(index) end

The weapon record at index, or 0 past the table.

GetArmorRecord

---@param index integer
---@return Pointer
function GetArmorRecord(index) end

The armor record at index, or 0 past the table.

GetMaterialRecord

---@param index integer
---@return Pointer
function GetMaterialRecord(index) end

The material record at index, or 0 past the table.

GetQuickRecord

---@param index integer
---@return Pointer
function GetQuickRecord(index) end

The quick-item record at index, or 0 past the table.

GetSpellRecord

---@param index integer
---@return Pointer
function GetSpellRecord(index) end

The spell record at index, or 0 past the table.

GetRuneRecord

---@param index integer
---@return Pointer
function GetRuneRecord(index) end

The rune record at index, or 0 past the table.

GetPerksTableSize

---@return integer
function GetPerksTableSize() end

The number of perk records.

GetWeaponsTableSize

---@return integer
function GetWeaponsTableSize() end

The number of weapon records.

GetArmorsTableSize

---@return integer
function GetArmorsTableSize() end

The number of armor records.

GetMaterialsTableSize

---@return integer
function GetMaterialsTableSize() end

The number of material records.

GetQuicksTableSize

---@return integer
function GetQuicksTableSize() end

The number of quick-item records.

GetSpellsTableSize

---@return integer
function GetSpellsTableSize() end

The number of spell records.

GetRunesTableSize

---@return integer
function GetRunesTableSize() end

The number of rune records.

GetPerkIndex

---@param record Pointer
---@return integer
function GetPerkIndex(record) end

The index of a perk record, or -1 if it is not found.

GetSpellIndex

---@param record Pointer
---@return integer
function GetSpellIndex(record) end

The index of a spell record, or -1 if it is not found.

GetRuneIndex

---@param record Pointer
---@return integer
function GetRuneIndex(record) end

The index of a rune record, or -1 if it is not found.

GetClassId

---@param object Pointer
---@return integer
function GetClassId(object) end

The class ID of an object.

GetItemsWeight

---@param unit Pointer
---@return number
function GetItemsWeight(unit) end

The total weight of a unit’s equipped items.

GetItemShapeEntry

---@param item Pointer
---@return Pointer
function GetItemShapeEntry(item) end

The prototype record of an item.

GetWeapon

---@param unit Pointer
---@param slot integer
---@return Pointer
function GetWeapon(unit, slot) end

The weapon in a slot (0 to 3) of a unit, or 0 if the slot is empty or out of range.

GetArmor

---@param unit Pointer
---@param slot integer
---@return Pointer
function GetArmor(unit, slot) end

The armor in a slot (0 to 6) of a unit, or 0 if the slot is empty or out of range.

GetQuick

---@param unit Pointer
---@param slot integer
---@return Pointer
function GetQuick(unit, slot) end

The quick item in a slot (0 to 3) of a unit, or 0 if the slot is empty or out of range.

GetSpell

---@param unit Pointer
---@param slot integer
---@return Pointer
function GetSpell(unit, slot) end

The spell in a slot (0 to 7) of a unit, or 0 if the slot is empty or out of range.

ConsoleWriteLine

---@param text string
function ConsoleWriteLine(text) end

Writes a line to the console.

GetGSVar

---@param unit Pointer
---@param name string
---@return number? value `nil` if the unit has no player or the variable does not exist.
function GetGSVar(unit, name) end

Reads a variable of the unit’s player. Names are case-sensitive.

SetGSVar

---@param unit Pointer
---@param name string
---@param value number
function SetGSVar(unit, name, value) end

Writes a variable of the unit’s player. Names are case-sensitive.

UnitIsHost

---@param unit Pointer
---@return boolean
function UnitIsHost(unit) end

Tests whether the unit belongs to the hosting player.

TempDumpVars

---@param unit Pointer
function TempDumpVars(unit) end

Prints every variable of the unit’s player to the console.

FloatFromMem

---@param address Pointer
---@return number
function FloatFromMem(address) end

Reads a 32-bit float.

DoubleFromMem

---@param address Pointer
---@return number
function DoubleFromMem(address) end

Reads a 64-bit float.

Int8FromMem

---@param address Pointer
---@return integer
function Int8FromMem(address) end

Reads a signed 8-bit integer.

Int16FromMem

---@param address Pointer
---@return integer
function Int16FromMem(address) end

Reads a signed 16-bit integer.

Int32FromMem

---@param address Pointer
---@return integer
function Int32FromMem(address) end

Reads a signed 32-bit integer.

UInt8FromMem

---@param address Pointer
---@return integer
function UInt8FromMem(address) end

Reads an unsigned 8-bit integer.

UInt16FromMem

---@param address Pointer
---@return integer
function UInt16FromMem(address) end

Reads an unsigned 16-bit integer.

UInt32FromMem

---@param address Pointer
---@return integer
function UInt32FromMem(address) end

Reads a 32-bit integer. The result is the signed reading, as for Int32FromMem.

FloatToMem

---@param address Pointer
---@param value number
function FloatToMem(address, value) end

Writes a 32-bit float.

DoubleToMem

---@param address Pointer
---@param value number
function DoubleToMem(address, value) end

Writes a 64-bit float.

Int8ToMem

---@param address Pointer
---@param value integer
function Int8ToMem(address, value) end

Writes the low 8 bits of an integer.

Int16ToMem

---@param address Pointer
---@param value integer
function Int16ToMem(address, value) end

Writes the low 16 bits of an integer.

Int32ToMem

---@param address Pointer
---@param value integer
function Int32ToMem(address, value) end

Writes a 32-bit integer.

UInt8ToMem

---@param address Pointer
---@param value integer
function UInt8ToMem(address, value) end

Writes the low 8 bits of an integer.

UInt16ToMem

---@param address Pointer
---@param value integer
function UInt16ToMem(address, value) end

Writes the low 16 bits of an integer.

UInt32ToMem

---@param address Pointer
---@param value integer
function UInt32ToMem(address, value) end

Writes the 32 bits of an integer, converted as Int32ToMem converts it.

StrFromMem

---@param address Pointer
---@return string? text `nil` if the stored pointer is null.
function StrFromMem(address) end

Reads the string pointer stored at address, then the NUL-terminated text it points to.

GetIniValue

---@param file string
---@param section string
---@param key string
---@return string? value `nil` if the path is refused or the file, section or key is missing.
function GetIniValue(file, section, key) end

Reads a value from an INI file of the mod folder, at the call. File, section and key are matched without regard to case. The file is a path below the mod folder, with / or \ as separators; an absolute path, a drive letter or a .. component is refused with a warning in addon.log, as is a missing value (once per file, section and key). Convert a number with tonumber, which wants a . as the decimal point.

Callbacks supplied by the mod

Global functions that the main script defines, each called by the patch group named in its description. Every callback is optional: where the script defines none, the game’s own code runs. A callback that returns nothing updates the structures it receives through their addresses.

GetSkillPriceDiff

---@param from integer
---@param to integer
---@return integer cost
function GetSkillPriceDiff(from, to) end

Group LuaGetPerkPrice. The experience cost of a skill step.

GetPerkPrice

---@param stats Pointer
---@param perkRecord Pointer
---@return integer cost
function GetPerkPrice(stats, perkRecord) end

Group LuaGetPerkPrice. The experience cost of a perk.

GetModifiedDamageOnServer

---@param stats Pointer
---@param unit Pointer
---@param damage number
---@return number damage
function GetModifiedDamageOnServer(stats, unit, damage) end

Group LuaGetModifiedDamage. The damage a unit takes on the server, without the game’s floor of 1.

GetModifiedDamageOnClient

---@param stats Pointer
---@param unit Pointer
---@param damage number
---@return number damage
function GetModifiedDamageOnClient(stats, unit, damage) end

Group LuaGetModifiedDamage. The damage a unit takes on a client, without the game’s floor of 1.

CalcBaseHealth

---@param stats Pointer
---@return number health
function CalcBaseHealth(stats) end

Group LuaRecalcUnitStats. The base health of a unit.

CalcBaseMana

---@param stats Pointer
---@return number mana
function CalcBaseMana(stats) end

Group LuaRecalcUnitStats. The base mana of a unit.

GetModifiedHealth

---@param stats Pointer
---@param unit Pointer
---@param hp number
---@return number health
function GetModifiedHealth(stats, unit, hp) end

Group LuaRecalcUnitStats. The health of a unit after its effects.

RecalcUnitStats

---@param stats Pointer
---@param vitals Pointer
---@param unit Pointer
---@param effectMaxima Pointer
function RecalcUnitStats(stats, vitals, unit, effectMaxima) end

Group LuaRecalcUnitStats. Recomputes a unit’s statistics; effectMaxima points to 40 floats.

Differs from addon.dll 0.12.4.2: sets the alive bit in the stats’ flags (the original sets it in the build flags); an intelligence raise marks the unit changed (the original does not); a strength raise widens the unit by 0.2, as the game does (the original narrows it by mistake); a unit without vitals is skipped (the original crashes).

RecalcInternalHeroStats

---@param stats Pointer
---@param newLoad number
function RecalcInternalHeroStats(stats, newLoad) end

Group LuaRecalcUnitStats. Resets a hero’s statistics to their base values.

Differs from addon.dll 0.12.4.2: sets the alive bit in the stats’ flags (the original sets it in the build flags); an intelligence raise marks the unit changed (the original does not); a strength raise widens the unit by 0.2, as the game does (the original narrows it by mistake); a unit without vitals is skipped (the original crashes).

RegenerateHpAndMp

---@param vitals Pointer
---@param stats Pointer
---@param unit Pointer
---@param inCombat boolean
---@return boolean changed Whether something changed.
function RegenerateHpAndMp(vitals, stats, unit, inCombat) end

Group LuaRegenerateHpAndMp. Regenerates health and mana.

CalcRunningManaCost

---@param stats Pointer
---@param unit Pointer
---@param vitals Pointer
function CalcRunningManaCost(stats, unit, vitals) end

Group LuaCalcRunningManaCost. The mana a running unit pays; subtract it from the mana in the callback.

CalcAttackParamsOnServer

---@param stats Pointer
---@param unit Pointer
---@param params Pointer
---@param effectMaxima Pointer
function CalcAttackParamsOnServer(stats, unit, params, effectMaxima) end

Group LuaCalcAttackParams. Computes an attack’s parameters on the server; effectMaxima points to 40 floats.

Differs from addon.dll 0.12.4.2: a hit from another player’s unit is ignored unless SpellAddon’s enablekillsinmulti is on, as without the group (the original lets players’ units always hurt each other).

CalcAttackParamsOnClient

---@param unitParams Pointer
---@param unit Pointer
---@param params Pointer
---@param effectMaxima Pointer
function CalcAttackParamsOnClient(unitParams, unit, params, effectMaxima) end

Group LuaCalcAttackParams. Computes an attack’s parameters on a client; effectMaxima points to 40 floats.

Differs from addon.dll 0.12.4.2: a hit from another player’s unit is ignored unless SpellAddon’s enablekillsinmulti is on, as without the group (the original lets players’ units always hurt each other).

GetManaBonusOnServer

---@param stats Pointer
---@return number factor
function GetManaBonusOnServer(stats) end

Group LuaGetExpModifiers. The mana factor of a unit on the server.

GetManaBonusOnClient

---@param params Pointer
---@return number factor
function GetManaBonusOnClient(params) end

Group LuaGetExpModifiers. The mana factor of a unit on a client.

GetExpMultiplierOnServer

---@param stats Pointer
---@return number multiplier
function GetExpMultiplierOnServer(stats) end

Group LuaGetExpModifiers. The experience multiplier of a unit on the server.

GetExpMultiplierOnClient

---@param params Pointer
---@return number multiplier
function GetExpMultiplierOnClient(params) end

Group LuaGetExpModifiers. The experience multiplier of a unit on a client.

Differs from addon.dll 0.12.4.2: experience for a unit the client does not have shows unchanged, without a call (the original passes the script a pointer into nothing).

RecalcShopsPriceMultipliers

---@param multipliers Pointer
---@param isLmp boolean
function RecalcShopsPriceMultipliers(multipliers, isLmp) end

Group LuaRecalcShopsPriceMultipliers. Sets the price multipliers of the shops; multipliers points to nine floats per shop.

DistributeLmpExp

---@param exp number
---@param players integer
---@return number share
function DistributeLmpExp(exp, players) end

Group LuaLmpExpDistribution. The share of a kill’s experience for each player.

Differs from addon.dll 0.12.4.2: no value is left on the FPU stack per call (the original’s leftovers corrupt later results).