---

Trigger API Reference\DCEI Types

YogaFlexDirection

Enum YogaFlexDirection

Enum Structure

Column
ColumnReverse
Row
RowReverse

Description

Used for the flex frame property FlexDirection, see:

• flexDirection
• DCEI.SetFrameFlexDirection
  

Example Usage

XML "FlexLayout":

<Frame layout="flex">
    <Frame frameImageColor="#ff0000ff" width="50" height="50" />
    <Frame frameImageColor="#00ff00ff" width="50" height="50" />
</Frame>

Lua:

local GMUI = require("GMUI")

local function TestFlexProperty()
    local NewFlexLayout = GMUI.Layout.New({ name = "FlexLayout" })
    DCEI.SetFrameFlexDirection(NewFlexLayout.Frame, "column")
end

TestFlexProperty()

YogaWrap

Enum YogaWrap

Enum Structure

NoWrap
Wrap
WrapReverse

Description

Used for the flex frame property FlexDirection, see:

• flexWrap
• DCEI.SetFrameFlexWrap
  

Example Usage

XML "FlexLayout":

<Frame layout="flex" width="200" >
    <Frame id="child1" frameImageColor="#ff0000ff" widthPercent="100" height="50" />
    <Frame id="child2" frameImageColor="#00ff00ff" widthPercent="100" height="50" />
</Frame>

Lua:

local GMUI = require("GMUI")

local function TestFlexProperty()
    local NewFlexLayout = GMUI.Layout.New({ name = "FlexLayout" })
    DCEI.SetFrameFlexWrap(NewFlexLayout.Frame, "wrap")
end

TestFlexProperty()

YogaJustify

Enum YogaJustify

Enum Structure

FlexStart
Center
FlexEnd
SpaceBetween
SpaceAround

Description

This defines the alignment along the main axis. For more info (including visualizations of each property) see justifyContent XML attribute.. See also DCEI.SetFrameJustifyContent.

Example Usage

XML "FlexLayout":

<Frame layout="flex" width="200">
    <Frame id="child1" frameImageColor="#ff0000ff" width="50" height="50" />
    <Frame id="child2" frameImageColor="#00ff00ff" width="50" height="50" />
</Frame>

Lua:

local GMUI = require("GMUI")

local function TestFlexProperty()
    local NewFlexLayout = GMUI.Layout.New({ name = "FlexLayout" })
    DCEI.SetFrameJustifyContent(NewFlexLayout.Frame, "space-between")
end

TestFlexProperty()

YogaAlign

Enum YogaAlign

Enum Structure

Auto
FlexStart
Center
FlexEnd
Stretch
Baseline
SpaceBetween
SpaceAround

Description

This defines the default behavior for how flex items are laid out along the cross axis on the current line. Think of it as the justify-content version for the cross-axis (perpendicular to the main-axis).

For more info (including visualizations of each property) see alignItems XML attribute.

Example Usage

<Frame layout="flex" width="200">
    <Frame id="child1" frameImageColor="#ff0000ff" width="50" height="150" />
    <Frame id="child2" frameImageColor="#00ff00ff" width="50" height="50" />
</Frame>

Lua:

local GMUI = require("GMUI")

local function TestFlexProperty()
    local NewFlexLayout = GMUI.Layout.New({ name = "FlexLayout" })
    DCEI.SetFrameAlignItems(NewFlexLayout.Frame, "center")
end

TestFlexProperty()

YogaPositionType

Enum YogaPositionType

Enum Structure

Relative
Absolute

Description

Position Relative or Absolute.

Relative By default an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

Absolute When positioned absolutely an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

For more info see position XML attribute.

Example Usage

<Frame layout="flex" width="200" height="200" flexWrap="wrap">
    <Frame id="child1" frameImageColor="#ff0000ff" widthPercent="50" height="55" />
    <Frame id="child2" frameImageColor="#00ff00ff" widthPercent="50" height="55" />
</Frame>

Lua:

local GMUI = require("GMUI")

local function TestFlexProperty()
    local NewFlexLayout = GMUI.Layout.New({ name = "FlexLayout" })
    DCEI.SetFramePosition(NewFlexLayout.child1, "Absolute")
    DCEI.SetFrameLeft(NewFlexLayout.child1, 150)
end

TestFlexProperty()

FullScreenMode

Enum FullScreenMode

Enum Structure

ExclusiveFullScreen
FullScreenWindow
MaximizedWindow
Windowed

Description

ExclusiveFullScreen
An exclusive full-screen mode where the application takes complete control of the screen, hiding other windows and overlays. Stretches the screen if the resolution does not fit.

FullScreenWindow
A windowed version of the FullScreen mode. If the resolution is too small and the ratio doesn't match the screen, it creates black borders.

MaximizedWindow
Emulates the FullScreen mode by stretching the window borders to fit the entire screen. Functionally similar to FullScreenWindow.

Windowed
Starts the game in its own window.

Example Usage

DCEI.SetResolution(1000, 500, "Windowed")
-- Logs after a timer so the game has time to update.
DCEI.TriggerAddTimerEventElapsed(function()
    local resolution = DCEI.GetCurrentResolution()
    DCEI.LogMessage("Width: " .. resolution.width)
    DCEI.LogMessage("Height: " .. resolution.height)
    DCEI.LogMessage("Mode: " .. resolution.mode)
end, 0)

Related

SetResolution
GetCurrentResolution

UnitBehaviorStatus

Type UnitBehaviorStatus

Type Structure

UnitBehaviorStatus
{
string name
int stack_count
}

Description

Unit's behavior stats, including behavior name and stack count.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 16, 16
local test_subject = DCEI.CreateUnit(team_id, player_id, unit_type, x, y)
local behavior_name = DCEI.Behavior("Damage Taken Half")

DCEI.ApplyBehaviorToSelf(test_subject, behavior_name, 2)

local stacks = DCEI.GetUnitBehaviorStackCount(test_subject, behavior_name)

DCEI.LogMessage(unit_type .. " has " .. stacks .. " stacks of " .. behavior_name)

BehaviorFilter

Type BehaviorFilter

Type Structure

BehaviorFilter
{
string name
string family
}

Description

Behavior Filters allow you to create a filter for trigger events such as TriggerAddBehaviorStackIncreaseEvent that make the event only fire for specific behavior type instead of all behaviors. See Using Trigger Event Filters

Example Usage

-- Create unit
local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 16, 16
local test_subject = DCEI.CreateUnit(team_id, player_id, unit_type, x, y)
local behavior_name = DCEI.Behavior("Damage Taken Half")

function OnUnitBehaviorAdd(effect_context)
    local name = DCEI.TriggeringBehaviorName
    local u = DCEI.TriggeringUnit
    local unit_type = DCEI.GetUnitType(u)
    local stacks = DCEI.GetUnitBehaviorStackCount(u, name)
    DCEI.LogMessage(unit_type .. " had " .. name .. " added for a total of " .. stacks .. " stacks.")
end

local behavior_filter = { name = behavior_name }
DCEI.TriggerAddBehaviorAddEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitBehaviorAdd, true, behavior_filter)

DCEI.ApplyBehaviorToSelf(test_subject, behavior_name, 2)

AbilityFilter

Type AbilityFilter

Type Structure

AbilityFilter
{
string name
string family
}

Description

Ability Filters allow you to create a filter for trigger events such as TriggerAddCastAbilityEvent that make the event only fire for specific a specific ability type instead of all abilities. See Using Trigger Event Filters

Example Usage

function OnAbilityCast(target_unit, target_pos)
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local ability_name = DCEI.TriggeringAbilityName
    DCEI.LogMessage(unit_name .. " casts " .. ability_name)

    local target_name = DCEI.GetUnitType(target_unit)
    DCEI.LogMessage("Target: " .. target_name .. " at (" .. target_pos.x .. ", " .. target_pos.y .. ")")
end

local ability_filter = { name = "Ability Fireball" }
DCEI.TriggerAddUseAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityCast, true, ability_filter)

