Trigger API Reference\Core Functions

These functions are available from the built-in core registry dependency and are implemented in Lua. These functions provide utility and shortcuts rather than strictly providing any new functionality.

For an explanation of what registry dependencies are and what other officially supported first-party mods there are, see Registry Mods.

WARNING: This mod is deprecated. See Core instead.

Example Usage

local core = require("core")

core.DamageUnit(some_unit, 10)

Color

HexToRGBA()

HexToRGBA( hex )

Returns a table array of RGBA values (0 - 255) from a hexadecimal string. If no alpha value is supplied, the returned color will have full opacity.

Example Usage

local hex_color = "#f17aed"

local magenta = core.HexToRGBA(hex_color)
-- magenta = {241, 122, 237, 255}

DCEI.SetFrameImage(DCEI.GetUiRootFrame(), magenta[1]/255, magenta[2]/255, magenta[3]/255, magenta[4]/255)

HexToValues()

HexToValues( hex )

Returns a table array of RGBA values (0 - 1) from a hexadecimal string. If no alpha value is supplied, the returned color will have full opacity.

Example Usage

local hex_color = "#f17aed"

local magenta = core.HexToValues(hex_color)

DCEI.SetFrameImage(DCEI.GetUiRootFrame(), magenta[1], magenta[2], magenta[3], magenta[4])

RGBAToHex()

RGBAToHex( rgba )

Returns a hexadecimal color value as a string from a table array of RGBA values. If no alpha value is supplied, the returned color will have full opacity.

Example Usage

local rgba = {241, 122, 237}

local magenta = core.RGBAToHex(rgba)
local tag = "<color=" .. magenta .. ">"
-- magenta = "#f17aed"

local text = tag .. "Magenta"
local label = DCEI.CreateTextFrame(DCEI.GetUiRootFrame())
DCEI.SetTextFrameText(label, text)

RGBAToValues()

RGBAToValues( rgba )

Returns a table array of RGBA percentage values (0 - 1) from a hexadecimal string. If no alpha value is supplied, the returned color will have full opacity.

Example Usage

local rgba = {0, 0, 0, 160}

local faded_black = core.RGBAToValues(rgba)
-- faded_black = {0, 0, 0, 0.63}

DCEI.SetFrameImageColor(DCEI.GetUiRootFrame(), {r = faded_black[1], g = faded_black[2], b = faded_black[3], a = faded_black[4]})

Effect

CreateEffect()

CreateEffect( effect_name, x, y )

Creates an effect at a location. The effect will be executed as if by a neutral caster unit.

Example Usage

local effect = DCEI.Effect("DebugPoint")
core.CreateEffect(effect, 16, 16)

Game

MapStartTime()

MapStartTime()

Returns the map start time as a unix timestamp number (in seconds.)

Example Usage

local date_time = os.date("%c", core.MapStartTime())
DCEI.LogMessage("Map started at " .. date_time)
-- see: https://www.lua.org/pil/22.1.html for more on date/time

MapTime()

MapTime()

Returns the time elapsed since the map started in seconds.

Example Usage

local t = core.MapTime()
DCEI.LogMessage("Map has been played for " .. t .. " seconds)

GetGameSpeed()

GetGameSpeed()

Returns the current game speed (as set by SetGameSpeed()/ClearGameSpeed()).

Example Usage

DCEI.LogMessage("Game Speed is " .. core.GetGameSpeed())

SetGameSpeed()

SetGameSpeed( speed )

Sets the game speed. Game speed is clamped between 0 and 3.

This function uses a combination of DCEI.SetUpdateFrequency() and DCEI.SetSpeedFactor() to achieve the specified speed in one handy function.

Example Usage

local game_speed = core.GetGameSpeed()

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 128, 128)

local label = DCEI.CreateTextFrame(button)
DCEI.SetTextFrameText(label, game_speed)

local function CycleGameSpeed()
    -- cycles the game speed between 1, 2, and 3
    game_speed = core.Cycle(game_speed, 1, 1, 3)
    core.SetGameSpeed(game_speed)

    DCEI.SetTextFrameText(label, game_speed)
end

DCEI.SetOnClickCallback(button, CycleGameSpeed)

ClearGameSpeed()

ClearGameSpeed()

Resets the current game speed to 1 by clearing the game's update frequency and speed factor.

Example Usage

core.ClearGameSpeed()

Input

HookupJoystick()

HookupJoystick( unit )

Hooks up a joystick to a unit and hides the joystick offscreen. This function is intended to quickly test unit movement and provides no customization options. To create your own joystick movement system, see the Joystick Events.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local unit = DCEI.CreateUnit(1, 1, unit_type, 16, 16)

core.HookupJoystick(unit)