WeaponFilter

Type WeaponFilter

Type Structure

WeaponFilter
{
string name
string family
}

Description

Weapon Filters allow you to create a filter for trigger events such as TriggerAddUseWeaponEvent that make the event only fire for specific a specific weapon type instead of all weapons. See Using Trigger Event Filters

Example Usage

local function OnUnitUseWeapon(target_unit, target_pos)
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local weapon = DCEI.TriggeringWeaponName
    DCEI.LogMessage(unit_name .. " has attacked with " .. weapon ..".")

    local target_name = DCEI.GetUnitType(target_unit)
    DCEI.LogMessage("Target: " .. target_name .. " at (" .. target_pos.x .. ", " .. target_pos.y .. ")")
end

local weapon_filter = { name = "Weapon Bow" }
DCEI.TriggerAddUseWeaponEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitUseWeapon, true, weapon_filter)

CriticalFilter

Type CriticalFilter

Type Structure

CriticalFilter
{
bool critical_only
bool not_critical_only
}

Description

Used to make events like TriggerAddUnitDamageEvent trigger with only critical or not critical damage events. See Using Trigger Event Filters

Example Usage

local function OnUnitDamaged(damage, target_unit)
    DCEI.ShowSimpleDamageNumber(target_unit, 1, damage)
end

DCEI.TriggerAddUnitDamageEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitDamaged, {critical_only = true})

UnitTagStatus

Type UnitTagStatus

Type Structure

UnitTagStatus
{
string name
int stack_count
}

Description

Tag status on unit, with name and stack count.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 16, 16
local unit = DCEI.CreateUnit(team_id, player_id, unit_type, x, y)
local tag = DCEI.Tag("Banana")

DCEI.ApplyTag(unit, tag, -1, 5)
local tag_count = DCEI.GetUnitTagCount(unit, tag)
DCEI.LogMessage(tag_count)


DCEI.RemoveTag(unit, tag, 2)
tag_count = DCEI.GetUnitTagCount(unit, tag)
DCEI.LogMessage(tag_count)

UnitFilter

Type UnitFilter

Type Structure

UnitFilter
{
Nullable<int> playerId
Nullable<int> team
string name
string tag
}

Description

Creates a filter for a specific unit type, which can be used with any trigger event API (like DCEI.TriggerAddUnitSelectedEvent) that accepts a unit as a parameter. This filter will then cause the event to register only for this specific unit type rather than all unit types. See Using Trigger Event Filters

Example Usage

-- Called when any enemy unit spawns or dies
local enemy_unit_filter = DCEI.CreateUnitFilter({ team = -1 })
DCEI.TriggerAddUnitSpawnEvent(enemy_unit_filter, function() DCEI.LogMessage("Enemy unit spawned") end, false)
DCEI.TriggerAddUnitDiedEvent(enemy_unit_filter, function() DCEI.LogMessage("Enemy unit died") end, false)

-- Called when any player unit spawns or dies
local player_unit_filter = DCEI.CreateUnitFilter({ team = 1 })
DCEI.TriggerAddUnitSpawnEvent(player_unit_filter, function() DCEI.LogMessage("Player unit spawned") end, false)
DCEI.TriggerAddUnitDiedEvent(player_unit_filter, function() DCEI.LogMessage("Player unit died") end, false)

-- Called when any "Test Unit" unit spawns or dies
local test_unit_filter = DCEI.CreateUnitFilter({ name = DCEI.Unit("Test Unit") })
DCEI.TriggerAddUnitSpawnEvent(test_unit_filter, function() DCEI.LogMessage("Test Unit spawned") end, false)
DCEI.TriggerAddUnitDiedEvent(test_unit_filter, function() DCEI.LogMessage("Test Unit died") end, false)

-- Called when player "Test Unit" unit spawns or dies
local player_test_unit_filter = DCEI.CreateUnitFilter({ team = 1, name = DCEI.Unit("Player Test Unit") })
DCEI.TriggerAddUnitSpawnEvent(player_test_unit_filter, function() DCEI.LogMessage("Player Test Unit spawned") end, false)
DCEI.TriggerAddUnitDiedEvent(player_test_unit_filter, function() DCEI.LogMessage("Player Test Unit died") end, false)

-- How to register multiple player units
local names = { DCEI.Unit("Ghost Inky"), DCEI.Unit("Ghost Blinky"), DCEI.Unit("Ghost Stinky") }
for _, name in ipairs(names) do
    local unit_filter = DCEI.CreateUnitFilter({ team = 1, name = name })
    DCEI.TriggerAddUnitSpawnEvent(unit_filter, function() DCEI.LogMessage(name .. " spawned") end, false)
    DCEI.TriggerAddUnitDiedEvent(unit_filter, function() DCEI.LogMessage(name .. " died") end, false)
end

Unit

Type Unit

Type Structure

Unit
{
Entity UnsafeEntity
UnitFilter filter
}

Description

A Unit instance. Create a Unit Type in the Data window of the editor, and then place them on the terrain or create them via Lua using apis like DCEI.CreateUnit to create a Unit instance.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local unit_instance = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)

DCEI.RemoveUnit(unit_instance)

Region

Type Region

Type Structure

Region
{
Entity UnsafeEntity
}

Description

A region is an area of the in-game level, similar to an area search but permanent.

Example Usage

local region = DCEI.CreateRegion(16, 16, 4, 4)

function OnRegionEnter()
    DCEI.SetUnitOwner(DCEI.TriggeringUnit, 2)
    DCEI.LogMessage(DCEI.GetUnitPlayerId(DCEI.TriggeringUnit))
end

DCEI.TriggerAddUnitEnterRegionEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), region, OnRegionEnter)

Float2

Type Float2

Type Structure

Float2
{
float x
float y
}

Description

Usually use for Position 2D.

Example Usage

local pos = {x = 1, y = 1}
DCEI.SetUnitPosition2D(unit, pos.x, pos.y)

AbilityCost

Type AbilityCost

Type Structure

AbilityCost
{
float health
float mana
float gold
}

Description

Ability cost table.

Example Usage

function OnAbilityUse()
    local id = DCEI.TriggeringAbilityId
    local name = DCEI.TriggeringAbilityName
    DCEI.LogMessage(name .. " use")
    local cost = DCEI.GetAbilityCost(name)
    for key, value in pairs(cost) do
        DCEI.LogMessage(key .. " : " .. value)
    end
end

DCEI.TriggerAddUseAbilityEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnAbilityUse)

Related

GetAbilityCost

BehaviorModifier

Type BehaviorModifier

Type Structure

BehaviorModifier
{
float scaled
float unscaled
float additive_factor
float positive_unified_factor
float negative_unified_factor
float multiplier_factor
}

Description

Works in the same way as BehaviorModifier in behavior data.

Example Usage

local example_value = DCEI.ApplyModifier(
    {
        scaled = 5,
        unscaled = 0,
        additive_factor = 1,
        positive_unified_factor = 1,
        negative_unified_factor = 0,
        multiplier_factor = 1,
    },
    5
)
DCEI.LogMessage(example_value)

Related

ApplyModifier

Damage

Type Damage

Type Structure

Damage
{
float damage_value
int style_index
int damage_type
float critical_damage_chance
float critical_damage_multiplier
int critical_damage_style_index
string stats_name
float duration_seconds
}

Description

Used for simple unit damage affinity.

Example Usage

In-develepment API
No example use yet

Float3

Type Float3

Type Structure

Float3
{
float x
float y
float z
}

Description

Can be used as Position 3D or Scale 3D.

Example Usage

local duration = 1
local ease = "Linear"
local k1 = {x = min_scale, y = min_scale, z = min_scale}
local k2 = {x = max_scale, y = max_scale, z = max_scale}
local anim = DCEI.AnimateFrameScale(layout.Frame, k1, k2, duration, ease)

EffectContext

Type EffectContext

Type Structure

EffectContext
{
unit caster
unit source
unit target
Float2 target_location
string damage_source_type
string damage_source_name
float return_value
}