Math

atan2()

atan2( y, x )

Returns the arc tangent of x and y as a number in radians.

Example Usage

local v = core.VectorBetweenPoints(p1, p2)
local angle_between_points = core.atan2(v.y, v.x)

Clamp()

Clamp( n, min, max )

Clamps a number between the min and max values.

Example Usage

local values = {-10, 7, 23}
for index, value in ipairs(values) do
    values[index] = core.Clamp(value, 1, 10)
end
-- values = {1, 7, 10}

Cycle()

Cycle( value, increment, min, max )

Increments a value while keeping it in the given range. If the value would be greater than the max value, it is reset to the min instead.

Example Usage

local game_speed = core.GetGameSpeed()

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 128, 128)

local label = DCEI.CreateTextFrame(button)
DCEI.SetTextFrameText(label, game_speed)

local function CycleGameSpeed()
    -- cycles the game speed between 1, 2, and 3
    game_speed = core.Cycle(game_speed, 1, 1, 3)
    core.SetGameSpeed(game_speed)

    DCEI.SetTextFrameText(label, game_speed)
end

DCEI.SetOnClickCallback(button, CycleGameSpeed)

IsInt()

IsInt(n)

Returns true if a number is an integer.

Example Usage

IsInt(23)
-- true

IsInt(23.4)
-- false

Lerp()

Lerp( start, finish, fraction )

Linearly interpolates between start and finish number values using the specified fraction (0 - 1).

Example Usage

local start = 1
local finish = 255

core.Lerp(start, finish, 0.5)
-- returns midpoint value of 128

core.Lerp(start, finish, 0.75)
-- returns 75% interpolation of 191.5

Round()

Round( n, decimals )

Rounds a floating point value to the number of decimals specified. If no decimals value is given, the number will be rounded to the nearest whole number.

Example Usage

core.Round(1/3)
-- returns 0.0

core.Round(2/3)
-- returns 1.0

local decimals = 2
core.Round(2/3, decimals)
-- returns 0.67

Point

AngleBetweenPoints()

AngleBetweenPoints( p1, p2 )

Returns the angle between two points in degrees. The result will be between -180 and 180 as follows:

        90
        |
 180____|____ 0
-180    |
        |
       -90

Example Usage

local map_center_point = {x = 16, y = 16}
local unit_type = DCEI.Unit("Standard MeleeUnit")
local unit = DCEI.CreateUnit(1, 1, unit_type, 12, 12)

local pos = DCEI.GetUnitPosition2D(unit)
-- pos = {x = 12, y = 12}

local angle = core.AngleBetweenPoints(pos, map_center_point)
-- 45 degrees between spawned unit position and map center

AngleToVector()

AngleToVector( angle )

Returns an xy vector from an angle (in degrees).

Example Usage

local v = core.AngleToVector(45)
-- v is {x = 0.7, y = 0.7}

DCEI.TurnUnitTowardsWithDuration(unit, v.x, v.y, 1)

ArcDistanceBetweenAngles()

ArcDistanceBetweenAngles( angle1, angle2 )

Returns the angle between two angles. This value will be between 0 and 180.

Example Usage

function GetNearestFacingEnemy( unit, enemies )
    local unit_pos = DCEI.GetUnitPosition2D(unit)
    local unit_angle = core.GetUnitFacingAngle(unit)
    local nearest_angle = 180
    local nearest_enemy

    for _, enemy in pairs(enemies) do
        local enemy_pos = DCEI.GetUnitPosition2D(enemy)
        local enemy_angle = core.AngleBetweenPoints(unit_pos, enemy_pos)

        -- gets the angle between the unit-facing angle and the unit-to-enemy angle
        local angle = core.ArcDistanceBetweenAngles( unit_angle, enemy_angle )

        if angle < nearest_angle then
            nearest_enemy = enemy           
            nearest_angle = angle
        end
    end

    return nearest_enemy
end

DistanceBetweenPoints()

DistanceBetweenPoints( p1, p2 )

Returns the distance between two points.

Example Usage

local map_center_point = {x = 16, y = 16}
local unit_type = DCEI.Unit("Standard MeleeUnit")
local unit = DCEI.CreateUnit(1, 1, unit_type, 12, 12)

local pos = DCEI.GetUnitPosition2D(unit)
-- pos = {x = 12, y = 12}

local distance = core.DistanceBetweenPoints(pos, map_center_point)
-- distance = 5.65

InterpolatedPoint()

InterpolatedPoint( p1, p2, fraction )

Returns a point along the line between two points, determined by the given fraction (0 - 1).

Example Usage

local map_center_point = {x = 16, y = 16}
local unit_type = DCEI.Unit("Standard MeleeUnit")
local unit = DCEI.CreateUnit(1, 1, unit_type, 12, 12)

local pos = DCEI.GetUnitPosition2D(unit)
-- pos = {x = 12, y = 12}

local p1 = core.InterpolatedPoint(pos, map_center_point, 0)
-- p1 = {x = 12, y = 12}, the same as pos

local p2 = core.InterpolatedPoint(pos, map_center_point, 1)
-- p2 = {x = 16, y = 16}, the same as map_center_point

local p3 = core.InterpolatedPoint(pos, map_center_point, 0.5)
-- p3 = {x = 14, y = 14}, the midpoint between the two

PointFromXY()

PointFromXY( x, y )

Returns a point from x and y coordinates.

Example Usage

local map_center_point = core.PointFromXY(16, 16)
-- map_center_point = {x = 16, y = 16}

PointWithPolarOffset()

PointWithPolarOffset( x, y, angle, distance )

Returns a point offset by a distance towards an angle (in degrees).

Example Usage

local pos = DCEI.GetUnitPosition2D(unit)
local facing = core.GetUnitFacingAngle(unit)

local distance = 4
local forward_point = core.PointWithPolarOffset( pos.x, pos.y, facing, angle)

-- teleports a unit forward a distance of 4
DCEI.SetUnitPosition2D(unit, forward_point.x, forward_point.y)

VectorBetweenPoints()

VectorBetweenPoints( p1, p2 )

Returns an xy vector between two points.

Example Usage

local v = core.VectorBetweenPoints(p1, p2)
local angle_between_points = core.atan2(v.y, v.x)

Random

Random()

Random( min, max )

Returns a seed-based random float. The random number generator seed can be set with SetRandomSeed().

Example Usage

local random_number = core.Random(1, 100)
DCEI.LogMessage(random_number)
-- based on the default seed, this will always be 27.037

RandomInteger()

RandomInteger( min, max )

Returns a seed-based random integer. The random number generator seed can be set with SetRandomSeed().

Example Usage

for n = 1, 5 do
    local d20 = core.RandomInteger(1, 20)
    DCEI.LogMessage(d20)
end

-- based on the default seed, the first five rolls will always be:
-- 5, 20, 14, 1, 4

SetRandomSeed()

SetRandomSeed( seed )

Sets the seed for the random number generator. Use a static number (such as "wave number" or "level number") to generate the same random sequence (such as enemy spawn formation within a wave). Use a dynamic number (such as the time stamp given by os.time()) to generate new random numbers each time.

Example Usage

core.SetRandomSeed(1357056)

for n = 1, 5 do
    local d20 = core.RandomInteger(1, 20)
    DCEI.LogMessage(d20)
end
-- using this seed, the first five rolls will always be:
-- 1, 2, 3, 4, 5

String

FormatNumberDecimalPlaces()

FormatNumberDecimalPlaces( amount, decimals, round )

Returns a number as a string to the specified number of decimal places. Has an optional round parameter to round the number to the given decimal place.

Example Usage

local display = core.FormatNumberDecimalPlaces(0.989, 4)
-- display = "0.9890"

local round = true
local display = core.FormatNumberDecimalPlaces(0.989, 2, round)
-- display = "0.99"

FormatNumberToRomanNumeral()

FormatNumberToRomanNumeral( number)

Returns a string as the roman numeral representation of a number.

Example Usage

local display = core.FormatNumberToRomanNumeral(114)
-- display = "CXIV"

FormatNumberWithCommas()

FormatNumberWithCommas( amount )

Returns a number as a string formatted with commas.

Example Usage

local amount = 1234567
local display = core.FormatNumberWithCommas(amount)
-- display = "1,234,567"

local label = DCEI.CreateTextFrame(DCEI.GetUiRootFrame())
DCEI.SetTextFrameText(label, display)

FormatIntegerDigits()

FormatIntegerDigits( amount, digits )

Returns a number as a string with the minimum digits specified.

Example Usage

local display = core.FormatIntegerDigits(3, 2)
-- display = "03"

FormatTimeHours()

FormatTimeHours( time_in_seconds, decimals )

Returns a string formatted as "HH:MM:SS". Has an optional decimals parameter to display milliseconds.

Example Usage

local time_in_seconds = 7384.559
local display = core.FormatTimeHours(time_in_seconds, 2)
-- display = "02:03:04.56"

local label = DCEI.CreateTextFrame(DCEI.GetUiRootFrame())
DCEI.SetTextFrameText(label, display)

FormatTimeMinutes()

FormatTimeMinutes( time_in_seconds, decimals )

Returns a string formatted as "MM:SS. Has an optional decimals parameter to display milliseconds.

Example Usage