Description

Get effect's context.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 16, 17
local test_subject = DCEI.CreateUnit(team_id, player_id, unit_type, x, y)
local behavior_name = DCEI.Behavior("Damage Taken Half")

local function OnUnitBehaviorAdd(effect_context)
    DCEI.LogMessage(
        "target location x: "
            .. effect_context.target_location.x
            .. " target location y: "
            .. effect_context.target_location.y
    )
end

DCEI.TriggerAddBehaviorAddEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitBehaviorAdd, true)
DCEI.ApplyBehaviorToSelf(test_subject, behavior_name, 2)

UnitLabelOptions

Type UnitLabelOptions

Type Structure

UnitLabelOptions
{
Offset offset
bool center_at_unit_origin
bool center_at_unit_top
}

Description

Built in unit label option table.

Example Usage

local label_options = {offset = {right = 1, up = 1, front = 1}, center_at_unit_origin = true, center_at_unit_top = true}
DCEI.ShowUnitLabel(unit, "Unit", label_options)

Related

ShowUnitLabel
HideUnitLabel

Offset

Type Offset

Type Structure

Offset
{
double right
double up
double front
}

Description

Helper table in some API for offset

Example Usage

local frame = DCEI.CreateTextFrame(DCEI.GetUiRootFrame())
DCEI.SetTextFrameText(frame, "Bob")

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

local options = {
    offset = {up = 1.2},
    center_at_unit_origin = true
}

DCEI.AttachFrameToUnit(frame, unit, options)

Related

AttachFrameToUnit

TextOptions

Type TextOptions

Type Structure

TextOptions
{
Offset offset
}

Description

Text option.

Example Usage

local float_text_pos = { x = 20, y = 2, z = 20 }
local text_options = { offset = { right = 1, up = 10, front = 10 } }
DCEI.ShowFloatingText(float_text_pos, "Floating Text", 5, 1, 5, text_options)

ExplicitOffset

Type ExplicitOffset

Type Structure

ExplicitOffset
{
double right
double up
double forward
}

Description

Offset is based on forward/right/up directions.

Example Usage

local parent_unit = DCEI.FindUnit("Ship")
local child_unit = DCEI.FindUnit("Archer")
DCEI.AttachUnit(
    child_unit,
    parent_unit,
    { explicit_offset = { forward = 3 }, use_child_facing = true, orientation_type = "WorldOrientation" }
)

PolarOffset

Type PolarOffset

Type Structure

PolarOffset
{
double yaw
double pitch
double distance
}

Description

Offset is based on angle and distance.

Example Usage

local parent_unit = DCEI.FindUnit("Ship")
local child_unit = DCEI.FindUnit("Archer")
DCEI.AttachUnit(
    child_unit,
    parent_unit,
    { polar_offset = { yaw = 3, distance = 2 }, use_child_facing = true, orientation_type = "WorldOrientation" }
)

SimpleUnitMeta

Type SimpleUnitMeta

Type Structure

SimpleUnitMeta
{
string type_name
}

Description

Used for SimpleUnitTypeOptions which is used by the DCEI.RegisterSimpleUnitType API. Specify the unit type name and the player and team IDs.

Example Usage

function RegisterUnitType(unit_data, life, damage, speed, mass)
    local meta_data = {
        type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
        player_id = -1, -- The Owners Player Id.
        team_id = -1, -- The Owners Team Id.
    }
    local health_data = {
        max = 6, -- The Maximum Health of the Unit.
        value = 6, -- The Current Health of the Unit.
    }
    local loot_data = {
        loot_id = DCEI.SimpleUnit("Experience - Small"), -- The Registered Loot Id to Drop.
        drop_rate = 0.5, -- The Chance [0 - 1] of dropping this Loot when the Unit is Killed.
    }
    local movement_data = {
        max_speed = 15, -- The Max Speed of the Unit.
        velocity = { x = 1, y = 0, z = 1 }, -- The Direction of Travel.
    }
    local collision_data = {
        belongs_to_layer_mask = -1, -- The Layer of the Unit.
        collides_with_layer_mask = 1, -- The Layer the Unit can collide with.
        radius = 0.5, -- The Radius of the Unit.
        takes_damage = true, -- Determines if the Unit can take Damage.
        use_rvo_agent = true, -- Determines if the Unit can Navigate around other RVO Units.
    }
    local collision_damage_data = {
        timing = timing, -- The Timing (Start, Continue, Stop) that will trigger this response.
        deal_damage_value = 4, -- The amount of Damage to deal.
        cooldown = 8, -- The Delay (in Frames) before a target can be Damaged again.
    }
    local options = {
        meta = meta_data,
        health_options = health_data,
        loot_options = loot_data,
        movement_options = movement_data,
        collision_options = collision_data,
        collision_damage_applier_options = collision_damage_data,
        collision_force_applier_options = nil,
        collision_stats_applier_options = nil,
        kill_timer_options = nil,
        remove_timer_options = nil,
        follow_unit = nil,
        mass = 2,
    }
    DCEI.RegisterSimpleUnitType(unit_data.Name, options)
    return unit_data.Name
end

SimpleUnitArmorOptions

Type SimpleUnitArmorOptions

Type Structure

SimpleUnitArmorOptions
{
int type
}

Description

In-develepment API
No example use yet

Example Usage

In-develepment API
No example use yet

SimpleUnitMoverOptions

Type SimpleUnitMoverOptions

Type Structure

SimpleUnitMoverOptions
{
bool enabled
bool do_not_use_mover_facing
}

Description

Experimental API: Not intended for wide use

Example Usage

-- Placeholder example
local simple_mover = { enabled = true }

SimpleUnitLocalAvoidanceOptions

Type SimpleUnitLocalAvoidanceOptions

Type Structure

SimpleUnitLocalAvoidanceOptions
{
bool enabled
}

Description

Experimental API: Not intended for wide use

Example Usage

-- Placeholder example
local simple_local_avoidance = { enabled = true }

SimpleUnitTimerOptions

Type SimpleUnitTimerOptions

Type Structure

SimpleUnitTimerOptions
{
float remove_unit_after_seconds
float kill_unit_after_seconds
}

Description

Experimental API: Not intended for wide use
Used by the SimpleUnitTypeOptions type which is used by the DCEI.RegisterSimpleUnitType API. Provides options to start timers for removing or killing a unit based on specified time intervals or after it has been killed.

Example Usage

-- Placeholder example
local simple_removal_timer = { remove_unit_after_seconds = nil, kill_unit_after_seconds = 1, remove_actor_after_killed_seconds = 3 }

SimpleLootOptions

Type SimpleLootOptions

Type Structure

SimpleLootOptions
{
int loot_id
float drop_rate
}

Description

Used by the SimpleUnitTypeOptions type which is used by the DCEI.RegisterSimpleUnitType API. Specifies the loot ID and drop rate for a simple unit type. See DCEI.RegisterSimpleLoot as well.

Example Usage

function RegisterUnitType(unit_data, life, damage, speed, mass)
    local meta_data = {
        type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
        player_id = -1, -- The Owners Player Id.
        team_id = -1, -- The Owners Team Id.
    }
    local health_data = {
        max = 6, -- The Maximum Health of the Unit.
        value = 6, -- The Current Health of the Unit.
    }
    local loot_data = {
        loot_id = DCEI.SimpleUnit("Experience - Small"), -- The Registered Loot Id to Drop.
        drop_rate = 0.5, -- The Chance [0 - 1] of dropping this Loot when the Unit is Killed.
    }
    local movement_data = {
        max_speed = 15, -- The Max Speed of the Unit.
        velocity = { x = 1, y = 0, z = 1 }, -- The Direction of Travel.
    }
    local collision_data = {
        belongs_to_layer_mask = -1, -- The Layer of the Unit.
        collides_with_layer_mask = 1, -- The Layer the Unit can collide with.
        radius = 0.5, -- The Radius of the Unit.
        takes_damage = true, -- Determines if the Unit can take Damage.
        use_rvo_agent = true, -- Determines if the Unit can Navigate around other RVO Units.
    }
    local collision_damage_data = {
        timing = timing, -- The Timing (Start, Continue, Stop) that will trigger this response.
        deal_damage_value = 4, -- The amount of Damage to deal.
        cooldown = 8, -- The Delay (in Frames) before a target can be Damaged again.
    }
    local options = {
        meta = meta_data,
        health_options = health_data,
        loot_options = loot_data,
        movement_options = movement_data,
        collision_options = collision_data,
        collision_damage_applier_options = collision_damage_data,
        collision_force_applier_options = nil,
        collision_stats_applier_options = nil,
        kill_timer_options = nil,
        remove_timer_options = nil,
        follow_unit = nil,
        mass = 2,
    }
    DCEI.RegisterSimpleUnitType(unit_data.Name, options)
    return unit_data.Name