local time_in_seconds = 7384
local display = core.FormatTimeMinutes(time_in_seconds, 2)
-- display = "123:04.00"

local label = DCEI.CreateTextFrame  (DCEI.GetUiRootFrame())
DCEI.SetTextFrameText(label, display)

StripChars()

StripChars( str, chars)

Returns a string with the specified chars removed.

Example Usage

local display = core.StripChars("strip that string", "aeiou")
-- display = "strp tht strng"

Terrain

GetRandomPointInMap()

GetRandomPointInMap( args )

Returns a random point within the map bounds. Has table args with padding option (default 2) to shrink the random point area.

Example Usage

-- if the map has dimensions of 32 x 32 the point will be generated between (4, 4) and (27, 27)
-- note that for a map of 32 x 32 the playable dimensions will span (0, 0) to (31, 31)
local options = { padding = 2 }
local pos = core.GetRandomPointInMap(options)

local unit_type = DCEI.Unit("Standard MeleeUnit")
DCEI.CreateUnit(1, 1, unit_type, pos.x, pos.y)

Timers

Timers are useful for implementing various time-related gameplay functionality and using many timers is more performant than many DCEI Timer Events.

Creating a new timer by itself won't do anything, but they can be used in conjunction with the common timer methods to accomplish things such as tracking how much time it takes for players to clear a level or to refresh a shop item in 20 minutes.

There are three types of timers, each using the same methods. Each type of timer tracks time differently:

Timer Update

Game Timers and Real Timers update every 0.0625 seconds. You can change the global time update frequency with SetGlobalTimerTickRate. The update frequency for OsTimers is once per second and cannot be changed.

On each timer update, the timer will check its Condition—if true the timer will run its Action and then Destroy itself, if false the timer will run its Tick function instead. By default, a timer's Condition, Action, and Tick functions are all blank, but can be overwritten to provide additional functionality.

if timer:Condition() then
    timer:Action()
    timer:Destroy()
else
    timer:Tick()
end

GameTimer:New()

GameTimer:New( args )

Creates and returns a new Game timer from the given arguments. Unlike Real and Os timers, Game timers are affected by game speed. By default, Game timers update every 0.0625 seconds (this can be overriden with SetGlobalTimerTickRate).

Parameters

Example Usage

-- creates a timer that expires in 2 seconds and displays a log message when it expires
local timer_a = core.GameTimer:New()
timer_a.name = "Timer A"
timer_a:AddDuration(2)

function timer_a:Action()
    DCEI.LogMessage("[" .. self.name .. "] has expired")
end

-- timer_b does the same thing as timer_a, but written in the timer constructor
function OnTimerExpire(self)
    DCEI.LogMessage("[" .. self.name .. "] has expired")
end

local timer_b = core.GameTimer:New({ duration = 2, action = OnTimerExpire })
timer_b.name = "Timer B"

RealTimer:New()

RealTimer:New( args )

Creates and returns a new Real timer from the given arguments. Similar to Os timers, Real timers are not affected by game speed. By default, Real timers update every 0.0625 seconds (this can be overridden with SetGlobalTimerTickRate).

Parameters

Example Usage

-- creates an indefinite timer that logs time elapsed each tick
local real_timer = core.RealTimer:New()

function real_timer:Tick()
    local decimals = 2
    local time_elapsed = self:GetTimeElapsed()
    local formatted_time = core.FormatTimeMinutes(time_elapsed, decimals)
    DCEI.LogMessage("Time Elapsed: " .. formatted_time)
end

OsTimer:New()

OsTimer:New( args )

Creates and returns a new Os timer from the given arguments. Similar to Real timers, Os timers are not affected by game speed. Os timers update every 1.0 seconds, using the precision of os.time().

If the game is running in the background (ie, on mobile devices), Os timers will update when the game is moved to the foreground and update based on the time that passed. If a timer would have expired while the game was running in the background, it will instead expire on the first frame after the game is resumed. This makes Os timers suitable for classic mobile game timers.

Note that since Os timers rely on the device's system clock, they can be manipulated by changing the device's system clock.

Parameters

Example Usage

-- creates a timer that expires after 60 seconds and displays a message when it expires
local os_timer = core.OsTimer:New({ duration = 60 })

function os_timer:Action()
    DCEI.LogMessage("Os Timer Expired")
end

SetGlobalTimerTickRate()

SetGlobalTimerTickRate( value )

Used to set the global tick rate of Game and Real timers (default is 0.0625 seconds). The global tick rate must be set before any timers are created to take effect. It may be useful to lower the global tick rate (in increments of 1/16 seconds) to improve performance, particularly if you're using complex timer conditions.

Example Usage