end

SimpleUnitTransformAnimationOptions

Type SimpleUnitTransformAnimationOptions

Type Structure

SimpleUnitTransformAnimationOptions
{
Float3 start_position
Float3 end_position
Float3 random_position_offset
Float3 start_scale
Float3 end_scale
Float3 pivot
float start_seconds
float end_seconds
Float3 rotation_axis
float start_degree
float end_degree
Ease ease
}

Description

Used for the DCEI.AddTransformAnimationToSimpleDamageNumberStyle API. Adds an animation to the scale, position, or rotation of a simple damage number text style.

Example Usage

local function RegisterSimpleDigitStyle()
    -- damage number style
    DCEI.RegisterSimpleDamageNumberStyles({
        font_type = 1,
        duration_seconds = 0.9,
        distance_between_digits = {
            x = 0.4,
            y = 0,
            z = 0,
        },
    })

    local x_y_ratio = 1
    local x_final = 0.5

    DCEI.AddTransformAnimationToSimpleDamageNumberStyle(1, {
        start_scale = { x = 0, y = 0, z = 0 },
        random_position_offset = { x = 0, y = 0, z = 0 },
        end_scale = { x = x_final * 1.2, y = x_final * x_y_ratio * 1.2, z = x_final * 1.2 },
        end_position = { x = 0, y = 0, z = 0 },
        end_degree = 0,
        pivot = { x = 0, y = 0 },
        start_seconds = 0,
        end_seconds = 0.25,
    })

    DCEI.AddTransformAnimationToSimpleDamageNumberStyle(1, {
        start_scale = { x = x_final * 1.2, y = x_final * x_y_ratio * 1.2, z = x_final * 1.2 },
        random_position_offset = { x = 0, y = 0, z = 0 },
        end_scale = { x = x_final * 0.9, y = x_final * x_y_ratio * 0.9, z = x_final * 0.9 },
        end_position = { x = 0, y = 0, z = 0 },
        end_degree = 0,
        pivot = { x = 0, y = 0 },
        start_seconds = 0.25,
        end_seconds = 0.375,
    })
end

local function OnUnitDamaged(damage, target_unit)
    DCEI.ShowSimpleDamageNumber(target_unit, 1, damage)
end

DCEI.TriggerAddUnitDamageEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitDamaged, {critical_only = true})

SimpleUnitTintColorAnimationOptions

Type SimpleUnitTintColorAnimationOptions

Type Structure

SimpleUnitTintColorAnimationOptions
{
Float3 start_tint_color
Float3 end_tint_color
float start_alpha
float end_alpha
float start_seconds
float end_seconds
Ease ease
}

Description

Used for the API DCEI.ApplyTransparencyAnimationToSimpleUnit. Sets the tint color, alpha, and tmiing for color animmations on a simple unit.

Example Usage

function AnimateSimpleUnit()
    local unit_data = {
        Collider = {
            belongs_to_layer_mask = 1,
            collides_with_layer_mask = 3,
            take_damage = false,
            radius = 3,
        },
        Unit = {
            type_name = DCEI.Unit("Collector"),
            max_health = 1,
        },
    }
    local position = {x = 15, y = 15}
    local facing_down = {x = 0, y = -1}
    local still_velocity = {x = 0, y = 0}
    local unit = DCEI.CreateSimpleUnit(
        1,
        unit_data.Unit,
        unit_data.Collider,
        position.x,
        position.y,
        facing_down.x,
        facing_down.y,
        still_velocity.x,
        still_velocity.y
    )
    DCEI.ApplyTransparencyAnimationToSimpleUnit(unit, {            
        start_tint_color = { x = 1, y = 1, z = 1},
        end_tint_color = { x = 1, y = 1, z = 1},
        start_alpha = 1,
        end_alpha = 0.5,
        start_seconds = 3,
        end_seconds = 5
    })

    return unit
end

SimpleUnitAnimationOptions

Type SimpleUnitAnimationOptions

Type Structure

SimpleUnitAnimationOptions
{
bool enabled
float frame_rate
}

Description

Used in SimpleUnitAnimatorOptions. Provides options to change the animation on a simple unit.

Example Usage

-- Placeholder example
local simple_removal_timer = { enabled = true, frame_rate = 30 }

Related

• SimpleUnitAnimatorOptions
  

SimpleUnitShadowOptions

Type SimpleUnitShadowOptions

Type Structure

SimpleUnitShadowOptions
{
bool enabled
float shadow_radius
}

Description

Used in SimpleUnitAnimatorOptions. Provides options to change the shadow on a simple unit.

Example Usage

-- Placeholder example
local shadow_options = { enabled = true, shadow_radius = 0.5 }

Related

• SimpleUnitAnimatorOptions
  

SimpleUnitCollisionEffect

Type SimpleUnitCollisionEffect

Type Structure

SimpleUnitCollisionEffect
{
CollisionTiming timing
string effect_name
float cooldown_seconds
int tag_mask_filter
}

Description

Defines which effect to apply periodically when colliding with a simple unit.

Example Usage

DCEI.RegisterSimpleUnitType("test", {
    meta = { type_name = DCEI.SimpleUnit("Standard MeleeUnit"), },
    collision_options = {
        belongs_to_layer_mask = 1,
        collides_with_layer_mask = 1,
        radius = 0.5,
    },
    cast_effect_options = {
        collision_effects = {{
            timing = 1,
            effect_name = DCEI.Effect("simple-spawn"),
        }, {
            timing = 3,
            cooldown = 0.5,
            effect_name = DCEI.Effect("simple-force")
        }
    }},
    mass = 1,
})

SimpleUnitCastEffectOptions

Type SimpleUnitCastEffectOptions

Type Structure

SimpleUnitCastEffectOptions
{
List<SimpleUnitCollisionEffect> collision_effects
string on_death
}

Description

In development internal API.
No example usage yet

Example Usage

In development internal API.
No example usage yet

SimpleUnitAnimatorOptions

Type SimpleUnitAnimatorOptions

Type Structure

SimpleUnitAnimatorOptions
{
SimpleUnitShadowOptions shadow_options
Dictionary<int, int> death_particle_effects
SimpleUnitAnimationOptions animation_options
}

Description

Experimental API: Not intended for wide use
Used by the SimpleUnitTypeOptions type which is used by the DCEI.RegisterSimpleUnitType API. Provides options for various visual effects for simple units.

Example Usage

-- Placeholder example
local shadow_data = { enabled = true, shadow_radius = 0.5 }
local death_particle_data = { [1] = 5, [2] = 10 }
local animation_data = { enabled = true, frame_rate = 30 }
local animator_options = { shadow_options = shadow_data, death_particle_effects = shadow_data, animation_options = animation_data }

• SimpleUnitTypeOptions
  

SimpleParticleSpawnOptions

Type SimpleParticleSpawnOptions

Type Structure

SimpleParticleSpawnOptions
{
string name
Float3 scale
Dictionary<string, ParticleProperties> subsystem_properties
}

Description

Options for the DCEI.RegisterSimpleParticle API.

Example Usage

-- Placeholder example
DCEI.RegisterSimpleParticle(option)

SimpleUnitTypeOptions

Type SimpleUnitTypeOptions

Type Structure

SimpleUnitTypeOptions
{
SimpleUnitMeta meta
SimpleHealthOptions health_options
SimpleUnitArmorOptions armor_options
SimpleLootOptions loot_options
SimpleUnitMovementOptions movement_options
SimpleUnitLocalAvoidanceOptions local_avoidance_options
SimpleUnitMoverOptions mover_options
CollisionOptions collision_options
CollisionDamageApplierOptions collision_damage_applier_options
CollisionForceApplierOptions[] collision_force_applier_options
CollisionStatsApplierOptions collision_stats_applier_options
CollisionMovementSpeedModifierApplierOptions collision_movement_speed_modifier_applier_options
SimpleUnitCastEffectOptions cast_effect_options
SimpleTagOptions tag_options
SimpleUnitTimerOptions timer_options
float mass
SimpleUnitAnimatorOptions animator_options
}

Description

Options for the DCEI.RegisterSimpleUnitType API for registering a new simple unit type.

Example Usage

function RegisterUnitType(unit_data, life, damage, speed, mass)
    local meta_data = {
        type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
        player_id = -1, -- The Owners Player Id.
        team_id = -1, -- The Owners Team Id.
    }
    local health_data = {
        max = 6, -- The Maximum Health of the Unit.
        value = 6, -- The Current Health of the Unit.
    }
    local loot_data = {
        loot_id = DCEI.SimpleUnit("Experience - Small"), -- The Registered Loot Id to Drop.
        drop_rate = 0.5, -- The Chance [0 - 1] of dropping this Loot when the Unit is Killed.
    }
    local movement_data = {
        max_speed = 15, -- The Max Speed of the Unit.
        velocity = { x = 1, y = 0, z = 1 }, -- The Direction of Travel.
    }
    local collision_data = {
        belongs_to_layer_mask = -1, -- The Layer of the Unit.
        collides_with_layer_mask = 1, -- The Layer the Unit can collide with.
        radius = 0.5, -- The Radius of the Unit.
        takes_damage = true, -- Determines if the Unit can take Damage.
        use_rvo_agent = true, -- Determines if the Unit can Navigate around other RVO Units.
    }
    local collision_damage_data = {
        timing = timing, -- The Timing (Start, Continue, Stop) that will trigger this response.
        deal_damage_value = 4, -- The amount of Damage to deal.
        cooldown = 8, -- The Delay (in Frames) before a target can be Damaged again.
    }
    local options = {
        meta = meta_data,
        health_options = health_data,
        loot_options = loot_data,
        movement_options = movement_data,
        collision_options = collision_data,
        collision_damage_applier_options = collision_damage_data,
        collision_force_applier_options = nil,
        collision_stats_applier_options = nil,
        kill_timer_options = nil,
        remove_timer_options = nil,
        follow_unit = nil,
        mass = 2,
    }
    DCEI.RegisterSimpleUnitType(unit_data.Name, options)
    return unit_data.Name
end

SimpleUnitInstanceOptions

Type SimpleUnitInstanceOptions

Type Structure

SimpleUnitInstanceOptions
{
int player_id
int team_id
Float3 position
Float2 facing
Float3 velocity
unit move_target_unit
Float3 move_target_position
Float3 move_target_direction
int animation_sequence_id
}

Description

Option type for DCEI.CreateSimpleUnitAsync used to specify the team an dplayer ID, position, velocity, and facing of the simple unit.

Example Usage

local meta_data = {
    type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
    player_id = -1, -- The Owners Player Id.
    team_id = -1, -- The Owners Team Id.
}
local health_data = {
    max = 6, -- The Maximum Health of the Unit.
    value = 6, -- The Current Health of the Unit.
}
local loot_data = {
    loot_id = DCEI.SimpleUnit("Experience - Small"), -- The Registered Loot Id to Drop.
    drop_rate = 0.5, -- The Chance [0 - 1] of dropping this Loot when the Unit is Killed.
}
local movement_data = {
    max_speed = 15, -- The Max Speed of the Unit.
    velocity = { x = 1, y = 0, z = 1 }, -- The Direction of Travel.
}
local collision_data = {
    belongs_to_layer_mask = -1, -- The Layer of the Unit.
    collides_with_layer_mask = 1, -- The Layer the Unit can collide with.
    radius = 0.5, -- The Radius of the Unit.
    takes_damage = true, -- Determines if the Unit can take Damage.
    use_rvo_agent = true, -- Determines if the Unit can Navigate around other RVO Units.
}
local collision_damage_data = {
    timing = timing, -- The Timing (Start, Continue, Stop) that will trigger this response.
    deal_damage_value = 4, -- The amount of Damage to deal.
    cooldown = 8, -- The Delay (in Frames) before a target can be Damaged again.
}
local options = {
    meta = meta_data,
    health_options = health_data,
    loot_options = loot_data,
    movement_options = movement_data,
    collision_options = collision_data,
    collision_damage_applier_options = collision_damage_data,
    collision_force_applier_options = nil,
    collision_stats_applier_options = nil,
    kill_timer_options = nil,
    remove_timer_options = nil,
    follow_unit = nil,
    mass = 2,
}
DCEI.RegisterSimpleUnitType("Hostile - Runner", options)
DCEI.CreateSimpleUnitAsync("Hostile - Runner", {
    player_id = -1,
    team_id = -1,
    position = { x = 15, y = 0, z = 15 },
    facing = { x = 0, y = 0 },
    velocity = { x = 1, y = 0, z = 1 },
    follow_unit = nil,
})

SimpleDamageNumberStyleOptions

Type SimpleDamageNumberStyleOptions

Type Structure

SimpleDamageNumberStyleOptions
{
int font_type
int prefix_symbol_index
int suffix_symbol_index
Float3 distance_between_digits
float duration_seconds
bool show_zero_damage
}

Description

Type used for DCEI.RegisterSimpleDamageNumberStyles for setting font style options.

Example Usage

local function RegisterSimpleDigitStyle()
    -- damage number style
    DCEI.RegisterSimpleDamageNumberStyles({
        font_type = 1,
        duration_seconds = 0.9,
        distance_between_digits = {
            x = 0.4,
            y = 0,
            z = 0,
        },
    })

    local x_y_ratio = 1
    local x_final = 0.5

    DCEI.AddTransformAnimationToSimpleDamageNumberStyle(1, {
        start_scale = { x = 0, y = 0, z = 0 },
        random_position_offset = { x = 0, y = 0, z = 0 },
        end_scale = { x = x_final * 1.2, y = x_final * x_y_ratio * 1.2, z = x_final * 1.2 },
        end_position = { x = 0, y = 0, z = 0 },
        end_degree = 0,
        pivot = { x = 0, y = 0 },
        start_seconds = 0,
        end_seconds = 0.25,
    })

    DCEI.AddTransformAnimationToSimpleDamageNumberStyle(1, {
        start_scale = { x = x_final * 1.2, y = x_final * x_y_ratio * 1.2, z = x_final * 1.2 },
        random_position_offset = { x = 0, y = 0, z = 0 },
        end_scale = { x = x_final * 0.9, y = x_final * x_y_ratio * 0.9, z = x_final * 0.9 },
        end_position = { x = 0, y = 0, z = 0 },
        end_degree = 0,
        pivot = { x = 0, y = 0 },
        start_seconds = 0.25,
        end_seconds = 0.375,
    })

    DCEI.AddTintColorAnimationToSimpleDamageNumberStyle(1, {
        start_alpha = 0.1,
        end_alpha = 1,
        start_tint_color = { x = 1, y = 1, z = 1 },
        end_tint_color = { x = 1, y = 1, z = 1 },
        start_seconds = 0,
        end_seconds = 0.25,
    })

    DCEI.AddTintColorAnimationToSimpleDamageNumberStyle(1, {
        start_alpha = 1,
        end_alpha = 1,
        start_tint_color = { x = 1, y = 1, z = 1 },
        end_tint_color = { x = 1, y = 1, z = 1 },
        start_seconds = 0.25,
        end_seconds = 0.75,
    })