core.SetGlobalTimerTickRate(0.25)

local real_timer = core.RealTimer:New()

function real_timer:Tick()
    local decimals = 2
    local time_elapsed = self:GetTimeElapsed()
    local formatted_time = core.FormatTimeMinutes(time_elapsed, decimals)
    DCEI.LogMessage("Time Elapsed: " .. formatted_time)
end

Timer Methods

Timer:AddDuration()

Timer:AddDuration( duration )

Adds time (in seconds) to the timer's duration and sets the timer's Condition to expire when the timer's time remaining reaches 0. When the timer expires it will run its Action and then be Destroyed.

Example Usage

local timer = core.GameTimer:New()
timer:AddDuration(2)

Timer:SetDuration()

Timer:SetDuration( duration )

Sets the timer's duration (in seconds) and sets the timer's Condition to expire when the timer's time remaining reaches 0. When the timer expires it will run its Action and then be Destroyed.

Example Usage

local timer = core.GameTimer:New()
timer:AddDuration(2)

Timer:Destroy()

Timer:Destroy()

Destroys a timer and stops it from updating.

Example Usage

local timer = core.RealTimer:New()

function timer:Tick()
    local decimals = 2
    local time_elapsed = self:GetTimeElapsed()
    local formatted_time = core.FormatTimeMinutes(time_elapsed, decimals)
    DCEI.LogMessage("Time Elapsed: " .. formatted_time)
end

DCEI.TriggerAddTimerEventElapsed(
    function()
        timer:Destroy()
    end, 
    2, true
)

Timer:GetTimeElapsed()

Timer:GetTimeElapsed()

Returns how long the timer has been active (in seconds).

Example Usage

local timer = core.RealTimer:New()

function timer:Tick()
    local decimals = 2
    local time_elapsed = self:GetTimeElapsed()
    local formatted_time = core.FormatTimeMinutes(time_elapsed, decimals)
    DCEI.LogMessage("Time Elapsed: " .. formatted_time)
end

Timer:GetTimeRemaining()

Timer:GetTimeRemaining()

Returns how long until the timer expires (in seconds). If no duration has been sit, this will return nil.

Example Usage

local timer = core.RealTimer:New({ duration = 3 })

function timer:Tick()
    local decimals = 2
    local time_remaining = self:GetTimeRemaining()
    local formatted_time = core.FormatTimeMinutes(time_remaining, decimals)
    DCEI.LogMessage("Time Remaining: " .. formatted_time)
end

Timer:SetPaused()

Timer:SetPaused( flag )

Pauses a timer if flag is true or unpauses a timer if flag is false. Paused timers don't update or expire.

Example Usage

-- this timer will ultimately expire after 4 seconds, since we pause it for 1 second
local timer = core.RealTimer:New({ duration = 3 })

function timer:Tick()
    local decimals = 2
    local time_elapsed = self:GetTimeElapsed()
    local formatted_time = core.FormatTimeMinutes(time_elapsed, decimals)
    DCEI.LogMessage("Time Elapsed: " .. formatted_time)
end


DCEI.TriggerAddTimerEventElapsed(
    function()
        timer:SetPaused(true)
    end, 
    2, true
)

DCEI.TriggerAddTimerEventElapsed(
    function()
        timer:SetPaused(false)
    end, 
    3, true
)

Timer:Condition()

Timer:Condition()

This function is evaluated each timer update to determine if the timer should expire. By default this function is blank, but can be overwritten to provide additional functionality.

Adding a duration to a timer will overwrite the condition to return true when the time remaining becomes 0.

Since timer conditions can be checked many times per second, it's best practice for performance if they are simple comparisons.

Example Usage

local hero = DCEI.CreateUnit(1, 1, DCEI.Unit("Standard MeleeUnit"), 16, 16)

local timer = core.RealTimer:New()

function timer:Condition()
    return not DCEI.UnitIsAlive(hero)
end

function timer:Action()
    local time_elapsed = self:GetTimeElapsed()
    DCEI.LogMessage("Hero survived for " .. time_elapsed .. " seconds")
end

local random_duration = core.Random(2, 5)
DCEI.TriggerAddTimerEventElapsed(
    function()
        DCEI.KillUnit(hero)
    end, 
    random_duration, true
)

Timer:Action()

Timer:Action()

This function is called if the timer's Condition evaluates as true when the timer updates. By default this function is blank, but can be overwritten to provide additional functionality.

Example Usage

local hero = DCEI.CreateUnit(1, 1, DCEI.Unit("Standard MeleeUnit"), 16, 16)

local timer = core.RealTimer:New()

function timer:Condition()
    return not DCEI.UnitIsAlive(hero)
end

function timer:Action()
    local time_elapsed = self:GetTimeElapsed()
    DCEI.LogMessage("Hero survived for " .. time_elapsed .. " seconds")
end

local random_duration = core.Random(2, 5)
DCEI.TriggerAddTimerEventElapsed(
    function()
        DCEI.KillUnit(hero)
    end, 
    random_duration, true
)

Timer:Tick()

Timer:Tick()

This function is called if the timer's Condition evaluates as false when the timer updates. By default this function is blank, but can be overwritten to provide additional functionality.

Since timer ticks can run many times per second, it's best practice for perfromance if they are simple actions.

Example Usage

local timer = core.RealTimer:New({ duration = 3 })

function timer:Tick()
    local decimals = 2
    local time_remaining = self:GetTimeRemaining()
    local formatted_time = core.FormatTimeMinutes(time_remaining, decimals)
    DCEI.LogMessage("Time Remaining: " .. formatted_time)
end

UI

FadeIn()

FadeIn( duration, color )

Fades the screen in over the duration (in seconds). An optional color can be set for the fade (default black {0, 0, 0, 1}).

Example Usage

-- fade to white over 1 second
local white = {1, 1, 1}
core.FadeOut(1, white)

-- pause for an additional second after fading out
DCEI.Wait(2)

-- fade in from white over 1 second
core.FadeIn(1, white)

FadeOut()

FadeOut( duration, color )

Fades the screen out over the duration (in seconds). An optional color can be set for the fade (default black {0, 0, 0, 1}).

Example Usage

local white = {1, 1, 1}
core.FadeOut(1, white)
DCEI.Wait(2)
core.FadeIn(1, white)

HideDefaultUi()

HideDefaultUi()

Hides the default gold display, wave display, and speed up buttons used in Wild Sky TD.

Example Usage

core.HideDefaultUi()

Unit

DamageUnit()

DamageUnit( unit, amount )

Deals damage to a unit (without a caster).

Example Usage

core.DamageUnit(unit, 5)

GetUnitId()

GetUnitId( unit )

Returns a unique unit id as a string, which is useful for data binding. The returned id will never change and never be associated with another unit.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local unit = DCEI.CreateUnit(1, 1, unit_type, 16, 16)

-- returns an id such as "u4x1xxx4"
local id = core.GetUnitId(unit)
DCEI.BindUnitData(id, unit)

GetUnitFacingAngle()

GetUnitFacingAngle( unit )

Returns the facing angle of the unit. The result will be between -180 and 180 as follows:

        90
        |
 180____|____ 0
-180    |
        |
       -90

Example Usage

local pos = DCEI.GetUnitPosition2D(unit)
local facing = core.GetUnitFacingAngle(unit)

local distance = 4
local forward_point = core.PointWithPolarOffset( pos.x, pos.y, facing, angle)

-- teleports a unit forward a distance of 4
DCEI.SetUnitPosition2D(unit, forward_point.x, forward_point.y)

MakeUnitFaceAngle()

MakeUnitFaceAngle( unit, angle, duration )

Sets a unit's rotation to the specified angle (in degrees) over the duration. A duration of 0 will turn the unit instantly.

Example Usage

-- makes the unit instantly turn 90 degrees clockwise
local facing = core.GetUnitFacingAngle(unit)

facing = facing - 90
core.MakeUnitFaceAngle(unit, facing, 0)

MakeUnitFacePoint()

MakeUnitFacePoint( unit, x, y, duration )

Sets a unit's rotation towards the specified point over the duration. A duration of 0 will turn the unit instantly.

Example Usage

local pos = DCEI.GetUnitPosition2D(other_unit)

-- makes the unit face the other_unit over 0.5 seconds
core.MakeUnitFacePoint(unit, pos.x, pos.y, 0.5)

SetBehaviorCount()

SetBehaviorCount( unit, behavior, count )

Sets the stack count of a behavior on the unit.

Example Usage

local behavior = DCEI.Behavior("Damage Taken None")
core.SetBehaviorCount(unit, behavior, 1)

UnitHoldPosition()

UnitHoldPosition( unit )

Makes a unit with a movement order stop moving. Does not affect the targeting or firing of weapons and abilities.

Example Usage

core.UnitHoldPosition(unit)

SendActorMessage()

SendActorMessage( unit, action, ... )

Sends an actor message to the specified unit. This function a variable number of arguments depending on the parameter of the actor message. Available actions and their parameters are listed in supported actions below. Note that the parameters are listed in order.

See actor actions for details of each actor action.

Supported Actions

Example Usage

-- tints the unit bright red and plays its attack animation over 2 seconds
core.SendActorMessage(unit, "setTintColor", {255, 0, 0})
core.SendActorMessage(unit, "playAnimationWithDuration", "attack", 2)