end

local function OnUnitDamaged(damage, target_unit)
    DCEI.ShowSimpleDamageNumber(target_unit, 1, damage)
end

DCEI.TriggerAddUnitDamageEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitDamaged, {critical_only = true})

SimpleDamageAffinityEntry

Type SimpleDamageAffinityEntry

Type Structure

SimpleDamageAffinityEntry
{
int damage_type
int armor_type
BehaviorModifier damage_modifier
}

Description

Internal API
No example usage yet

Example Usage

Internal API

No example usage yet

SimpleDamageAffinityOptions

Type SimpleDamageAffinityOptions

Type Structure

SimpleDamageAffinityOptions
{
SimpleDamageAffinityEntry[] entries
}

Description

Internal API
No example usage yet

Example Usage

Internal API

No example usage yet

ControllerMapEntry

Type ControllerMapEntry

Type Structure

ControllerMapEntry
{
ElementAssignmentEntry[] assignments
    ElementAssignmentEntry
    {
int key_id
int action_id
    }

}

Description

Example Usage

SimpleUnitMapBoundOptions

Type SimpleUnitMapBoundOptions

Type Structure

SimpleUnitMapBoundOptions
{
float center_x
float center_y
float width
float height
int player_id_remove_mask
}

Description

Used for DCEI.SetSimpleUnitMapBounds API for setting simple unit map bounds.

Example Usage

  local size = self:GetPlayableSize()
  DCEI.SetSimpleUnitMapBounds({
      center_x = 0,
      center_y = 0,
      width =  32, 
      height = 32, 
      player_id_remove_mask = -1,
  })

SimpleUnitMovementOptions

Type SimpleUnitMovementOptions

Type Structure

SimpleUnitMovementOptions
{
float max_speed
}

Description

Used in the SimpleUnitTypeOptions type which is used by the DCEI.RegisterSimpleUnitType API. Specifies max speed and other simple unit movement options.

Example Usage

function RegisterUnitType(unit_data, life, damage, speed, mass)
    local meta_data = {
        type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
        player_id = -1, -- The Owners Player Id.
        team_id = -1, -- The Owners Team Id.
    }
    local health_data = {
        max = 6, -- The Maximum Health of the Unit.
        value = 6, -- The Current Health of the Unit.
    }
    local loot_data = {
        loot_id = DCEI.SimpleUnit("Experience - Small"), -- The Registered Loot Id to Drop.
        drop_rate = 0.5, -- The Chance [0 - 1] of dropping this Loot when the Unit is Killed.
    }
    local movement_data = {
        max_speed = 15, -- The Max Speed of the Unit.
        velocity = { x = 1, y = 0, z = 1 }, -- The Direction of Travel.
    }
    local collision_data = {
        belongs_to_layer_mask = -1, -- The Layer of the Unit.
        collides_with_layer_mask = 1, -- The Layer the Unit can collide with.
        radius = 0.5, -- The Radius of the Unit.
        takes_damage = true, -- Determines if the Unit can take Damage.
        use_rvo_agent = true, -- Determines if the Unit can Navigate around other RVO Units.
    }
    local collision_damage_data = {
        timing = timing, -- The Timing (Start, Continue, Stop) that will trigger this response.
        deal_damage_value = 4, -- The amount of Damage to deal.
        cooldown = 8, -- The Delay (in Frames) before a target can be Damaged again.
    }
    local options = {
        meta = meta_data,
        health_options = health_data,
        loot_options = loot_data,
        movement_options = movement_data,
        collision_options = collision_data,
        collision_damage_applier_options = collision_damage_data,
        collision_force_applier_options = nil,
        collision_stats_applier_options = nil,
        kill_timer_options = nil,
        remove_timer_options = nil,
        follow_unit = nil,
        mass = 2,
    }
    DCEI.RegisterSimpleUnitType(unit_data.Name, options)
    return unit_data.Name
end

CollisionOptions

Type CollisionOptions

Type Structure

CollisionOptions
{
int belongs_to_layer_mask
int collides_with_layer_mask
float radius
}

Description

Used for APIs such as CreateSimpleUnit, SetCollisionComponentData and RegisterSimpleLoot to set collision options.

Example Usage

local unit_data = {
    -- These are the collision options. 
    Collider = {
        belongs_to_layer_mask = 1,
        collides_with_layer_mask = 3,
        take_damage = false,
        radius = 3,
    },
    Unit = {
        type_name = DCEI.Unit("Collector"),
        max_health = 1,
    },
}
local unit = DCEI.CreateSimpleUnitSync(simple_unit_type, {
    player_id = -1,
    team_id = -1,
    position = { x = 15, y = 0, z = 15 },
    facing = { x = 0, y = 0 },
    velocity = { x = 1, y = 0, z = 1 },
    move_target_unit = nil,
    move_target_position = nil,
    move_target_direction = nil,
})

CollisionMovementSpeedModifierApplierOptions

Type CollisionMovementSpeedModifierApplierOptions

Type Structure

CollisionMovementSpeedModifierApplierOptions
{
BehaviorModifier modifier
float duration_seconds
CollisionTiming timing
float cooldown_seconds
}

Description

Internal and in-development
No example usage yet

Example Usage

Internal and in-development

No example usage yet

CollisionDamageApplierOptions

Type CollisionDamageApplierOptions

Type Structure

CollisionDamageApplierOptions
{
Damage deal_damage
Damage self_damage
CollisionTiming timing
float cooldown_seconds
}

Description

Used for API SetCollisionDamageData

Example Usage

DCEI.SetCollisionDamageData(self.unit, {
    timing = 1,
    cooldown = 5,
    deal_damage_value = 1,
})

CollisionForceApplierOptions

Type CollisionForceApplierOptions

Type Structure

CollisionForceApplierOptions
{
float horizontal_force
float horizontal_friction
float vertical_force
float vertical_friction
float duration
CollisionTiming timing
bool only_trigger_on_kill
float cooldown_seconds
}

Description

Used for api SetCollisionForceData

Example Usage

DCEI.SetCollisionForceData(self.unit, {
    force = 10, -- Push Force (+)
    factor = -20, -- Change over Time
    duration = 0.5, -- Seconds
})

CollisionStatsApplierOptions

Type CollisionStatsApplierOptions

Type Structure

CollisionStatsApplierOptions
{
string stats_name
float delta_value
CollisionTiming timing
}

Description

Used for api SetCollisionStatsData and RegisterSimpleLoot

Example Usage

-- Placeholder example
DCEI.SetCollisionStatsData(unit, {stats_id = 1, delta_value = 15})

SimpleHealthOptions

Type SimpleHealthOptions

Type Structure

SimpleHealthOptions
{
float max
float value
}

Description

Used for API SetSimpleHealthData. For more info about simple units, see Simple Units Guide.

Example Usage

local new_simple_unit = DCEI.CreateSimpleUnitSync(simple_unit_type, {
    player_id = -1,
    team_id = -1,
    position = { x = 15, y = 0, z = 15 },
    facing = { x = 0, y = 0 },
    velocity = { x = 1, y = 0, z = 1 },
    move_target_unit = nil,
    move_target_position = nil,
    move_target_direction = nil,
})

DCEI.SetSimpleHealthData(new_simple_unit, {max = 10, value = 10})

SimpleTagOptions

Type SimpleTagOptions

Type Structure

SimpleTagOptions
{
int value
}

Description

Internal and in-development
No example usage yet

Example Usage

Internal and in-development

No example usage yet

AttachOffsetOptions

Type AttachOffsetOptions

Type Structure

AttachOffsetOptions
{
ExplicitOffset explicit_offset
PolarOffset polar_offset
bool use_current_offset
bool use_child_facing
OrientationType orientation_type
}

Description

Options to customize how units attach.

Example Usage