Utility

These utility functions are mostly comprised of helper functions for table management. Consider brushing up on your table knowledge before diving into these.

AddToTableValue()

AddToTableValue( table_arg, key, amount )

Adds the amount to the table entry for the given key. Negative values are accepted. If the key doesn't exist, a new entry will be created with the amount.

Example Usage

local fruits = {
    bananas = 2,
    apples = 3
}

core.AddToTableValue(fruits, "bananas", 4)
-- fruits.bananas = 6

AddToProtectedValue()

AddToProtectedValue( key, amount )

Adds the amount to the protected value for the given key. Negative values are accepted. If the key doesn't exist, a new protected value will be created with the amount (though you will get a log error for attempting to read a non-existent key). Note that it is good practice to initialize protected value keys on map start.

Example Usage

local protected_keys = { gems = "gems", gold = "gold" }
for _, key in pairs(protected_keys) do
    DCEI.SetProtectedValue(key, 0)
end

core.AddToProtectedValue(protected_keys.gems, 10)
local gems = DCEI.GetProtectedValue(protected_keys.gems)
-- gems = 10

Dump()

Dump( object )

Returns a string printout of an unpacked table (including all nested tables). Note that nil values won't be included. Useful for quickly debugging tables.

Example Usage

local mixed_table = {
    count = 42,
    yee = "haw",
    subtable = {
        negative = false,
        nix = nil,
        func = function() return 0 end
    }
}

local print = core.Dump(mixed_table)
DCEI.LogMessage(print)
-- logs: { ["count"] = 42,["subtable"] = { ["func"] = function: 0000018EF9B4AB70,["negative"] = false,} ,["yee"] = haw,}

DumpSimple()

DumpSimple( object )

Returns string printout of an unpacked table without unpacking nested tables. Note that nil values won't be included. Useful for quickly debugging tables.

Example Usage

local mixed_table = {
    count = 42,
    yee = "haw",
    subtable = {
        negative = false,
        nix = nil,
        func = function() return 0 end
    }
}

local print = core.DumpSimple(mixed_table)
DCEI.LogMessage(print)
-- logs: { ["count"] = 42,["subtable"] = table: 0000018EFC6C4190,["yee"] = haw,}

LogDump()

LogDump( object )

Logs the result of Dump with DCEI.LogMessage().

Example Usage

local array = { 4, 8, 15, 16, 23, 42 }
core.LogDump(array)
-- logs: { [1] = 4,[2] = 8,[3] = 15,[4] = 16,[5] = 23,[6] = 42,}

LogDumpSimple()

LogDumpSimple( object )

Logs the result of DumpSimple with DCEI.LogMessage().

Example Usage

local array = { 4, 8, 15, 16, 23, 42, poorly_formatted_nested_table = { 1, 2, 3} }
core.LogDumpSimple(array)
-- logs: { [1] = 4,[2] = 8,[3] = 15,[4] = 16,[5] = 23,[6] = 42,["poorly_formatted_nested_table"] = table: 0000018EFCA12490,}

ClearTable()

ClearTable( table_arg )

Removes all keys from the given table. This is useful for resetting table values while preserving table references.

Example Usage

local bar = {}
local baz = {}

for i = 1, 3 do
    table.insert(baz, i)
    table.insert(bar, i)
end

local foo = {
    bar = bar,
    baz = baz
}