local parent_unit = DCEI.FindUnit("Ship")
local child_unit = DCEI.FindUnit("Archer")
DCEI.AttachUnit(
    child_unit,
    parent_unit,
    { explicit_offset = { forward = 3 }, use_child_facing = true, orientation_type = "WorldOrientation" }
)

orientation_type:

• WorldOrientation: Orientation is relative to world facing (i.e., north).
• ParentOrientation: Orientation is relative to the direction from parent unit's facing.
  

ColorRGBA

Type ColorRGBA

Type Structure

ColorRGBA
{
float r
float g
float b
Nullable<float> a
}

Description

Color table. Notice the float is 0~1 instead of 0~255. APIs using this parameter also accept hex codes, such as "#32a852"

Example Usage

local frame = DCEI.CreateFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameImageColor(frame, {r = 251/255, g = 79/255, b = 79/255, a = 1})
DCEI.SetFrameImageColor(frame, "#32a852") -- This also works
DCEI.SetFrameSize(frame, 100, 100)

ColorRGB

Type ColorRGB

Type Structure

ColorRGB
{
float r
float g
float b
}

Description

Color table. Notice the float is 0~1 instead of 0~255. Also accepts hex values such as "#32a852"

Example Usage

DCEI.SetTextFrameColorRGB(text_frame, { r = 0.5, g = 0.5, b = 0.5 })
DCEI.SetTextFrameColorRGB(text_frame, "#32a852") -- Also works

WaypointOptions

Type WaypointOptions

Type Structure

WaypointOptions
{
string waypoint_name
float dispersal
bool use_natural_dispersal
int node_index
}

Description

Waypoint options including waypoint name, dispersal, use natural dispersal flag, and node index to use for API's such as DCEI.ApplyWaypoint.

Example Usage

local pos = { x = 31, y = 8 } -- spawn pos
local GoblinWarshipUnit = DCEI.CreateUnit(-1, -1, DCEI.Unit("Goblin Warship"), pos.x, pos.y, 1, -1)
DCEI.ApplyWaypoint(GoblinWarshipUnit, {
    waypoint_name = "GoblinWarshipFlyby",
    dispersal = 0.5,
    use_natural_dispersal = true,
    node_index = 2
})

ScreenBackgroundOptions

Type ScreenBackgroundOptions

Type Structure

ScreenBackgroundOptions
{
Color color
float duration
}

Description

Color and duration options for DCEI.ShowScreenMask

Example Usage

-- Creates the screen mask
local mask_alpha = 0.5
local screen_options = { color = { r = 255, g = 0, b = 255, a = 255 }, duration = 1 }
DCEI.ShowScreenMask(mask_alpha, screen_options)

-- Hides the mask after 2 seconds
local show_duration = 2
DCEI.TriggerAddTimerEventElapsed(function()
    DCEI.HideScreenMask()
end, show_duration)

AreaOffset

Type AreaOffset

Type Structure

AreaOffset
{
float left
float right
float top
float bottom
ColorRGBA debug_draw_color
}

Description

AreaOffset used for JoystickOptions to offset the radius of area on screen the joystick will be activated if pressed.

Example Usage

local unit = DCEI.CreateUnit(1, 1, "Standard MeleeUnit", 15, 15)

local function OnJoystickMove()
    local axes = DCEI.TriggeringJoystickAxes
    DCEI.DirectionalMove(unit, axes.x, axes.y)
end

local function CreateJoystick()
    local frame = DCEI.CreateFrame(DCEI.GetUiRootFrame())

    DCEI.SetFrameWidth(frame, 1500)
    DCEI.SetFrameHeight(frame, 1500)

    local joystick_options = {
        anchor = { x = 0, y = 0 },
        offset = { x = 0, y = 0 },
        disable_wasd = true,
        disable_arrow_keys = true,
        joystick_id = 1,
        dynamic_position = true,
        always_show = true,
        radius = 150,
        active_area_offset = {
            left = 500,
            right = 50,
            top = 500,
            bottom = 50,
            debug_draw_color = { r = 0, g = 1, b = 0, a = 0.5 },
        },
        handle_icon = DCEI.Texture("icon_arrow"),
        handle_icon_color = { r = 1, g = 0, b = 0, a = 0.5 },
        background_icon = DCEI.Texture("general_icon_wildsky_mall_light_circle"),
        background_icon_color = { r = 1, g = 0, b = 0, a = 0.5 },
        handle_rotation = true,
        parent = frame,
    }

    DCEI.TriggerAddJoystickEventWithJoystickOptions(OnJoystickMove, joystick_options)
end

CreateJoystick()

JoystickOptions

Type JoystickOptions

Type Structure

JoystickOptions
{
Float2 anchor
Float2 offset
bool disable_wasd
bool disable_arrow_keys
int joystick_id
bool dynamic_position
bool always_show
float radius
AreaOffset active_area_offset
string handle_icon
ColorRGBA handle_icon_color
string background_icon
ColorRGBA background_icon_color
bool handle_rotation
InGameUILayoutComponent parent
JoystickOptions Default
}

Description

All the joystick options for virtual joystick.

Example Usage

local unit = DCEI.CreateUnit(1, 1, "Standard MeleeUnit", 15, 15)

local function OnJoystickMove()
    local axes = DCEI.TriggeringJoystickAxes
    DCEI.DirectionalMove(unit, axes.x, axes.y)
end

local function CreateJoystick()
    local frame = DCEI.CreateFrame(DCEI.GetUiRootFrame())

    DCEI.SetFrameWidth(frame, 1500)
    DCEI.SetFrameHeight(frame, 1500)

    local joystick_options = {
        anchor = { x = 0, y = 0 },
        offset = { x = 0, y = 0 },
        disable_wasd = true,
        disable_arrow_keys = true,
        joystick_id = 1,
        dynamic_position = true,
        always_show = true,
        radius = 150,
        active_area_offset = {
            left = 500,
            right = 50,
            top = 500,
            bottom = 50,
            debug_draw_color = { r = 0, g = 1, b = 0, a = 0.5 },
        },
        handle_icon = DCEI.Texture("icon_arrow"),
        handle_icon_color = { r = 1, g = 0, b = 0, a = 0.5 },
        background_icon = DCEI.Texture("general_icon_wildsky_mall_light_circle"),
        background_icon_color = { r = 1, g = 0, b = 0, a = 0.5 },
        handle_rotation = true,
        parent = frame,
    }

    DCEI.TriggerAddJoystickEventWithJoystickOptions(OnJoystickMove, joystick_options)
end

CreateJoystick()

JoystickButtonOptions

Type JoystickButtonOptions

Type Structure

JoystickButtonOptions
{
string icon
bool hide
}

Description

All the joystick button options for virtual joystick.

Example Usage

function OnJoystickButton()
    local button_id = DCEI.TriggeringJoystickButtonId
    local button_event = DCEI.TriggeringJoystickButtonEventType

    -- button event 0 is for ButtonDown, event 1 is for ButtonUp
    if button_id == 0 and button_event == 0 then
        -- currently does not support targeted abilities
        -- movement commands will interrupt ability prep time / finish time, unless ability has "can cast while moving" flag checked
        DCEI.CastAbility(HERO_SLASH, HERO, HERO)
    end
end

DCEI.TriggerAddJoystickButtonEvent(0, OnJoystickButton, { icon = DCEI.Texture("icon_ingame_towerslot_barracks") })

BigHeadMessageOptions

Type BigHeadMessageOptions

Type Structure

BigHeadMessageOptions
{
bool pause
object on_dismiss
double delay
Color message_box_color
Color title_box_color
}

Description

Big head message options

Example Usage

local title = "Title"
local message = "Message"
local image = "bighead_hero_smith"
local big_head_options = {
    pause = true,
    on_dismiss = function()
        DCEI.LogMessage("Dismissed")
    end,
    delay = 5,
    message_box_color = { r = 255, g = 0, b = 255, a = 255 },
    title_box_color = { r = 255, g = 0, b = 255, a = 255 },
}
DCEI.ShowBigHeadMessage(title, message, image, big_head_options)