DCEI.LogMessage(#foo.bar .. ", " .. #foo.baz)
-- logs: "3, 3"

bar = {}
core.ClearTable(baz)

for i = 1, 4 do
    table.insert(baz, i)
    table.insert(bar, i)
end

DCEI.LogMessage(#foo.bar .. ", " .. #foo.baz)
-- logs: "3, 4"
-- by re-initializing `bar` as a new table, we broke the refrence between `bar` and `foo.bar`
-- meanwhile ClearTable() allows us to delete a table's keys without breaking such references

CombineTables()

CombineTables( table1, table2 )

Returns a new table as a combined list of the values of each input table. Note that this should be used with lists and not dictionaries.

Example Usage

local abc = { "a", "b", "c" }
local def = { "d", "e", "f" }

local abcdef = core.CombineTables(foo, bar)
-- abcdef = { "a", "b", "c", "d", "e", "f" }

CopyAndShuffleTable()

CopyAndShuffleTable( table_arg )

Returns a new table with the shuffled values of the input table. Note that this should be used with lists and not dictionaries.

Example Usage

local deck = { "clubs", "diamonds", "hearts", "spades" }

local shuffled_deck = core.CopyAndShuffleTable(deck)
-- shuffled_deck = { "hearts", "spades", "diamonds", "clubs" }

DeepCopyTable()

DeepCopyTable( table_arg )

Returns a new table as a copy of the input table, using copies of any nested tables from the original.

Example Usage

local original = {
  foo = { 1, 2, 3 }
}

local deep_copy = core.DeepCopyTable(original)
table.insert(deep_copy.foo, 4)

DCEI.LogMessage(#original.foo .. ", " .. #deep_copy.foo)
-- logs: "3, 4"

ShallowCopyTable()

ShallowCopyTable( table_arg )

Returns a new table as a copy of the input table, using references to any nested tables from the original.

Example Usage

local original = {
  foo = { 1, 2, 3 }
}

local shallow_copy = core.ShallowCopyTable(original)
table.insert(shallow_copy.foo, 4)

DCEI.LogMessage(#original.foo .. ", " .. #shallow_copy.foo)
-- logs: "4, 4"

GetAllKeys()

GetAllKeys( table_to_gather )

Returns a table as a list of keys from the input table.

Example Usage

local event_table = {
    event01 = "WaveStart",
    event02 = "WaveWin",
    event03 = "WaveLoss",
    event04 = "WaveRewards"
}

local keys = core.GetAllKeys(event_table)
-- keys = { "event01", "event02", "event03", "event04" }
-- note that the collapsed list may not be in the order of the original key-pair values

GetAllValues()

GetAllValues( table_to_gather )

Returns a table as a list of values from the input table.

Example Usage

local event_table = {
    event01 = "WaveStart",
    event02 = "WaveWin",
    event03 = "WaveLoss",
    event04 = "WaveRewards"
}

local values = core.GetAllValues(event_table)
-- keys = { "WaveStart", "WaveWin", "WaveLoss", "WaveRewards" }
-- note that the collapsed list may not be in the order of the original key-pair values

MergeTables()

MergeTables( table1, table2 )

Returns a new table of the combined key-pair values of each input table. Any overlapping keys will be overwritten by value of the second input table.

Example Usage

local hero_template = {
    strength = 8,
    agility = 8,
    intellect = 8,
    speed = 2,
}
local hero_data = {
    name = "Wind Knight",
    agility = 12,
    abilities = { "Wind Slash" }
}

local wind_knight = core.MergeTables(hero_template, hero_data)

-- wind_knight = {
--     name = "Wind Knight",
--     strength = 8,
--     agility = 12,
--     intellect = 8,
--     speed = 2,
--     abilities = { "Wind Slash" }
-- }

TableContains()

TableContains( table_arg, value )

Returns true if the table contains the given value.

Example Usage

local equipment = { "sword", "shield", "helmet" }

local has_shield = core.TableContains(equipment, "shield")
-- returns true

TableIsEmpty()

TableIsEmpty( table_arg )

Returns true if the table is empty

Example Usage

local empty_table = {}
local other_table = { false }

local is_empty = core.TableIsEmpty(empty_table)
-- returns true

local is_empty = core.TableIsEmpty(other_table)
-- returns false

TableLength()

TableLength( table_arg )

Returns the number of values of a table.

Example Usage

local event_table = {
    event01 = "WaveStart",
    event02 = "WaveWin",
    event03 = "WaveLoss",
    event04 = "WaveRewards"
}

local length = core.TableLength(event_table)
-- length = 4

RandomTableIndex()

RandomTableIndex( roll_table )

Returns a random index/key from the given (list/dictionary) table.

Example Usage

local deck = { "clubs", "diamonds", "hearts", "spades" }

local random_deck_index = core.RandomTableIndex(deck)
-- returns a random value between 1 and 4

RandomTableIndexNoRepeat()

RandomTableIndexNoRepeat( roll_table )

Returns a random index/key from the given (list/dictionary) table. Will never return the same index twice in a row for tables with size greater than 1.

Example Usage

local deck = { "clubs", "diamonds", "hearts", "spades" }

local random_deck_index = core.RandomTableIndexNoRepeat(deck)
-- returns a random value between 1 and 4
-- subsequent rolls will never repeat the same value twice in row

RandomTableValue()

RandomTableValue( roll_table )

Returns a random value from the given table.

Example Usage

local deck = { "clubs", "diamonds", "hearts", "spades" }

local random_card_suit = core.RandomTableValue(deck)
-- returns a random card suit

RandomTableValueNoRepeat()

RandomTableValueNoRepeat( roll_table )

Returns a random value from the given table. Will never return the same value index twice in a row for tables with size greater than 1.

Example Usage

local deck = { "clubs", "diamonds", "hearts", "spades" }

local random_card_suit = core.RandomTableValueNoRepeat(deck)
-- returns a random card suit
-- subsequent rolls will never repeat the same value twice in row