SpawnGroupUnit

Type SpawnGroupUnit

Type Structure

SpawnGroupUnit
{
string unit
double delay
double offset
}

Description

A list of unit types, delays, and offsets that make up a Spawn Groups, just like spawn groups in data.

Example Usage

local pattern = {
    name = "Goblin x3",
    group = {
        {
            unit = "Creep Goblin",
            delay = 0,
            offset = 0,
        },
        {
            unit = "Creep Goblin",
            delay = 1,
            offset = -0.25,
        },
        {
            unit = "Creep Goblin",
            delay = 1,
            offset = 0.25,
        }
    }
}

DCEI.RegisterSpawnGroup(pattern.name, pattern.group)

SetModelScaleActorAction

Type SetModelScaleActorAction

Type Structure

SetModelScaleActorAction
{
string actor
float model_scale
float duration
Ease ease
float ease_intensity
}

Description

A table of arguments for a model scale actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  actor = "",
  model_scale = 2.0,
  duration = 1.0,
  ease = "InBounce",
  ease_intensity = 1.0,
}

DCEI.SendSetModelScaleActorAction(target, action)

CreateActorAction

Type CreateActorAction

Type Structure

CreateActorAction
{
string actor
string host_site
List<string> host_site_operations
List<string> aliases
bool detached
}

Description

A table of arguments for a create actor actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  actor = "Test Model",
  host_site = {"SiteWeaponLeft"},
  host_site_operations = {"SOp Up Dot 1", "SOp Left Dot 5"},
  aliases = {},
  detached = false,
}

DCEI.SendCreateActorAction(target, action)

DestroyActorAction

Type DestroyActorAction

Type Structure

DestroyActorAction
{
string actor
}

Description

A table of arguments for a destroy actor actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  actor = "Test Model",
}

DCEI.SendDestroyActorAction(target, action)

SendCustomEventActorAction

Type SendCustomEventActorAction

Type Structure

SendCustomEventActorAction
{
string actor
string identifier
}

Description

A table of arguments for a send custom event actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  actor = "",
  identifier = "test_custom_event",
}

DCEI.SendSendCustomEventActorAction(target, action)

PlayAnimationActorAction

Type PlayAnimationActorAction

Type Structure

PlayAnimationActorAction
{
string clip_id
double duration
bool use_real_timer
}

Description

A table of arguments for a play animation actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  clip_id = "action",
  duration = 0.56,
  use_real_timer = false,
}

DCEI.SendPlayAnimationActorAction(target, action)

PauseAnimationActorAction

Type PauseAnimationActorAction

Type Structure

PauseAnimationActorAction
{
string clip_id
}

Description

A table of arguments for a pause animation actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  clip_id = "action",
}

DCEI.SendPauseAnimationActorAction(target, action)

SetVisibilityActorAction

Type SetVisibilityActorAction

Type Structure

SetVisibilityActorAction
{
string actor
bool visibility
}

Description

A table of arguments for a set visibility actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  actor = "",
  visibility = false,
}

DCEI.SendSetVisibilityActorAction(target, action)

SetTintColorActorAction

Type SetTintColorActorAction

Type Structure

SetTintColorActorAction
{
string actor
ColorRGBA color
float duration
Ease ease
float ease_intensity
}

Description

A table of arguments for a set tint color actor action.

Example Usage

local team_id = 1
local player_id = 1
local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 16, 16
local target = DCEI.CreateUnit(team_id, player_id, unit_type, x, z)
local action = {
  actor = "",
  color = {r = 1.0, g = 0.5, b = 0.5, a = 0.25},
  duration = 1.0,
  ease = "InBounce",
  ease_intensity = 1.0,
}

DCEI.SendSetTintColorActorAction(target, action)

AsyncPvpBot

Type AsyncPvpBot

Type Structure

AsyncPvpBot
{
string uuid
string tag
string name
string board
double elo
}

Description

Used for DCEI.AsyncPvp.UseBotOpponent()

Example Usage

Demo map with source code: https://platform.wildsky.dev/arcade/game/775

DCEI.SetOnClickCallback(
    use_bot_button,
    function()
        local bot = {uuid = "bot:1234", tag = "bx", name = "bx", elo = 0, board = "bb", board_win_count = 0, board_lose_count = 0, board_time = os.time()}
        DCEI.AsyncPvp.UseBotOpponent(
            session_info.id,
            bot,
            function(result)
                if not result then
                    return
                end
                session_info.current_opponent = bot
                controller:SetSessionInfo(session_info)
            end
        )
    end
)

Ease

Enum Ease

Enum Structure

Unset
Linear
InSine
OutSine
InOutSine
InQuad
OutQuad
InOutQuad
InCubic
OutCubic
InOutCubic
InQuart
OutQuart
InOutQuart
InQuint
OutQuint
InOutQuint
InExpo
OutExpo
InOutExpo
InCirc
OutCirc
InOutCirc
InElastic
OutElastic
InOutElastic
InBack
OutBack
InOutBack
InBounce
OutBounce
InOutBounce
Flash
InFlash
OutFlash
InOutFlash

Description

See https://easings.net/en for visual examples.

Example Usage

function AnimateSparkle(self, frame)
    local k1, k2 = 0, 1
    local duration = Core.Random.GetNumber(1, 2)
    local ease = "OutQuart"
    local animation = DCEI.AnimateFrameAlpha(frame, k1, k2, duration, ease)
    DCEI.SetFrameAnimationLoops(animation, -1, "Yoyo")

    local k1 = { x = 0.5, y = 0.5, z = 0.5 }
    local k2 = { x = 1.5, y = 1.5, z = 1.5 }
    local ease = "OutSine"
    local animation = DCEI.AnimateFrameScale(frame, k1, k2, duration, ease)
    DCEI.SetFrameAnimationLoops(animation, -1, "Yoyo")

    local start_rotation = math.random(1, 360)
    local k1, k2 = { z = start_rotation }, { z = start_rotation - 90 }
    local ease = "Linear"
    local duration = 1
    local duration = Core.Random.GetNumber(1.5, 2.5)
    local animation = DCEI.AnimateFrameRotation(frame, k1, k2, duration, ease)
    DCEI.SetFrameAnimationLoops(animation, -1, "Incremental")
end

LoopType

Enum LoopType

Enum Structure

Restart
Yoyo
Incremental

Description

Restart
When the animation finishes, it resets to the start. An animation rotating 15 degrees will reset to 0 degrees and animate back towards 15 degrees again.

Yoyo
When the animation finishes, it reverses and plays back to the start, then plays forwards again. An animation rotating 15 degrees will rotate back to 0 degrees, then forwards to 15 degrees, etc.

Incremental
When the animation finishes, it continues to play additively. An animation rotating 15 degrees will continue, rotating 30 degrees, 45 degrees, etc.

Example Usage

function AnimateSparkle(self, frame)
    local k1, k2 = 0, 1
    local duration = Core.Random.GetNumber(1, 2)
    local ease = "OutQuart"
    local animation = DCEI.AnimateFrameAlpha(frame, k1, k2, duration, ease)
    DCEI.SetFrameAnimationLoops(animation, -1, "Yoyo")

    local k1 = { x = 0.5, y = 0.5, z = 0.5 }
    local k2 = { x = 1.5, y = 1.5, z = 1.5 }
    local ease = "OutSine"
    local animation = DCEI.AnimateFrameScale(frame, k1, k2, duration, ease)
    DCEI.SetFrameAnimationLoops(animation, -1, "Yoyo")

    local start_rotation = math.random(1, 360)
    local k1, k2 = { z = start_rotation }, { z = start_rotation - 90 }
    local ease = "Linear"
    local duration = 1
    local duration = Core.Random.GetNumber(1.5, 2.5)
    local animation = DCEI.AnimateFrameRotation(frame, k1, k2, duration, ease)
    DCEI.SetFrameAnimationLoops(animation, -1, "Incremental")
end