Trigger API Reference\DCEI Functions\Unit

Trigger API Reference\DCEI Functions\Unit

string DefaultHero()

string DefaultHero()

Description

Wild Sky only. Returns the default hero.

Example Usage

    local hero_names = {}
    table.insert(hero_names, DCEI.DefaultHero())
    for _, hero in ipairs(DCEI.ExtraHeros()) do
        table.insert(hero_names, hero)
    end

object ExtraHeros()

object ExtraHeros()

Description

Wild Sky only. Returns other heroes players have equipped.

Example Usage

    local hero_names = {}
    table.insert(hero_names, DCEI.DefaultHero())
    for _, hero in ipairs(DCEI.ExtraHeros()) do
        table.insert(hero_names, hero)
    end

unit CreateUnitFilter(UnitFilter filter)

unit CreateUnitFilter(UnitFilter filter)

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

Parameters

UnitFilter filter the unit filter to create.

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 CreateUnit(int teamId, int playerId, string unitType, float x, float z, float dx = 0, float dz = 1)

unit CreateUnit(int teamId, int playerId, string unitType, float x, float z, float dx = 0, float dz = 1)

Description

Creates a unit at the specified location using default facing.

Parameters

int teamId which team to create the unit for. Use 1 for local player and -1 for enemy.
int playerId which player to create the unit for. Use 1 for local player and -1 for enemy.
string unitType name of data for the unit type to create
float x the x coordinate of where to create the unit.
float z the y coordinate of where to create the unit.
float dx a value between -1.0 and 1.0 that indicates the relative direction to face along the x-axis.
float dz a value between -1.0 and 1.0 that indicates the relative direction at to face along y-axis.

Example Usage

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

TriggerAddUnitSpawnEvent

float GetPlayerStats(int playerId, string statsName)

float GetPlayerStats(int playerId, string statsName)

Description

This is used in conjunction with simple units to improve performance. Ordinary methods of getting damaged dealt or tracking XP are not performant enough or don't work with simple units. For more info about simple units, see Simple Units Guide.

Enemy playerId is 0, player playerId is 1
statsId 0 is total damage dealt (collision damage(unit owner) + simple damage(caster owner))
statsId 1 is total experience gained
Returns 0 if playerId or statsId not found

Parameters

int playerId player to get stat for. 0 = enemy, 1 = player
string statsName name of stats to get

Example Usage

-- Get XP for player
local experience = DCEI.GetPlayerStats(1, 1)

void ResetPlayerStats()

void ResetPlayerStats()

Description

Resets the stats tracking from DCEI.GetPlayerStats

Example Usage

-- Rests XP, damage, kill simple stats
DCEI.ResetPlayerStats()

void SetUnitMass(unit unit, float massValue)

void SetUnitMass(unit unit, float massValue)

Description

Set a unit's mass. This affects how units behave whrn Simple Force is applied. Bigger mass value means higher inertia. Units that don't have mass se default to 1 mass.

Parameters

unit unit unit to set mass value for.
float massValue mass value to set.

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.SetUnitMass(new_simple_unit, 2)

CreateSimpleUnitAsync
CreateSimpleUnitSync

void SetUnitSimpleTag(unit unit, SimpleTagOptions options)

void SetUnitSimpleTag(unit unit, SimpleTagOptions options)

Description

Parameters

Example Usage

void SetSimpleHealthData(unit unit, SimpleHealthOptions options)

void SetSimpleHealthData(unit unit, SimpleHealthOptions options)

Description

Set Simple Health Component for simple or normal unit. For more info about simple units, see Simple Units Guide.

Parameters

unit unit unit to set simple health options for.
SimpleHealthOptions options set the current and max health values: {value = 10, max = 10}

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

CreateSimpleUnitAsync
CreateSimpleUnitSync

void SetSimpleUnitMoveTargetUnit(unit unit, unit targetUnit)

void SetSimpleUnitMoveTargetUnit(unit unit, unit targetUnit)

Description

Set a given simple unit to move to the target unit. For more info about simple units, see Simple Units Guide.

Parameters

unit unit simple unit to issue move command to
unit targetUnit target unit for the move command

Example Usage

function Spawner:SpawnHostile(unit_properties, position, rotation, velocity, target)
    local unit = DCEI.CreateSimpleUnit(
        PLAYERS.Hostile,
        unit_properties.Unit,
        unit_properties.Collider,
        position.x,
        position.y,
        rotation.x,
        rotation.y,
        velocity.x,
        velocity.y
    )

    DCEI.SetSimpleUnitMoveTargetUnit(unit, target)
    return unit
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

void SetSimpleUnitMoveTargetWorldPosition2D(unit unit, float x, float y)

void SetSimpleUnitMoveTargetWorldPosition2D(unit unit, float x, float y)

Description

Set Simple Unit Move Target Location. For more info about simple units, see Simple Units Guide.

Parameters

unit unit simple unit to issue move command to
float x the x coordinate of the target position
float y the y coordinate of the target position

Example Usage

function Spawner:SpawnHostile(unit_properties, position, rotation, velocity, target_pos)
    local unit = DCEI.CreateSimpleUnit(
        PLAYERS.Hostile,
        unit_properties.Unit,
        unit_properties.Collider,
        position.x,
        position.y,
        rotation.x,
        rotation.y,
        velocity.x,
        velocity.y
    )

    DCEI.SetSimpleUnitMoveTargetWorldPosition2D(unit, target_pos.x, target_pos.y)
    return unit
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

void SetSimpleUnitMoveTargetDirection(unit unit, float dx, float dy)

void SetSimpleUnitMoveTargetDirection(unit unit, float dx, float dy)

Description

Set simple unit move target direction. For more info about simple units, see Simple Units Guide.

Parameters

unit unit simple unit to issue move command to
float dx a value between -1.0 and 1.0 that indicates the relative direction to move along the x-axis.
float dy a value between -1.0 and 1.0 that indicates the relative direction to move along the y-axis.

Example Usage

function Spawner:SpawnHostile(unit_properties, position, rotation, velocity)
    local unit = DCEI.CreateSimpleUnit(
        PLAYERS.Hostile,
        unit_properties.Unit,
        unit_properties.Collider,
        position.x,
        position.y,
        rotation.x,
        rotation.y,
        velocity.x,
        velocity.y
    )

    DCEI.SetSimpleUnitMoveTargetDirection(unit, move_vector.x, move_vector.y)
    return unit
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

void SetSimpleUnitTeamId(unit unit, int teamId)

void SetSimpleUnitTeamId(unit unit, int teamId)

Description

Set the team ID for an existing simple unit.

Parameters

unit unit simple unit to change the team ownership of
int teamId team id to set.

Example Usage

function Units.Spawn.Hostile(hostile_data, position, facing, velocity, life)
    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.SetSimpleUnitTeamId(unit, TEAMS.Hostile)

    return unit
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

void RegisterSimpleAnimationSequence(int id, SimpleAnimationSequence sequence)

void RegisterSimpleAnimationSequence(int id, SimpleAnimationSequence sequence)

Description

Parameters

Example Usage

void ApplyTransformAnimationToSimpleUnit(unit unit, SimpleUnitTransformAnimationOptions options)

void ApplyTransformAnimationToSimpleUnit(unit unit, SimpleUnitTransformAnimationOptions options)

Description

Applies a simple transformation animation to a simple unit.

Parameters

unit unit the simple unit to apply the transform animation to.
SimpleUnitTransformAnimationOptions options the settings for the transform animation.

Example Usage

local unit_data = {
    Collider = {
        belongs_to_layer_mask = 1,
        collides_with_layer_mask = 3,
        take_damage = false,
        radius = 3,
    },
    Unit = {
        type_name = DCEI.Unit("Archer"),
    },
}

local position = { x = 18, y = 18 }
local facing_down = { x = 0, y = -1 }
local still_velocity = { x = 0, y = 0 }
local new_simple_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
)

local simple_animation_transformation_option = {
    start_scale = { x = 0, y = 0, z = 0 },
    random_position_offset = { x = 0, y = 0, z = 0 },
    end_scale = { x = 1, y = 1, z = 1 },
    end_position = { x = 0, y = 0, z = 0 },
    end_degree = 360,
    pivot = { x = 0, y = 0 },
    start_seconds = 0,
    end_seconds = 1,
}

DCEI.ApplyTransformAnimationToSimpleUnit(new_simple_unit, simple_animation_transformation_option)

CreateSimpleUnitAsync
CreateSimpleUnitSync

void ApplyTintColorAnimationToSimpleUnit(unit unit, SimpleUnitTintColorAnimationOptions options)

void ApplyTintColorAnimationToSimpleUnit(unit unit, SimpleUnitTintColorAnimationOptions options)

Description

Applies a simple tint animation to a simple unit.

Parameters

unit unit the simple unit to apply the tint animation to.
SimpleUnitTintColorAnimationOptions options the settings for the tint animation.

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.ApplyTintColorAnimationToSimpleUnit(unit, {            
        start_tint_color = { x = 0, y = 0, z = 0},
        end_tint_color = { x = 1, y = 1, z = 1},
        start_alpha = 1,
        end_alpha = 1,
        start_seconds = 1,
        end_seconds = 4
    })

    return unit
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

void ClearTintColorAnimationToSimpleUnit(unit unit)

void ClearTintColorAnimationToSimpleUnit(unit unit)

Description

Clears a simple tint animation from a simple unit.

Parameters

unit unit the simple unit to apply the tint animation to.

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.ApplyTintColorAnimationToSimpleUnit(unit, {            
        start_tint_color = { x = 0, y = 0, z = 0},
        end_tint_color = { x = 1, y = 1, z = 1},
        start_alpha = 1,
        end_alpha = 1,
        start_seconds = 1,
        end_seconds = 4
    })

    DCEI.Wait(2)
    -- This interrupts the tint color animation after 2 seconds and clears it.
    DCEI.ClearTintColorAnimationToSimpleUnit(unit)

    return unit
end

void AddKillTimerToSimpleUnit(unit unit, float seconds)

void AddKillTimerToSimpleUnit(unit unit, float seconds)

Description

Kill simple unit after some time.

Parameters

unit unit simple unit to kill.
float seconds seconds until the unit is killed.

Example Usage

function TemporarySimpleUnit()
    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.AddKillTimerToSimpleUnit(unit, 15)

    return unit
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

void AddRemoveTimerToSimpleUnit(unit unit, float seconds)

void AddRemoveTimerToSimpleUnit(unit unit, float seconds)

Description

Remove simple unit after some time.

Parameters

unit unit simple unit to remove.
float seconds seconds until the unit is removed.

Example Usage

function TemporarySimpleUnit()
    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.AddRemoveTimerToSimpleUnit(unit, 15)

    return unit
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

void ApplySimpleMoverTargetUnit(unit unit, unit target, float speed, float accelerationMagnitude, float startSeconds, float endSeconds)

void ApplySimpleMoverTargetUnit(unit unit, unit target, float speed, float accelerationMagnitude, float startSeconds, float endSeconds)

Description

Applies a simple mover to a simple unit which moves it toward a target unit.

Parameters

unit unit simple unit to apply the mover to.
unit target target unit.
float speed missile speed.
float accelerationMagnitude acceleration magnituide.
float startSeconds duration before the acceleration begins.
float endSeconds time when the acceleration will end. e.g. The total duration will be endSeconds - startSeconds

Example Usage

    local target_unit = DCEI.CreateUnit(-1, -1, DCEI.Unit("MyUnit"), 15, 15)

    local missile_simple_unit = DCEI.CreateSimpleUnit(2, {
        max_health = 10,
        type_name = DCEI.Unit("simple_missile_type"),
    }, {
        belongs_to_layer_mask = 2,
        collides_with_layer_mask = 1,
        radius = 0.2,
        take_damage = false,
    }, caster_position.x, caster_position.y, 1, 1, 0, 0)

    DCEI.ApplySimpleMoverTargetUnit(
        missile_simple_unit, --unit
        target_unit, --target
        15, --speed
        5, --accelerationMagnitude
        0, --startSeconds
        1.0625 --endSeconds
    )

CreateSimpleUnitAsync
CreateSimpleUnitSync

void ApplySimpleMoverUniformAcceleration(unit unit, float velocityX, float velocityY, float accelerationX, float accelerationY, float startSeconds, float endSeconds)

void ApplySimpleMoverUniformAcceleration(unit unit, float velocityX, float velocityY, float accelerationX, float accelerationY, float startSeconds, float endSeconds)

Description

Applies a simple mover to a simple unit.

Parameters

unit unit simple unit to apply the mover to.
float velocityX initial x velocity.
float velocityY initial y velocity.
float accelerationX x acceleration.
float accelerationY y acceleration.
float startSeconds duration before the acceleration begins.
float endSeconds time when the acceleration will end. e.g. The total duration will be endSeconds - startSeconds

Example Usage

    local missile_simple_unit = DCEI.CreateSimpleUnit(2, {
        max_health = 10,
        type_name = DCEI.Unit("simple_missile_type"),
    }, {
        belongs_to_layer_mask = 2,
        collides_with_layer_mask = 1,
        radius = 0.2,
        take_damage = false,
    }, caster_position.x, caster_position.y, 1, 1, 0, 0)

    local distance = Util.VectorMinus(target_position, caster_position)

    DCEI.ApplySimpleMoverUniformAcceleration(
        missile_simple_unit, --unit
        0, --velocityX
        distance.y, --velocityY
        0, --accelerationX
        0, --accelerationY
        0, --startSeconds
        1.0625 --endSeconds
    )

CreateSimpleUnitAsync
CreateSimpleUnitSync

void ApplySimpleMoverSineWave(unit unit, float amplitude, float periodSeconds, float startSeconds, float endSeconds)

void ApplySimpleMoverSineWave(unit unit, float amplitude, float periodSeconds, float startSeconds, float endSeconds)

Description

Applies a sine simple mover to a simple unit.

Parameters

unit unit simple unit to apply the mover to.
float amplitude the depth of the sine wave curves.
float periodSeconds the distance between peaks in the sine wave.
float startSeconds duration before the mover begins.
float endSeconds time when the mover will end. e.g. The total duration will be endSeconds - startSeconds

Example Usage

    local target_unit = DCEI.CreateUnit(-1, -1, DCEI.Unit("MyUnit"), 15, 15)

    local missile_simple_unit = DCEI.CreateSimpleUnit(2, {
        max_health = 10,
        type_name = DCEI.Unit("simple_missile_type"),
    }, {
        belongs_to_layer_mask = 2,
        collides_with_layer_mask = 1,
        radius = 0.2,
        take_damage = false,
    }, caster_position.x, caster_position.y, 1, 1, 0, 0)

    DCEI.ApplySimpleMoverSineWave(
        missile_simple_unit, --unit
        5, --amplitude
        1, --periodSeconds
        0, --startSeconds
        1.0625 --endSeconds
    )

CreateSimpleUnitAsync
CreateSimpleUnitSync

void ApplySimpleMoverTargetLocation(unit unit, Float3 targetLocation, float speed, float accelerationMagnitude, float startSeconds, float endSeconds)

void ApplySimpleMoverTargetLocation(unit unit, Float3 targetLocation, float speed, float accelerationMagnitude, float startSeconds, float endSeconds)

Description

Applies a simple mover to a simple unit which moves it toward a target location.

Parameters

unit unit simple unit to apply the mover to.
Float3 targetLocation target location in world space as a table of x,y,z values.
float speed missile speed.
float accelerationMagnitude acceleration magnituide.
float startSeconds duration before the acceleration begins.
float endSeconds time when the acceleration will end. e.g. The total duration will be endSeconds - startSeconds

Example Usage

    local target_location = {x = 0.0, y = 12.0, z = 0.5}

    local missile_simple_unit = DCEI.CreateSimpleUnit(2, {
        max_health = 10,
        type_name = DCEI.Unit("simple_missile_type"),
    }, {
        belongs_to_layer_mask = 2,
        collides_with_layer_mask = 1,
        radius = 0.2,
        take_damage = false,
    }, caster_position.x, caster_position.y, 1, 1, 0, 0)

    DCEI.ApplySimpleMoverTargetUnit(
        missile_simple_unit, --unit
        target_location, --targetLocation
        15, --speed
        5, --accelerationMagnitude
        0, --startSeconds
        1.0625 --endSeconds
    )

CreateSimpleUnitAsync
CreateSimpleUnitSync

void SetCollisionDamageData(unit unit, CollisionDamageApplierOptions options)

void SetCollisionDamageData(unit unit, CollisionDamageApplierOptions options)

Description

Enable applying damage on collision for a given unit.

Parameters

unit unit simple unit to issue move command to
CollisionDamageApplierOptions options a table of options with timing, cooldown, and deal_damage_value

Example Usage

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

void SetCollisionEffectTriggers(unit unit, SimpleUnitCastEffectOptions options)

void SetCollisionEffectTriggers(unit unit, SimpleUnitCastEffectOptions options)

Description

In development internal API.
No example usage yet

Parameters

Example Usage

In development internal API.
No example usage yet

void SetArmorData(unit unit, SimpleUnitArmorOptions options)

void SetArmorData(unit unit, SimpleUnitArmorOptions options)

Description

In development internal API.
No example usage yet

Parameters

Example Usage

In development internal API.
No example usage yet

void SetCollisionForceData(unit unit, CollisionForceApplierOptions options)

void SetCollisionForceData(unit unit, CollisionForceApplierOptions options)

Description

Enable applying force on collision for a given unit.

Parameters

unit unit simple unit to issue move command to
CollisionForceApplierOptions options a table of options with timing, cooldown, and deal_damage_value

Example Usage

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

void SetCollisionStatsData(unit unit, CollisionStatsApplierOptions options)

void SetCollisionStatsData(unit unit, CollisionStatsApplierOptions options)

Description

Enable applying stats on collision for unit.

Experimental API: Not intended for wide use

Parameters

unit unit simple unit to issue move command to
CollisionStatsApplierOptions options a table of options stats_id, delta_value

Example Usage

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

void SetCollisionMovementSpeedModifierData(unit unit, CollisionMovementSpeedModifierApplierOptions options)

void SetCollisionMovementSpeedModifierData(unit unit, CollisionMovementSpeedModifierApplierOptions options)

Description

Added API DCEI.SetCollisionMovementSpeedModifierData(Unit unit, CollisionMovementSpeedModifierApplierOptions options) and field collision_movement_speed_modifier_applier_options in SimpleUnitTypeOptions, field type is CollisionMovementSpeedModifierApplierOptions.
Once set, if it collides with other moving units, the defined movement speed modifier would be applied to them

CollisionMovementSpeedModifierApplierOptions:

BehaviorModifier modifier
float duration_seconds
CollisionTiming timing
float cooldown_seconds

Parameters

unit unit unit target
CollisionMovementSpeedModifierApplierOptions options the options for collision speed modifier

Example Usage

EXPERIMENTAL / IN-DEVELOPMENT / INTERNAL API
No official documentation.

void SetSimpleUnitToDestroySelfOnCollision(unit unit)

void SetSimpleUnitToDestroySelfOnCollision(unit unit)

Description

Set simple unit to destroy self on collision. For more info about simple units, see Simple Units Guide.

Parameters

unit unit target unit to enable self-destruction on collision

Example Usage

DCEI.SetSimpleUnitToDestroySelfOnCollision(unit)

void SetCollisionComponentData(unit unit, CollisionOptions options)

void SetCollisionComponentData(unit unit, CollisionOptions options)

Description

Enable collision for unit, with options

Parameters

unit unit target unit to enable self-destruction on collision
CollisionOptions options table of collision options, including radius, take_damage, and collision layers

Example Usage

-- Setup Collision Data
DCEI.SetCollisionComponentData(self.unit, {
    belongs_to_layer_mask = 1,
    collides_with_layer_mask = 3,
    take_damage = false,
    radius = 3,
})

void RegisterSimpleUnitType(string name, SimpleUnitTypeOptions options)

void RegisterSimpleUnitType(string name, SimpleUnitTypeOptions options)

Description

Parameters

string name name of simple unit type
SimpleUnitTypeOptions options table of simple unit type options.

Example Usage

function RegisterUnitType(unit_data, life, damage, speed, mass)
    local player_id = -1
    local team_id = -1
    local default_armor = 0
    local default_loot = 0
    local default_timing = 1 -- OnStart

    local meta_data = {
        type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
    }
    local health_data = {
        max = 6, -- The Maximum Health of the Unit.
        value = 6, -- The Current Health of the Unit.
    }
    local armor_data = {
        type = default_armor, -- Index for armor type.
    }
    local loot_data = {
        loot_id = default_loot, -- 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 local_avoidance_data = {
        enabled = false, -- Navigates around collisions.
    }
    local mover_data = {
        enabled = false,
    }
    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.
    }
    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 collision_force_data = {
        horizontal_force = 1.0,
        horizontal_friction = 0.1,
        vertical_force = 0.1,
        vertical_friction = 0.01,
        duration = 0.25,
        timing = default_timing,
        only_trigger_on_kill = false,
        cooldown_seconds = 0.25,
    }
    local collision_stats_data = {
        stats_name = "Spunk",
        delta_value = 1.0,
        timing = default_timing
    }
    local collision_movement_speed_modifier_applier_data = {
        modifier = {
            scaled = 0.0,
            unscaled = 1.0,
            additive_factor = 0.0,
            positive_unified_factor = 0.0,
            negative_unified_factor = 0.0,
            multiplier_factor = 0.0,
        },
        duration_seconds = 1.0,
        timing = default_timing,
        cooldown_seconds = 1.0,
    }
    local cast_effect_data = {
        collision_effects = {
            {
                timing = default_timing,
                effect_name = DCEI.Effect("Hostile - Runner Collide Effect"),
                cooldown_seconds = 1.0,
                tag_mask_filter = 0,
            },
        },
        on_death = DCEI.Effect("Hostile - Runner Death Effect"),
    }
    local tag_data = {
        value = 1,
    }
    local timer_data = {
        remove_unit_after_seconds = 10.0, -- Removes the Unit after a duration.
        kill_unit_after_seconds = 9.0, -- Kills the Unit after a duration.
    }
    local animator_data = {
        shadow_options = {
            enabled = true,
            shadow_radius = 0.5,
        },
        death_particle_effects = {1, 2, 3},
        animation_options = {
            enabled = true,
            frame_rate = 30.0,
        },
    }
    local options = {
        meta = meta_data,
        health_options = health_data,
        armor_options = armor_data,
        loot_options = loot_data,
        movement_options = movement_data,
        local_avoidance_options = local_avoidance_data,
        mover_options = mover_data,
        collision_options = collision_data,
        collision_damage_applier_options = collision_damage_data,
        collision_force_applier_options = collision_force_data,
        collision_stats_applier_options = collision_stats_data,
        collision_movement_speed_modifier_applier_options = collision_speed_data,
        cast_effect_options = cast_effect_data,
        tag_options = tag_data,
        timer_options = timer_data,
        mass = 2.0,
        animator_options = animator_data,
    }

    -- Register the simple unit type ...
    DCEI.RegisterSimpleUnitType(unit_data.Name, options)
    return unit_data.Name
end

void RegisterSimpleDamageAffinity(SimpleDamageAffinityOptions options)

void RegisterSimpleDamageAffinity(SimpleDamageAffinityOptions options)

Description

Parameters

SimpleDamageAffinityOptions options options. See SimpleDamageAffinityOptions

Example Usage

-- declare enum for damage types and armor types
local DamageTypes = {
    DEFAULT = 0,
    PHYSICAL = 1,
    MAGICAL = 2,
}

local ArmorTypes = {
    DEFAULT = 0,
    LIGHT = 1,
    MEDIUM = 2,
    HEAVY = 3,
}

-- register defender with ArmorTypes.HEAVY
DCEI.RegisterSimpleUnitType("StandardDummy", {
    meta = { type_name = DCEI.SimpleUnit("Standard MeleeUnit")},
    collision_options = {
        belongs_to_layer_mask = 1,
        collides_with_layer_mask = 2,
        radius = 0.2,
    },
    health_options = {
        max = 1000000000,
    },
    armor_options = {
        type = ArmorTypes.HEAVY,
    }
})

-- register damage affinities
DCEI.RegisterSimpleDamageAffinity({
    entries = {
        {
            damage_type = DamageTypes.MAGICAL,
            armor_type = ArmorTypes.HEAVY,
            damage_modifier = {
                additive_factor = 0.5,
            }
        },
        {
            damage_type = DamageTypes.PHYSICAL,
            armor_type = ArmorTypes.HEAVY,
            damage_modifier = {
                unscaled = -50,
            }
        }
    }
})

-- register missile with DamageTypes.PHYSICAL
DCEI.RegisterSimpleUnitType("StandardMissile", {
    meta = { type_name = DCEI.SimpleUnit("StandardMissile")},
    movement_options = { max_speed = 1 },
    collision_options = {
        belongs_to_layer_mask = 2,
        collides_with_layer_mask = 1,
        radius = 0.5,
    },
    collision_damage_applier_options = {
        timing = 1,
        deal_damage = {
            damage_type = DamageTypes.PHYSICAL,
            damage_value = 100,
            style_index = 0,
            critical_damage_chance = 0.1,
            critical_damage_multiplier = 10,
            critical_damage_style_index = 1,
            stats_name = example_stats,
        },
    },
})

void RegisterSimpleDamageNumberStyles(SimpleDamageNumberStyleOptions options)

void RegisterSimpleDamageNumberStyles(SimpleDamageNumberStyleOptions options)

Description

Register a simple damage number style. These text settings will be used when this style is used when calling DCEI.ShowSimpleDamageNumber

Parameters

SimpleDamageNumberStyleOptions options the settings for this 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,
    })

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

void SetDefaultSimpleDamageNumberStyle(SimpleDamageNumberStyleOptions options)

void SetDefaultSimpleDamageNumberStyle(SimpleDamageNumberStyleOptions options)

Description

Sets the default style for simple damage numbers.

Parameters

SimpleDamageNumberStyleOptions options the settings for this style.

Example Usage

DCEI.SetDefaultSimpleDamageNumberStyle({
    font_type = 1,
    duration_seconds = 0.9,
    distance_between_digits = {
        x = 0.4,
        y = 0,
        z = 0,
    },
})

void AddTransformAnimationToSimpleDamageNumberStyle(int idx, SimpleUnitTransformAnimationOptions options)

void AddTransformAnimationToSimpleDamageNumberStyle(int idx, SimpleUnitTransformAnimationOptions options)

Description

Add a transform animation to an simple number style registered with DCEI.RegisterSimpleDamageNumberStyles

Parameters

int idx index of the style to add the transform to.
SimpleUnitTransformAnimationOptions options the settings for the transform animation.

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

void AddTintColorAnimationToSimpleDamageNumberStyle(int idx, SimpleUnitTintColorAnimationOptions options)

void AddTintColorAnimationToSimpleDamageNumberStyle(int idx, SimpleUnitTintColorAnimationOptions options)

Description

Add a tint animation to an simple number style registered with DCEI.RegisterSimpleDamageNumberStyles

Parameters

int idx index of the style to add the tint animation to.
SimpleUnitTintColorAnimationOptions options the settings for the tint animation.

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

void ShowSimpleDamageNumber(unit unit, int styleType, float damageValue)

void ShowSimpleDamageNumber(unit unit, int styleType, float damageValue)

Description

Display a simple damage number over a unit, using a style registered with DCEI.RegisterSimpleDamageNumberStyles.

Parameters

unit unit the unit for the damage number to appear above.
int styleType the style registered with DCEI.RegisterSimpleDamageNumberStyles.
float damageValue number value to display in the damage text.

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

unit CreateSimpleUnitAsync(string name, SimpleUnitInstanceOptions options)

unit CreateSimpleUnitAsync(string name, SimpleUnitInstanceOptions options)

Description

Create instances of Simple Unit Type that has been registered with RegisterSimpleUnitType

Parameters

string name name of simple unit type registered with RegisterSimpleUnitType
SimpleUnitInstanceOptions options unit creation options

Example Usage

local player_id = -1
local team_id = -1
local default_armor = 0
local default_loot = 0
local default_timing = 1 -- OnStart

local meta_data = {
    type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
}
local health_data = {
    max = 6, -- The Maximum Health of the Unit.
    value = 6, -- The Current Health of the Unit.
}
local armor_data = {
    type = default_armor, -- Index for armor type.
}
local loot_data = {
    loot_id = default_loot, -- 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 local_avoidance_data = {
    enabled = false, -- Navigates around collisions.
}
local mover_data = {
    enabled = false,
}
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.
}
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 collision_force_data = {
    horizontal_force = 1.0,
    horizontal_friction = 0.1,
    vertical_force = 0.1,
    vertical_friction = 0.01,
    duration = 0.25,
    timing = default_timing,
    only_trigger_on_kill = false,
    cooldown_seconds = 0.25,
}
local collision_stats_data = {
    stats_name = "Spunk",
    delta_value = 1.0,
    timing = default_timing
}
local collision_movement_speed_modifier_applier_data = {
    modifier = {
        scaled = 0.0,
        unscaled = 1.0,
        additive_factor = 0.0,
        positive_unified_factor = 0.0,
        negative_unified_factor = 0.0,
        multiplier_factor = 0.0,
    },
    duration_seconds = 1.0,
    timing = default_timing,
    cooldown_seconds = 1.0,
}
local cast_effect_data = {
    collision_effects = {
        {
            timing = default_timing,
            effect_name = DCEI.Effect("Hostile - Runner Collide Effect"),
            cooldown_seconds = 1.0,
            tag_mask_filter = 0,
        },
    },
    on_death = DCEI.Effect("Hostile - Runner Death Effect"),
}
local tag_data = {
    value = 1,
}
local timer_data = {
    remove_unit_after_seconds = 10.0, -- Removes the Unit after a duration.
    kill_unit_after_seconds = 9.0, -- Kills the Unit after a duration.
}
local animator_data = {
    shadow_options = {
        enabled = true,
        shadow_radius = 0.5,
    },
    death_particle_effects = {1, 2, 3},
    animation_options = {
        enabled = true,
        frame_rate = 30.0,
    },
}
local options = {
    meta = meta_data,
    health_options = health_data,
    armor_options = armor_data,
    loot_options = loot_data,
    movement_options = movement_data,
    local_avoidance_options = local_avoidance_data,
    mover_options = mover_data,
    collision_options = collision_data,
    collision_damage_applier_options = collision_damage_data,
    collision_force_applier_options = collision_force_data,
    collision_stats_applier_options = collision_stats_data,
    collision_movement_speed_modifier_applier_options = collision_speed_data,
    cast_effect_options = cast_effect_data,
    tag_options = tag_data,
    timer_options = timer_data,
    mass = 2.0,
    animator_options = animator_data,
}

-- Register the simple unit type ...
DCEI.RegisterSimpleUnitType("Hostile - Runner", options)

-- ... then create an instance of it.
DCEI.CreateSimpleUnitAsync("Hostile - Runner", {
    player_id = player_id,
    team_id = team_id,
    position = { x = 15, y = 0, z = 15 },
    facing = { x = 0, y = 0 },
    velocity = { x = 1, y = 0, z = 1 },
    move_target_unit = nil, -- Unit reference
    move_target_position = nil, -- {x,y,z}
    move_target_direction = nil, -- {x,y,z}
})

unit CreateSimpleUnitSync(string name, SimpleUnitInstanceOptions options)

unit CreateSimpleUnitSync(string name, SimpleUnitInstanceOptions options)

Description

Create instances of Simple Unit Type that has been registered with RegisterSimpleUnitType. its parameters are the same as DCEI.CreateSimpleUnitAsync, but it would return an Unit for further operations

Parameters

string name name of simple unit type registered with RegisterSimpleUnitType
SimpleUnitInstanceOptions options unit creation options

Example Usage

local player_id = -1
local team_id = -1
local default_armor = 0
local default_loot = 0
local default_timing = 1 -- OnStart

local meta_data = {
    type_name = DCEI.SimpleUnit("Hostile - Runner"), -- A Registered Simple Unit.
}
local health_data = {
    max = 6, -- The Maximum Health of the Unit.
    value = 6, -- The Current Health of the Unit.
}
local armor_data = {
    type = default_armor, -- Index for armor type.
}
local loot_data = {
    loot_id = default_loot, -- 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 local_avoidance_data = {
    enabled = false, -- Navigates around collisions.
}
local mover_data = {
    enabled = false,
}
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.
}
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 collision_force_data = {
    horizontal_force = 1.0,
    horizontal_friction = 0.1,
    vertical_force = 0.1,
    vertical_friction = 0.01,
    duration = 0.25,
    timing = default_timing,
    only_trigger_on_kill = false,
    cooldown_seconds = 0.25,
}
local collision_stats_data = {
    stats_name = "Spunk",
    delta_value = 1.0,
    timing = default_timing
}
local collision_movement_speed_modifier_applier_data = {
    modifier = {
        scaled = 0.0,
        unscaled = 1.0,
        additive_factor = 0.0,
        positive_unified_factor = 0.0,
        negative_unified_factor = 0.0,
        multiplier_factor = 0.0,
    },
    duration_seconds = 1.0,
    timing = default_timing,
    cooldown_seconds = 1.0,
}
local cast_effect_data = {
    collision_effects = {
        {
            timing = default_timing,
            effect_name = DCEI.Effect("Hostile - Runner Collide Effect"),
            cooldown_seconds = 1.0,
            tag_mask_filter = 0,
        },
    },
    on_death = DCEI.Effect("Hostile - Runner Death Effect"),
}
local tag_data = {
    value = 1,
}
local timer_data = {
    remove_unit_after_seconds = 10.0, -- Removes the Unit after a duration.
    kill_unit_after_seconds = 9.0, -- Kills the Unit after a duration.
}
local animator_data = {
    shadow_options = {
        enabled = true,
        shadow_radius = 0.5,
    },
    death_particle_effects = {1, 2, 3},
    animation_options = {
        enabled = true,
        frame_rate = 30.0,
    },
}
local options = {
    meta = meta_data,
    health_options = health_data,
    armor_options = armor_data,
    loot_options = loot_data,
    movement_options = movement_data,
    local_avoidance_options = local_avoidance_data,
    mover_options = mover_data,
    collision_options = collision_data,
    collision_damage_applier_options = collision_damage_data,
    collision_force_applier_options = collision_force_data,
    collision_stats_applier_options = collision_stats_data,
    collision_movement_speed_modifier_applier_options = collision_speed_data,
    cast_effect_options = cast_effect_data,
    tag_options = tag_data,
    timer_options = timer_data,
    mass = 2.0,
    animator_options = animator_data,
}

-- Register the simple unit type ...
DCEI.RegisterSimpleUnitType("Hostile - Runner", options)

-- ... then create an instance of it.
local new_unit = DCEI.CreateSimpleUnitSync("Hostile - Runner", {
    player_id = player_id,
    team_id = team_id,
    position = { x = 15, y = 0, z = 15 },
    facing = { x = 0, y = 0 },
    velocity = { x = 1, y = 0, z = 1 },
    move_target_unit = nil, -- Unit reference
    move_target_position = nil, -- {x,y,z}
    move_target_direction = nil, -- {x,y,z}
})

int RegisterSimpleLoot(string lootName, string unitName, SimpleUnitInstanceOptions options)

int RegisterSimpleLoot(string lootName, string unitName, SimpleUnitInstanceOptions options)

Description

Parameters

string lootName name of loot
string unitName name of simple unit type
SimpleUnitInstanceOptions options options SimpleUnitInstanceOptions

Example Usage

Experimental / in-development / internal API
No example usage

void SetSimpleUnitLootData(unit unit, string name, float dropRate)

void SetSimpleUnitLootData(unit unit, string name, float dropRate)

Description

Set simple unit to have a chance to drop loot that was previously registered with the same name using DCEI.RegisterSimpleLoot. For more info about simple units, see Simple Units Guide.

Parameters

unit unit the unit to add the chance of dropping loot to
string name name index of loot, previously registered with DCEI.RegisterSimpleLoot
float dropRate the chance to drop loot

Example Usage

local unit_options = {
    type_name = DCEI.Unit("XP Item"),
    max_health = 1,
    drop_rate = 0,
}
local collision_options = {
    belongs_to_layer_mask = 1,
    collides_with_layer_mask = 2,
    radius = 0.5,
    take_damage = false,
}
local collision_stats = {
    stats_id = 1,
    delta_value = reward,
}

DCEI.RegisterSimpleLoot("basic_loot", unit_options, collision_options, collision_stats)
DCEI.SetSimpleUnitLootData(unit, "basic_loot", 1.00)

unit CreateUnitAsync(int teamId, int playerId, string unitType, float x, float z, float dx = 0, float dz = 1)

unit CreateUnitAsync(int teamId, int playerId, string unitType, float x, float z, float dx = 0, float dz = 1)

Description

Creates a unit at the specified location using default facing. Asynchronous, meaning the unit may not finish initializing until the next frame. Wait a full frame before trying to reference the created unit with other APIs.

Parameters

int teamId which team to create the unit for. Use 1 for local player and -1 for enemy.
int playerId which player to create the unit for. Use 1 for local player and -1 for enemy.
string unitType name of data for the unit type to create
float x the x coordinate of where to create the unit.
float z the y coordinate of where to create the unit.
float dx a value between -1.0 and 1.0 that indicates the relative direction to face along the x-axis.
float dz a value between -1.0 and 1.0 that indicates the relative direction at to face along y-axis.

Example Usage

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

unit CreateChildUnit(unit parent, string unitType, float x, float z, float dx = 0, float dz = 1)

unit CreateChildUnit(unit parent, string unitType, float x, float z, float dx = 0, float dz = 1)

Description

Creates a child unit for a parent unit. Used for Wild Sky to create pets that follow and defend parent units.

Parameters

unit parent parent unit to create this unit under.
string unitType name of data for the unit type to create
float x the x coordinate of where to create the unit.
float z the y coordinate of where to create the unit.
float dx a value between -1.0 and 1.0 that indicates the relative direction to face along the x-axis.
float dz a value between -1.0 and 1.0 that indicates the relative direction at to face along y-axis.

Example Usage

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

DCEI.CreateChildUnit(parent_unit, unit_type, x + 1, y + 1)

unit CreateChildUnitAsync(unit parent, string unitType, float x, float z)

unit CreateChildUnitAsync(unit parent, string unitType, float x, float z)

Description

Creates a child unit for a parent unit. Used for Wild Sky to create pets that follow and defend parent units. Asynchronous, meaning the unit may not be created/initialized on the same frame. Wait a full frame before trying to reference the created unit.

Parameters

unit parent parent unit to create this unit under.
string unitType name of data for the unit type to create
float x the x coordinate of where to create the unit.
float z the y coordinate of where to create the unit.

Example Usage

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

DCEI.CreateChildUnitAsync(parent_unit, unit_type, x + 1, y + 1)

void KillUnit(unit unit)

void KillUnit(unit unit)

Description

Kills a unit.

Parameters

unit unit the unit to kill.

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)
DCEI.KillUnit(unit)

TriggerAddUnitDiedEvent

void RemoveUnit(unit unit)

void RemoveUnit(unit unit)

Description

Removes a unit.

Parameters

unit unit the unit to remove.

Example Usage

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

TriggerAddUnitRemovedEvent

void RemoveSimpleUnit(unit unit)

void RemoveSimpleUnit(unit unit)

Description

Remove a simple unit, without triggering death effects.

Parameters

unit unit the unit to remove.

Example Usage

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,
})
DCEI.RemoveSimpleUnit(unit)

CreateSimpleUnitAsync
CreateSimpleUnitSync

void KillSimpleUnit(unit unit)

void KillSimpleUnit(unit unit)

Description

Kill simple unit.

Parameters

unit unit the unit to kill.

Example Usage

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,
})
DCEI.KillSimpleUnit(unit)

string GetUnitType(unit unit)

string GetUnitType(unit unit)

Description

Returns the unit name as a string.

Parameters

unit unit the unit to get the name of.

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 unit_type = DCEI.GetUnitType(unit)

-- prints "Standard MeleeUnit
DCEI.LogMessage(unit_name)

double GetUnitTypeHealth(string unitType)

double GetUnitTypeHealth(string unitType)

Description

Returns the maximum health for a unit type.

Parameters

string unitType the unit type to get the health of.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local health = DCEI.GetUnitTypeHealth(unit_type)
DCEI.LogMessage(health)

Max Health (Data)

string GetUnitDisplayName(unit unit)

string GetUnitDisplayName(unit unit)

Description

Returns the Display Name of a unit as a string.

Parameters

unit unit the unit whose display name to get.

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 display_name = DCEI.GetUnitDisplayName(unit)
DCEI.LogMessage(display_name)

Display Name (Data)

string GetUnitCategory(unit unit)

string GetUnitCategory(unit unit)

Description

Returns the unit category of a unit as a string (Unit, Missile, or Structure).

Parameters

unit unit the unit whose unit category to get.

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 unit_category = DCEI.GetUnitCategory(unit)

-- prints "Unit"
DCEI.LogMessage(unit_category)

void AttachSimpleUnitToCursor(unit unit)

void AttachSimpleUnitToCursor(unit unit)

Description

Added DCEI.AttachSimpleUnitToCursor(unit) and DCEI.DetachSimpleUnitFromCursor, only actor is attached, the unit stays where it was, when detach, the animator reappear at original position

Parameters

unit unit the unit whose unit category to get.

Example Usage

In-development API
No documentation

void DetachSimpleUnitFromCursor(unit unit)

void DetachSimpleUnitFromCursor(unit unit)

Description

Added DCEI.AttachSimpleUnitToCursor(unit) and DCEI.DetachSimpleUnitFromCursor, only actor is attached, the unit stays where it was, when detach, the animator reappear at original position

Parameters

unit unit the unit whose unit category to get.

Example Usage

In-development API
No documentation

void PlaySimpleUnitAnimationClip(unit unit, string clipName, string nextClipName)

void PlaySimpleUnitAnimationClip(unit unit, string clipName, string nextClipName)

Description

Plays an animation clip on a simple unit, then loops the next animation clip.

The following clip names are supported:

"cmd_remove" // reserved keyword, remove animator
"cmd_pause" // reserved keyword, stop playing animation
"attack" 
"die" 
"death" 
"idle" 
"walk" 
"action" 
"action1" 
"build" 
"select" 
"close" 
"open" 
"flying" 
"action2" 
"hit" 
"birth" 
"action3" 
"action4" 
"action5" 
"fidget" 
"attack1" 
"victory" 
"jump_start" 
"jump" 
"jump_end" 
"channeling_start" 
"channeling" 
"channeling_end" 
"attack2" 
"dodge" 
"walk2" 
"walk3" 
"walk4" 
"walk5" 
"vfx_fadeout" 
"sfx_loop"

Parameters

unit unit the unit that will play an animation clip.
string clipName the clip name to play for the unit.
string nextClipName the clip name to loop after clipName finishes playing.

Example Usage

    local simple_unit = DCEI.CreateSimpleUnit(2, {
        max_health = 10,
        type_name = DCEI.Unit("simple_unit_type"),
    }, {
        belongs_to_layer_mask = 2,
        collides_with_layer_mask = 1,
        radius = 0.2,
        take_damage = false,
    }, position.x, position.y, 1, 1, 0, 0)

    DCEI.PlaySimpleUnitAnimationClip(
        simple_unit, --unit
        "attack", --clipName
        "idle" --nextClipName
    )

CreateSimpleUnitAsync
CreateSimpleUnitSync

void AttachUnit(unit childUnit, unit parentUnit, AttachOffsetOptions option)

void AttachUnit(unit childUnit, unit parentUnit, AttachOffsetOptions option)

Description

Attach two units.

You can use AttachUnit to attach a "Simple" unit to a "Normal" unit. It's bridge for Simple/Complex units working together.

Parameters

unit childUnit the child unit in attach.
unit parentUnit the parent unit in attach.
AttachOffsetOptions option 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" }
)

void DetachUnit(unit unit)

void DetachUnit(unit unit)

Description

If unit is attached to a parent unit, detach this unit from it's parent unit.

Parameters

unit unit the unit to detach.

Example Usage

local child_unit = DCEI.FindUnit("Archer")
DCEI.DetachUnit(child_unit)

void Move(unit unit, float x, float z)

void Move(unit unit, float x, float z)

Description

Issues an order for a unit to move to a target point.

Parameters

unit unit the unit instance to issue the move command to.
float x the x-axis coordinate to move towards.
float z the z-axis coordinate to move towards.

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)

DCEI.TriggerAddUnitMoveCommandEvent(unit, OnUnitMoveCommand)

function OnUnitMoveCommand(destination)
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    local position = DCEI.GetUnitPosition2D(unit)

    local message = string.format("%q is moving to (%.2f, %.2f) from (%.2f, %.2f).", unit_name, destination.x, destination.y, position.x, position.y)
    DCEI.LogMessage(message)
end

DCEI.Move(unit, 15, 15)

void Attack(unit unit, unit target)

void Attack(unit unit, unit target)

Description

Issues an order for a unit to attack another unit, causing it to move to get in range if necessary.

Parameters

unit unit the attacking unit.
unit target the unit to attack.

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 target = DCEI.CreateUnit(team_id, player_id, unit_type, x + 1, y + 1)

DCEI.Attack(unit, target)

MoveAttack

void DirectionalMove(unit target, float right, float up)

void DirectionalMove(unit target, float right, float up)

Description

Issues an order for the unit to move in a specified direction.

Notes: The unit will not attempt to navigate around units or obstacles when using Directional Move. This function only runs for a single frame. To have the unit continue to move in a specific direction, this function must be run each frame. This useful for games with that use WASD or joystick movement to control units.

Parameters

unit target the unit to move.
float right a value between -1.0 and 1.0 that indicates the relative speed and direction to move along the x-axis.
float up a value between -1.0 and 1.0 that indicates the relative speed and direction to move along the y-axis.

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)

function OnJoystickMove()
    local axes = DCEI.TriggeringJoystickAxes
    -- order unit to move in direction of joystick axes
    DCEI.LogMessage("(" .. axes.x .. ", " .. axes.y .. ")")
    DCEI.DirectionalMove(unit, axes.x, axes.y)
end

DCEI.TriggerAddJoystickEvent(OnJoystickMove)

void TurnUnitTowards(unit unit, float dx, float dz, float duration = 0)

void TurnUnitTowards(unit unit, float dx, float dz, float duration = 0)

Description

Turns a unit to face towards a specified direction.

Parameters

unit unit the unit to turn.
float dx a value between -1.0 and 1.0 that indicates the relative direction to face along the x-axis.
float dz a value between -1.0 and 1.0 that indicates the relative direction at to face along y-axis.
float duration duration of time the turning takes

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)

-- Make the unit face southwest
DCEI.TurnUnitTowards(unit, -1.0,-1.0, 3.0)

GetUnitFacing2D
GetUnitRotationEuler
SetUnitRotationEuler

float GetHealth(unit unit)

float GetHealth(unit unit)

Description

Returns the current health of a unit.

Parameters

unit unit the unit to check.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealth(unit, 5)
    DCEI.SetMaxHealth(unit, 30)
    local hp = DCEI.GetHealth(unit)
    local max_hp = DCEI.GetMaxHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")

    DCEI.AddHealth(unit, 10)
    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")
end, 
0)

void AddHealth(unit unit, float value)

void AddHealth(unit unit, float value)

Description

Increases the current health of a unit.

Parameters

unit unit the unit to add health to.
float value the amount of health to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealth(unit, 5)
    DCEI.SetMaxHealth(unit, 30)
    local hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. " hp currently.")

    DCEI.AddHealth(unit, 10)
    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. " hp currently.")
end, 
0)

void AddHealthAsync(unit unit, float value)

void AddHealthAsync(unit unit, float value)

Description

Increases the current health of a unit. Async, meaning it may not happen on this exact frame.

Parameters

unit unit the unit to add health to.
float value the amount of health to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealth(unit, 5)
    DCEI.SetMaxHealth(unit, 30)
    local hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. " hp currently.")

    DCEI.AddHealthAsync(unit, 10)

    DCEI.Wait(1)

    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. " hp currently.")
end, 
0)

void SetHealth(unit unit, float value)

void SetHealth(unit unit, float value)

Description

Sets the current health of a unit.

Parameters

unit unit the unit to set the health of.
float value the amount to set it to.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealth(unit, 5)
    DCEI.SetMaxHealth(unit, 30)
    local hp = DCEI.GetHealth(unit)
    local max_hp = DCEI.GetMaxHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")

    DCEI.AddHealth(unit, 10)
    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")
end, 
0)

void SetUnitOwner(unit unit, int playerId)

void SetUnitOwner(unit unit, int playerId)

Description

Sets the owner of a unit.

Parameters

unit unit the unit to change ownership of.
int playerId the player to give the unit to.

Example Usage

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

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

void SetUnitTeamId(unit unit, int teamId)

void SetUnitTeamId(unit unit, int teamId)

Description

Sets the team id of a unit.

Parameters

unit unit the unit to change ownership of.
int teamId the team ID to assign to the unit.

Example Usage

function OnRegionEnter()
    DCEI.SetUnitTeamId(DCEI.TriggeringUnit, 2)
    DCEI.LogMessage(DCEI.UnitTeamId(DCEI.TriggeringUnit))
end

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

void SetHealthValueAsync(unit unit, float amount)

void SetHealthValueAsync(unit unit, float amount)

Description

Sets the current health of a unit. Asynchronous, so may not happen on this exact frame.

Parameters

unit unit the unit to set the health of.
float amount the amount to set it to.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealthValueAsync(unit, 5)
    DCEI.SetMaxHealth(unit, 30)

    DCEI.Wait(1)

    local hp = DCEI.GetHealth(unit)
    local max_hp = DCEI.GetMaxHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")

    DCEI.AddHealth(unit, 10)
    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")
end, 
0)

float GetMana(unit unit)

float GetMana(unit unit)

Description

Returns the current mana of a unit.

Parameters

unit unit the unit to check.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxMana(unit, 20)
    DCEI.SetMana(unit, 5)
    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddMana(unit, 10)
    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0)

void AddMana(unit unit, float value)

void AddMana(unit unit, float value)

Description

Increases the current mana of a unit.

Parameters

unit unit the unit to add mana to.
float value the amount to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxMana(unit, 20)
    DCEI.SetMana(unit, 5)
    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddMana(unit, 10)
    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0)

void AddManaAsync(unit unit, float value)

void AddManaAsync(unit unit, float value)

Description

Increases the current mana of a unit. Asychronous, so may not occur on this frame.

Parameters

unit unit the unit to add mana to.
float value the amount to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxMana(unit, 20)
    DCEI.SetMana(unit, 5)
    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddManaAsync(unit, 10)

    DCEI.Wait(1)

    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0)

void SetMana(unit unit, float value)

void SetMana(unit unit, float value)

Description

Sets the current mana of a unit.

Parameters

unit unit the unit to add mana to.
float value the amount to set it to.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxMana(unit, 20)
    DCEI.SetMana(unit, 5)
    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddMana(unit, 10)
    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0)

void SetManaValueAsync(unit unit, float amount)

void SetManaValueAsync(unit unit, float amount)

Description

Sets the current mana of a unit. Asynchronous, so may take a simulation frame to occur.

Parameters

unit unit the unit to add mana to.
float amount the amount to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxMana(unit, 20)
    DCEI.SetManaValueAsync(unit, 5)

    DCEI.Wait(1)

    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddMana(unit, 10)
    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0)

Float2 GetUnitFacing2D(unit unit)

Float2 GetUnitFacing2D(unit unit)

Description

Returns the facing of a unit as a vector with X and Y coordinates.

Parameters

unit unit the unit to get the position of.

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 facing = DCEI.GetUnitFacing2D(unit)
DCEI.LogMessage(unit_type .. " is facing " .. facing.x .. ", " .. facing.y)

TurnUnitTowards
GetUnitRotationEuler
SetUnitRotationEuler
Float2

float GetUnitBounty(unit unit)

float GetUnitBounty(unit unit)

Description

Returns the SetGoldBounty of a unit.

Parameters

unit unit the unit to get the bounty of.

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)

DCEI.SetGoldBounty(unit, 5.0)
local bounty = DCEI.GetUnitBounty(unit)
DCEI.LogMessage(unit_type .. " has a bounty of " .. bounty .. " gold.")

SetGoldBounty

object GetUnitBehaviorList(unit unit)

object GetUnitBehaviorList(unit unit)

Description

Returns a list of behaviors on a unit along with their stack count.

Parameters

unit unit the unit to get the list of behaviors from.

Example Usage

local behaviors = DCEI.GetUnitBehaviorList(unit)
for _, behavior in ipairs(behaviors) do
    DCEI.LogMessage(behavior.name .. ": " .. behavior.stack_count)
end

object GetUnitWeaponList(unit unit)

object GetUnitWeaponList(unit unit)

Description

Returns a list of weapons on a unit.

Parameters

unit unit the unit to get the list of weapons from.

Example Usage

local weapons = DCEI.GetUnitWeaponList(unit)
for _, weapon in ipairs(weapons) do
    DCEI.LogMessage(weapon)
end

IsUnitWeaponEnabled

object GetUnitAbilityList(unit unit)

object GetUnitAbilityList(unit unit)

Description

Returns a list of abilities on a unit.

Parameters

unit unit the unit to get the list of abilities from.

Example Usage

local abilities = DCEI.GetUnitAbilityList(unit)
for _, ability in ipairs(abilities) do
    DCEI.LogMessage(ability)
end

void ApplyTag(unit unit, string tagName, float duration, int stackCount)

void ApplyTag(unit unit, string tagName, float duration, int stackCount)

Description

Applies a set number of tags to a unit for a set duration.

Parameters

unit unit the unit to apply the tags to.
string tagName the name of the tag to apply.
float duration the length of time to apply the tag for. A value of -1 applies it permanently.
int stackCount the number of tags to apply.

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)

void RemoveTag(unit unit, string tagName, int stackCount = 0)

void RemoveTag(unit unit, string tagName, int stackCount = 0)

Description

Removes a set number of tags from a unit.

Parameters

unit unit the unit to remove the tags from.
string tagName the name of the tag to remove.
int stackCount the number of tags to remove.

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)

int GetUnitTagCount(unit unit, string tagName)

int GetUnitTagCount(unit unit, string tagName)

Description

Returns the tag count of a given tag on a unit.

Parameters

unit unit the unit to count the tags on.
string tagName the name of the tag to 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)

object GetUnitTagList(unit unit)

object GetUnitTagList(unit unit)

Description

Returns a list of tags on a unit

Parameters

unit unit the unit to get the total damage of.

Example Usage

local tags = DCEI.GetUnitTagList(unit)
for _, tag in ipairs(tags) do
    DCEI.LogMessage(tag)
end

float GetUnitTotalDamage(unit unit)

float GetUnitTotalDamage(unit unit)

Description

Returns the total amount of damage a unit has dealt.

Parameters

unit unit the unit to get the total damage of.

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 total_damage = DCEI.GetUnitTotalDamage(unit)
DCEI.LogMessage(total_damage)

Float2 GetUnitRallyPoint(unit unit)

Float2 GetUnitRallyPoint(unit unit)

Description

Get the unit's rally point target, for Wild Sky units using a rally point ability.

Parameters

unit unit the unit to get the rally point for.

Example Usage

function TowerHunterHutCreateTraps(unit, quantity)
    local pos = DCEI.GetUnitPosition2D(unit)
    --local target = DCEI.FindClosestPointOnRoad(pos.x, pos.y, true)
    local target = DCEI.GetUnitRallyPoint(unit)
    for i = 1, quantity do
        DCEI.TriggerAddTimerEventElapsed(function()
            DCEI.CreateEffectAtPosition(
                "Tower HunterHut Trapmaster Trap Launch",
                unit,
                target.x + (math.random() * math.random(-1, 1) * 0.9),
                target.y + (math.random() * math.random(-1, 1) * 0.9)
            )
        end, i * 0.125)
    end
end

int GetUnitWaypointNodeIndex(unit unit)

int GetUnitWaypointNodeIndex(unit unit)

Description

Wild Sky only. Gets the index for the current node along a waypoint path that a unit is traveling, if the unit is currently travelling along a waypoint path. This can then be used with API's like ApplyWaypoint to make sure the unit resumes the waypoint at the same position it left it, if you temporarily interrupt the unit.

Parameters

unit unit the unit to get the waypoint node index for.

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, "GoblinWarshipFlyby", 0.5)
DCEI.Wait(5)
local node_index = DCEI.GetUnitWaypointNodeIndex(GoblinWarshipUnit)
DCEI.Stop(GoblinWarshipUnit)
DCEI.Wait(5)
DCEI.ApplyWaypoint(GoblinWarshipUnit, {
    waypoint_name = "GoblinWarshipFlyby",
    dispersal = 0.5,
    use_natural_dispersal = true,
    node_index = node_index
})

Float2 GetUnitPosition2D(unit unit)

Float2 GetUnitPosition2D(unit unit)

Description

Returns the position of a unit.

Parameters

unit unit the unit to get the position of.

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 position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

Float3 GetUnitPosition3D(unit unit)

Float3 GetUnitPosition3D(unit unit)

Description

Returns the 3D position of a unit.

Parameters

unit unit the unit to get the position of.

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 position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

void SetUnitPosition2D(unit unit, float x, float z)

void SetUnitPosition2D(unit unit, float x, float z)

Description

Sets the position of a unit.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

DCEI.SetUnitPosition2D(unit, 15, 15)

position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

SetUnitPosition2DWithInterpolation

void SetUnitPosition3D(unit unit, float x, float y, float z)

void SetUnitPosition3D(unit unit, float x, float y, float z)

Description

Sets the 3D position of a unit.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float y the y-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

DCEI.SetUnitPosition3D(unit, 15, 1, 15)

position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

SetUnitPosition3DWithInterpolation

void SetUnitPosition2DWithInterpolation(unit unit, float x, float z)

void SetUnitPosition2DWithInterpolation(unit unit, float x, float z)

Description

Sets the position of a unit while causing it to seemingly leap to that position.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

DCEI.SetUnitPosition2DWithInterpolation(unit, 15, 15)

position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

SetUnitPosition2D

void SetUnitPosition3DWithInterpolation(unit unit, float x, float y, float z)

void SetUnitPosition3DWithInterpolation(unit unit, float x, float y, float z)

Description

Sets the 3D position of a unit while causing it to seemingly leap to that position.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float y the y-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

DCEI.SetUnitPosition3DWithInterpolation(unit, 15, 1, 15)

position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

SetUnitPosition3D

void SetUnitPosition2DAsync(unit unit, float x, float z)

void SetUnitPosition2DAsync(unit unit, float x, float z)

Description

Sets the position of a unit. Asynchronous, so may not occur this simulation frame.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

DCEI.SetUnitPosition2DAsync(unit, 15, 15)

DCEI.Wait(0.0625) -- Wait because the API is async

position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

void SetUnitPosition3DAsync(unit unit, float x, float y, float z)

void SetUnitPosition3DAsync(unit unit, float x, float y, float z)

Description

Sets the 3D position of a unit. Asynchronous so may not occur this simulation frame.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float y the y-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

DCEI.SetUnitPosition3DAsync(unit, 15, 1, 15)

DCEI.Wait(0.0625) -- Wait since the API is async

position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

void SetUnitPosition2DWithInterpolationAsync(unit unit, float x, float z)

void SetUnitPosition2DWithInterpolationAsync(unit unit, float x, float z)

Description

Sets the position of a unit while causing it to seemingly leap to that position. Async so may not happen this simulation frame. Recommended you use the non-Async version.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

DCEI.SetUnitPosition2DWithInterpolationAsync(unit, 15, 15)

DCEI.Wait(0.0625) -- Wait because this is the Async version of this API.

position = DCEI.GetUnitPosition2D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y)

void SetUnitPosition3DWithInterpolationAsync(unit unit, float x, float y, float z)

void SetUnitPosition3DWithInterpolationAsync(unit unit, float x, float y, float z)

Description

Sets the 3D position of a unit while causing it to seemingly leap to that position. Async so may not occur this frame. Recommended you use the non-async version of this API.

Parameters

unit unit the unit to set the position of.
float x the x-axis coordinate of the new position.
float y the y-axis coordinate of the new position.
float z the z-axis coordinate of the new position.

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 position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

DCEI.SetUnitPosition3DWithInterpolationAsync(unit, 15, 1, 15)

DCEI.Wait(0.0625) -- Wait since this is the async version of the api

position = DCEI.GetUnitPosition3D(unit)
DCEI.LogMessage("Unit position " .. position.x .. ", " .. position.y .. ", " .. position.z)

Float3 GetUnitRotationEuler(unit unit)

Float3 GetUnitRotationEuler(unit unit)

Description

Returns the 3d facing of a unit as a set of Euler Angles.

Parameters

unit unit the unit to get the facing of.

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 rotation = DCEI.GetUnitRotationEuler(unit)
DCEI.LogMessage("Unit rotation: " .. rotation.x .. ", " .. rotation.y .. ", " .. rotation.z)

void SetUnitRotationEuler(unit unit, float x, float y, float z)

void SetUnitRotationEuler(unit unit, float x, float y, float z)

Description

Sets the facing of a unit using Euler Angles.

Parameters

unit unit the unit to set the facing of of.
float x the x-axis rotation.
float y the y-axis rotation.
float z the z-axis rotation.

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 rotation = DCEI.GetUnitRotationEuler(unit)
DCEI.LogMessage("Unit rotation: " .. rotation.x .. ", " .. rotation.y .. ", " .. rotation.z)

DCEI.SetUnitRotationEuler(unit,90, 150, 270)

rotation = DCEI.GetUnitRotationEuler(unit)
DCEI.LogMessage("Unit rotation: " .. rotation.x .. ", " .. rotation.y .. ", " .. rotation.z)

void MoveAttack(unit target, float x, float z)

void MoveAttack(unit target, float x, float z)

Description

Issues an order for a unit to move to a target point while attacking any enemies they come across while moving.

Parameters

unit target unit to issue the attack-move command to.
float x the x-axis coordinate of the target point.
float z the z-axis coordinate of the target point.

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 enemy = DCEI.CreateUnit(-1, -1, unit_type, 12, 12)

DCEI.MoveAttack(unit, 10, 10)

bool UnitExists(unit unit)

bool UnitExists(unit unit)

Description

Returns true if a units exists.

Parameters

unit unit the unit to check.

Example Usage

local status = false
DCEI.LogMessage(status)

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)

status = DCEI.UnitExists(unit) -- true
DCEI.LogMessage(status)

UnitIsAlive
UnitIsMoving

bool SimpleUnitExists(unit unit)

bool SimpleUnitExists(unit unit)

Description

Returns true if a simple unit exists.

Parameters

unit unit the simple unit to check.

Example Usage

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,
})
local exists = DCEI.SimpleUnitExists(unit)
DCEI.LogMessage(tostring(exists))

bool UnitIsAlive(unit unit)

bool UnitIsAlive(unit unit)

Description

Returns true if a unit is alive.

Parameters

unit unit the unit to check.

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 status = DCEI.UnitIsAlive(unit)
DCEI.LogMessage("Unit is " .. (status and "alive." or "dead."))

bool UnitIsMoving(unit unit)

bool UnitIsMoving(unit unit)

Description

Returns true if a unit is moving.

Parameters

unit unit the unit to check.

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 status = DCEI.UnitIsMoving(unit)
DCEI.LogMessage("Unit is " .. (status and "" or "not ") .. "moving.")

DCEI.Move(unit, 13, 13)
DCEI.TriggerAddTimerEventElapsed(function()
    status = DCEI.UnitIsMoving(unit)
    DCEI.LogMessage("Unit is " .. (status and "" or "not ") .. "moving.")
end, 0.5, false, true)

void EnableUnitSelection(unit target)

void EnableUnitSelection(unit target)

Description

Enables selection for a unit.

Parameters

unit target the unit to enable selection on.

Example Usage

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

DCEI.DisableUnitSelection(unit)
DCEI.EnableUnitSelection(unit)

void DisableUnitSelection(unit target)

void DisableUnitSelection(unit target)

Description

Disables selection for a unit.

Parameters

unit target the unit to disable selection on.

Example Usage

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

DCEI.DisableUnitSelection(unit)

void ShowUnitCustomHealthBar(unit unit, bool show)

void ShowUnitCustomHealthBar(unit unit, bool show)

Description

Enable or disable displaying a unit's custom health bar, defined in the unit's data.

Parameters

unit unit the unit to enable/disable custom health bar.
bool show if true, displays the unit's custom health bar; if false, disables the unit's custom health bar.

Example Usage

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

DCEI.ShowUnitCustomHealthBar(unit)

void ConfigStatusBar(Float3 OffsetInStatusDisplay, Float3 DistanceBetweenIcons, int MaxDisplayCount = 3)

void ConfigStatusBar(Float3 OffsetInStatusDisplay, Float3 DistanceBetweenIcons, int MaxDisplayCount = 3)

Description

Set global configuration for unit status bar for display of status icons, with an offset, a distance between icons, and a max display count. The status bar will display the highest priority status icons up to the maximum count.

Parameters

Float3 OffsetInStatusDisplay offset in world space from a host unit as a table of x,y,z values.
Float3 DistanceBetweenIcons distance between status icons in world space as a table of x,y,z values.
int MaxDisplayCount the maximum number of status icons that will be displayed on a host unit. Default value is 3.

Example Usage

offset = {x = 0, y = 0, z = 20}
distance = {x = 5, y = 1, z = 0}
max_count = 4
DCEI.ConfigStatusBar(offset, distance, max_count)

void RegisterBehaviorStatusIcon(string behaviorName, string actorName, int priority = 0)

void RegisterBehaviorStatusIcon(string behaviorName, string actorName, int priority = 0)

Description

Define a behavior for display in the status bar, with a behavior, status icon sprite actor, and a display priority.

Parameters

string behaviorName the name of the behavior to register.
string actorName the actor type that contains the status sprite.
int priority the display priority for the status icon. Default value is 0.

Example Usage

offset = {x = 0, y = 0, z = 20}
distance = {x = 5, y = 1, z = 0}
max_count = 4
DCEI.ConfigStatusBar(offset, distance, max_count)

behavior = DCEI.Behavior("Test Behavior")
actor = DCEI.Actor("Test Behavior")
priority = 10
DCEI.RegisterBehaviorStatusIcon(behavior, actor, priority)

float GetMaxShield(unit unit)

float GetMaxShield(unit unit)

Description

Returns the maximum shields of a unit.

Parameters

unit unit the unit to check.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShield(unit, 5)
    DCEI.SetMaxShield(unit,30)
    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShield(unit, 10)
    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

void SetMaxShield(unit unit, float value)

void SetMaxShield(unit unit, float value)

Description

Sets the maximum shields for a unit.

Parameters

unit unit the unit to modify.
float value the new maximum for the unit.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShield(unit, 5)
    DCEI.SetMaxShield(unit,30)
    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShield(unit, 10)
    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

void SetMaxShieldAsync(unit unit, float value)

void SetMaxShieldAsync(unit unit, float value)

Description

Sets the maximum shields for a unit. Async version of API; may not occur until a simulation frame tick after it's called. Recommended you use the non-async version of this API.

Parameters

unit unit the unit to modify.
float value the new maximum for the unit.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShield(unit, 5)
    DCEI.SetMaxShieldAsync(unit,30)

    DCEI.Wait(0.0625) -- Wait because async

    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShield(unit, 10)
    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

float GetShield(unit unit)

float GetShield(unit unit)

Description

Returns the current shields of a unit.

Parameters

unit unit the unit to check.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShield(unit, 5)
    DCEI.SetMaxShield(unit,30)
    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShield(unit, 10)
    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

void AddShield(unit unit, float value)

void AddShield(unit unit, float value)

Description

Increases the current shields of a unit by a set amount up to its maximum.

Parameters

unit unit the unit to add shields to.
float value amount of shields to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShield(unit, 5)
    DCEI.SetMaxShield(unit,30)
    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShield(unit, 10)
    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

void SetShield(unit unit, float value)

void SetShield(unit unit, float value)

Description

Set the current shields of a unit to a set amount up to its maximum.

Parameters

unit unit the unit to add shields to.
float value the amount of shields to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShield(unit, 5)
    DCEI.SetMaxShield(unit,30)
    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShield(unit, 10)
    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

void AddShieldAsync(unit unit, float value)

void AddShieldAsync(unit unit, float value)

Description

Increases the current shields of a unit by a set amount up to its maximum. Async so may not occur on the same simulation frame as it's called. Recommended you use the non-async version of this API.

Parameters

unit unit the unit to add shields to.
float value amount of shields to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShield(unit, 5)
    DCEI.SetMaxShield(unit,30)
    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShieldAsync(unit, 10)

    DCEI.Wait(0.0625) -- Wait because of async api

    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

void SetShieldValueAsync(unit unit, float amount)

void SetShieldValueAsync(unit unit, float amount)

Description

Set the current shields of a unit to a set amount up to its maximum. Async so may not occur util after the current simulation frame. Recommended you use the non-async API instead.

Parameters

unit unit the unit to add shields to.
float amount amount of shields to add.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetShieldValueAsync(unit, 5)

    DCEI.Wait(0.0625) -- Wait for async API 

    DCEI.SetMaxShield(unit,30)
    local shields = DCEI.GetShield(unit)
    local max_shields = DCEI.GetMaxShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")

    DCEI.AddShield(unit, 10)
    shields = DCEI.GetShield(unit)
    DCEI.LogMessage(unit_type .. " has " .. shields .. "/" .. max_shields .. " shields currently.")
end, 
0.0)

float GetMaxHealth(unit unit)

float GetMaxHealth(unit unit)

Description

Returns the maximum health of a unit.

Parameters

unit unit the unit to check.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealth(unit, 5)
    DCEI.SetMaxHealth(unit,30)
    local hp = DCEI.GetHealth(unit)
    local max_hp = DCEI.GetMaxHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")

    DCEI.AddHealth(unit, 10)
    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")
end, 
0.0)

void SetMaxHealth(unit unit, float value)

void SetMaxHealth(unit unit, float value)

Description

Sets the maximum health for a unit.

Parameters

unit unit the unit to modify.
float value the new maximum for the unit.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealth(unit, 5)
    DCEI.SetMaxHealth(unit,30)
    local hp = DCEI.GetHealth(unit)
    local max_hp = DCEI.GetMaxHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")

    DCEI.AddHealth(unit, 10)
    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")
end, 
0.0)

void SetMaxHealthAsync(unit unit, float value)

void SetMaxHealthAsync(unit unit, float value)

Description

Sets the maximum health for a unit. Async, so may not occur until next simulation frame. Recommended you use the non-async version of this API.

Parameters

unit unit the unit to modify.
float value the new maximum for the unit.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetHealth(unit, 5)
    DCEI.SetMaxHealthAsync(unit,30)

    DCEI.Wait(0.0625) -- Wait for async API

    local hp = DCEI.GetHealth(unit)
    local max_hp = DCEI.GetMaxHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")

    DCEI.AddHealth(unit, 10)
    hp = DCEI.GetHealth(unit)
    DCEI.LogMessage(unit_type .. " has " .. hp .. "/" .. max_hp .. " hp currently.")
end, 
0.0)

float GetMaxMana(unit unit)

float GetMaxMana(unit unit)

Description

Returns the maximum mana of a unit.

Parameters

unit unit the unit to check.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxMana(unit, 20)
    DCEI.SetMana(5)
    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddMana(unit, 10)
    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0.0)

void SetMaxMana(unit unit, float value)

void SetMaxMana(unit unit, float value)

Description

Sets the maximum mana for a unit.

Parameters

unit unit the unit to modify.
float value the new maximum for the unit.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxMana(unit, 20)
    DCEI.SetMana(5)
    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddMana(unit, 10)
    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0.0)

void SetMaxManaAsync(unit unit, float value)

void SetMaxManaAsync(unit unit, float value)

Description

Sets the maximum mana for a unit. Async, so may not occur until next simulation frame. Recommended you use the non-async API.

Parameters

unit unit the unit to modify.
float value the new maximum for the unit.

Example Usage

DCEI.TriggerAddTimerEventElapsed(function()
    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)
    DCEI.Wait(1)

    DCEI.SetMaxManaAsync(unit, 20)

    DCEI.Wait(0.0625) -- Async version of API

    DCEI.SetMana(5)
    local mana = DCEI.GetMana(unit)
    local max_mana = DCEI.GetMaxMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")

    DCEI.AddMana(unit, 10)
    mana = DCEI.GetMana(unit)
    DCEI.LogMessage(unit_type .. " has " .. mana .. "/" .. max_mana .. " mana currently.")
end, 
0.0)

void SetGoldBounty(unit unit, float amount)

void SetGoldBounty(unit unit, float amount)

Description

Sets the SetGoldBounty for a unit.

Parameters

unit unit the unit to set the bounty on.
float amount the amount of gold the unit is worth.

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)

DCEI.SetGoldBounty(unit, 5.0)
local bounty = DCEI.GetUnitBounty(unit)
DCEI.LogMessage(unit_type .. " has a bounty of " .. bounty .. " gold.")

GetUnitBounty

void SetGoldBountyAsync(unit unit, float amount)

void SetGoldBountyAsync(unit unit, float amount)

Description

Sets the SetGoldBounty for a unit. Async so may not occur until the next simulation frame. Recommended you use the non-async version instead.

Parameters

unit unit the unit to set the bounty on.
float amount the amount of gold the unit is worth.

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)

DCEI.SetGoldBountyAsync(unit, 5.0)

DCEI.Wait(0.0625) -- Wait because of async API

local bounty = DCEI.GetUnitBounty(unit)
DCEI.LogMessage(unit_type .. " has a bounty of " .. bounty .. " gold.")

void ApplyWaypoint(unit unit, string waypointName, float waypointDispersal)

void ApplyWaypoint(unit unit, string waypointName, float waypointDispersal)

Description

Make a unit follow a waypoint using a certain dispersal. Wild Sky only.

Parameters

unit unit the unit to apply waypoints to.
string waypointName the name of the waypoint path as defined in the terrain editor.
float waypointDispersal distance offset from the center of the waypoint path the unit should walk.

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, "GoblinWarshipFlyby", 0.5)

void ApplyWaypoint(unit unit, WaypointOptions option)

void ApplyWaypoint(unit unit, WaypointOptions option)

Description

Make a unit follow a waypoint using additional options. Wild Sky only.

Parameters

unit unit the unit to apply waypoints to.
WaypointOptions option waypoint options including waypoint name, dispersal, use natural dispersal flag, and node index.

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

object GetWaypointPaths(bool includeRallyDisabledLanes)

object GetWaypointPaths(bool includeRallyDisabledLanes)

Description

Wild Sky feature. Get all waypoint paths defined in the terrain editor.

Parameters

bool includeRallyDisabledLanes if true, includes waypoint paths with the "rallyDisabled" flag checked.

Example Usage

function HeroMakaWolfSpawner(u)
    -- First we assign the spawner a waypoint
    local paths = DCEI.GetWaypointPaths()

    local path = paths[(1 % #paths) + 1]
    local start = DCEI.GetWaypointPathStartPosition(path)
    -- Second we find the closest tower slot
    local slot = game.GetClosestUnit(DCEI.FindUnits(DCEI.Unit("Tower Slot")), start)
    if slot and slot ~= DCEI.UnitAny then
        -- Third we get a polar offset from the slot toward the start
        local pos = game.PolarOffsetFromUnit2D(slot, 0.5, game.AngleBetweenUnitAndPoint2D(slot, start))
        -- Finally we find the closest point on a road and translate the spawner
        local road = DCEI.FindClosestPointOnRoad(pos.x, pos.y, true)
        DCEI.SetUnitPosition2DAsync(u, road.x, road.y)
    end
end

Float2 GetWaypointPathStartPosition(string name, float dispersal = 0.5)

Float2 GetWaypointPathStartPosition(string name, float dispersal = 0.5)

Description

Wild Sky feature. Get the starting point of a given waypoint path.

Parameters

string name name of the waypoint path to get the starting coordinants for.
float dispersal range of dispersal from the center of the waypoint path.

Example Usage

function HeroMakaWolfSpawner(u)
    -- First we assign the spawner a waypoint
    local paths = DCEI.GetWaypointPaths()

    local path = paths[(1 % #paths) + 1]
    local start = DCEI.GetWaypointPathStartPosition(path)
    -- Second we find the closest tower slot
    local slot = game.GetClosestUnit(DCEI.FindUnits(DCEI.Unit("Tower Slot")), start)
    if slot and slot ~= DCEI.UnitAny then
        -- Third we get a polar offset from the slot toward the start
        local pos = game.PolarOffsetFromUnit2D(slot, 0.5, game.AngleBetweenUnitAndPoint2D(slot, start))
        -- Finally we find the closest point on a road and translate the spawner
        local road = DCEI.FindClosestPointOnRoad(pos.x, pos.y, true)
        DCEI.SetUnitPosition2DAsync(u, road.x, road.y)
    end
end

void FollowUnit(unit unit, unit targetUnit, float offsetX, float offsetY, float distanceMax)

void FollowUnit(unit unit, unit targetUnit, float offsetX, float offsetY, float distanceMax)

Description

Commands a unit to follow another unit.

Parameters

unit unit the unit to command.
unit targetUnit the unit to follow.
float offsetX x offset from the target unit.
float offsetY y offset from the target unit.
float distanceMax if the distance between the units becomes larger than this, the follower unit will move towards the target unit, using the given offsets.

Example Usage

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

DCEI.FollowUnit(unit, target, 1.0, 1.0, 2.0)

DCEI.Move(target, 10, 10)

void FollowUnitWithOffset(unit unit, unit targetUnit, float offset)

void FollowUnitWithOffset(unit unit, unit targetUnit, float offset)

Description

Commands a unit to follow another unit.

Parameters

unit unit the unit to command.
unit targetUnit the unit to follow.
float offset offset distance from the target unit.

Example Usage

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

DCEI.FollowUnit(unit, target, 2.0)

DCEI.Move(target, 10, 10)

void ClearFollowUnit(unit unit)

void ClearFollowUnit(unit unit)

Description

Clears the order for a unit to follow another unit.

Parameters

unit unit the unit to command.

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 target = DCEI.CreateUnit(team_id, player_id, unit_type, x, y)

DCEI.FollowUnit(unit, target, 1.0, 1.0, 2.0)

DCEI.Move(target, 10, 10)

DCEI.TriggerAddTimerEventElapsed(function()
    DCEI.ClearFollowUnit(unit)
end, 2.0, false, true)

void SelectUnit(unit unit)

void SelectUnit(unit unit)

Description

Selects a unit for the player.

Parameters

unit unit the unit to select.

Example Usage

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

DCEI.SelectUnit(unit)

if DCEI.IsUnitSelected then
    DCEI.LogMessage(unit_type .. " is selected.")
end

DCEI.TriggerAddTimerEventElapsed(function()
    DCEI.Deselect(unit)
end, 2.0, false, true)

if DCEI.IsUnitSelected then
    DCEI.LogMessage(unit_type .. " is selected.")
else
    DCEI.LogMessage(unit_type .. " is not selected.")
end

DeselectUnit
IsUnitSelected

void DeselectUnit(unit unit)

void DeselectUnit(unit unit)

Description

Deselects a unit.

Parameters

unit unit the unit to deselect.

Example Usage

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

DCEI.SelectUnit(unit)

if DCEI.IsUnitSelected then
    DCEI.LogMessage(unit_type .. " is selected.")
end

DCEI.TriggerAddTimerEventElapsed(function()
    DCEI.Deselect(unit)
end, 2.0, false, true)

if DCEI.IsUnitSelected then
    DCEI.LogMessage(unit_type .. " is selected.")
else
    DCEI.LogMessage(unit_type .. " is not selected.")
end

unit FindUnit(string name)

unit FindUnit(string name)

Description

Attempts to return an existing unit from its name.

Parameters

string name the name of the unit type to find.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 12, 12
local unit = {}
local i
for i = 1, 5 do
    unit[i] = DCEI.CreateUnit(i, i % 2, unit_type, x+i, y+i)
    DCEI.SetHealth(unit[i], i)
end

local test_subject = DCEI.FindUnit(unit_type)

local hp = DCEI.GetHealth(test_subject)
DCEI.LogMessage(unit_type .. " has " .. hp .. " hp currently.")
DCEI.SetUnitPosition2D(test_subject,14,10)

test_subject = DCEI.FindUnitAtPosition(unit_type, 14,14)
DCEI.LogMessage(DCEI.GetUnitType(test_subject) .. " owned by player " .. DCEI.GetUnitPlayerId(test_subject) .. " is at " .. DCEI.GetUnitPosition2D(test_subject).x .. ", " .. DCEI.GetUnitPosition2D(test_subject).y .. " currently.")

FindUnitsByPlayerId
FindUnitsByTeamId
FindUnits
FindUnitAtPosition

object FindUnitsByPlayerId(int playerId)

object FindUnitsByPlayerId(int playerId)

Description

Returns a list of all units owned by a player.

Parameters

int playerId the player id to search for units by.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 12, 12
local unit = {}
local i
for i = 1, 5 do
    unit[i] = DCEI.CreateUnit(i, i % 2, unit_type, x+i, y+i)
    DCEI.SetHealth(unit[i], i)
end

local group = DCEI.FindUnitsByPlayerId(1)

for _, unit in ipairs(group) do
    DCEI.LogMessage(DCEI.GetUnitType(unit) .. " owned by player " .. DCEI.GetUnitPlayerId(unit) .. " is at " .. DCEI.GetUnitPosition2D(unit).x .. ", " .. DCEI.GetUnitPosition2D(unit).y .. " currently.")
end

FindUnit
FindUnitsByTeamId
FindUnits
FindUnitAtPosition

object FindUnitsByTeamId(int teamId)

object FindUnitsByTeamId(int teamId)

Description

Returns a list of all units that belong to the specified team.

Parameters

int teamId the team id to search for units by.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 12, 12
local unit = {}
local i
for i = 1, 5 do
    unit[i] = DCEI.CreateUnit(i, i % 2, unit_type, x+i, y+i)
    DCEI.SetHealth(unit[i], i)
end

local group = DCEI.FindUnitsByTeamId(1)

for _, unit in ipairs(group) do
    DCEI.LogMessage(DCEI.GetUnitType(unit) .. " owned by player " .. DCEI.GetUnitPlayerId(unit) .. " is at " .. DCEI.GetUnitPosition2D(unit).x .. ", " .. DCEI.GetUnitPosition2D(unit).y .. " currently.")
end

object FindSimpleUnitsByName(string name)

object FindSimpleUnitsByName(string name)

Description

Find all simple units by unit type name. For more info about simple units, see Simple Units Guide.

Parameters

string name the name of the simple unit type to find

Example Usage

local unit_type = "Simple Unit"
local x, y = 12, 12
local unit = {}

for i = 1, 5 do
    unit[i] = DCEI.CreateSimpleUnit(
        -1
        unit_properties.Unit,
        unit_properties.Collider,
        position.x,
        position.y,
        rotation.x,
        rotation.y,
        velocity.x,
        velocity.y
    )
end

local group = DCEI.FindSimpleUnitsByName("Simple Unit")

for _, unit in ipairs(group) do
    DCEI.LogMessage("Unit Found")
end

CreateSimpleUnitAsync
CreateSimpleUnitSync

object FindSimpleUnitsByPlayerId(int playerId)

object FindSimpleUnitsByPlayerId(int playerId)

Description

Find all simple units by owner player ID. For more info about simple units, see Simple Units Guide.

Parameters

int playerId the player ID to fetch table of units for

Example Usage

local unit_type = "Simple Unit"
local x, y = 12, 12
local unit = {}

for i = 1, 5 do
    unit[i] = DCEI.CreateSimpleUnit(
        -1
        unit_properties.Unit,
        unit_properties.Collider,
        position.x,
        position.y,
        rotation.x,
        rotation.y,
        velocity.x,
        velocity.y
    )
end

local group = DCEI.FindSimpleUnitsByPlayerId(-1)

for _, unit in ipairs(group) do
    DCEI.LogMessage("Unit Found")
end

object FindUnits(string name)

object FindUnits(string name)

Description

Returns a list of all units with the specified unit name.

Parameters

string name the name of the unit type to find.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, y = 12, 12
local unit = {}
local i
for i = 1, 5 do
    unit[i] = DCEI.CreateUnit(i, i % 2, unit_type, x+i, y+i)
    DCEI.SetHealth(unit[i], i)
end

local group = DCEI.FindUnits(unit_type)

for _, unit in ipairs(group) do
    DCEI.LogMessage(DCEI.GetUnitType(unit) .. " owned by player " .. DCEI.GetUnitPlayerId(unit) .. " is at " .. DCEI.GetUnitPosition2D(unit).x .. ", " .. DCEI.GetUnitPosition2D(unit).y .. " currently.")
end

FindUnit
FindUnitsByPlayerId
FindUnitsByTeamId
FindUnitAtPosition()

unit FindUnitAtPosition(string name, float x, float z)

unit FindUnitAtPosition(string name, float x, float z)

Description

Returns the unit with the given name closest to the given coordinates.

Parameters

string name the name of the unit type to find.
float x the x-coordinate of the point to search for the unit at.
float z the y-coordinate of the point to search for the unit at.

Example Usage

local unit_type = DCEI.Unit("Standard MeleeUnit")
local x, z = 12, 12
local unit = {}
local i
for i = 1, 5 do
    unit[i] = DCEI.CreateUnit(i, i % 2, unit_type, x + i, y + i)
    DCEI.SetHealth(unit[i], i)
end

local test_subject = DCEI.FindUnit(unit_type)

local hp = DCEI.GetHealth(test_subject)
DCEI.LogMessage(unit_type .. " has " .. hp .. " hp currently.")
DCEI.SetUnitPosition2D(test_subject, 14, 10)

test_subject = DCEI.FindUnitAtPosition(unit_type, 14, 14)
DCEI.LogMessage(DCEI.GetUnitType(test_subject) .. " owned by player " .. DCEI.GetUnitPlayerId(test_subject) .. " is at " .. DCEI.GetUnitPosition2D(test_subject).x .. ", " .. DCEI.GetUnitPosition2D(test_subject).y .. " currently.")

bool IsUnitSelected(unit unit)

bool IsUnitSelected(unit unit)

Description

Returns true if the unit is selected.

Parameters

unit unit the unit to check.

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)

DCEI.SelectUnit(unit)

if DCEI.IsUnitSelected then
    DCEI.LogMessage(unit_type .. " is selected.")
end

DCEI.TriggerAddTimerEventElapsed(function()
    DCEI.Deselect(unit)
end, 2.0, false, true)

if DCEI.IsUnitSelected then
    DCEI.LogMessage(unit_type .. " is selected.")
else
    DCEI.LogMessage(unit_type .. " is not selected.")
end

Trigger API Reference\DCEI Functions\Unit

string DefaultHero()

Description

Example Usage

object ExtraHeros()

Description

Example Usage

unit CreateUnitFilter(UnitFilter filter)

Description

Parameters

Example Usage

unit CreateUnit(int teamId, int playerId, string unitType, float x, float z, float dx = 0, float dz = 1)

Description

Parameters

Example Usage

Related

float GetPlayerStats(int playerId, string statsName)

Description

Parameters

Example Usage

void ResetPlayerStats()

Description

Example Usage

void SetUnitMass(unit unit, float massValue)

Description

Parameters

Example Usage

Related

void SetUnitSimpleTag(unit unit, SimpleTagOptions options)

Description

Parameters

Example Usage

void SetSimpleHealthData(unit unit, SimpleHealthOptions options)

Description

Parameters

Example Usage

Related

void SetSimpleUnitMoveTargetUnit(unit unit, unit targetUnit)

Description

Parameters

Example Usage

Related

void SetSimpleUnitMoveTargetWorldPosition2D(unit unit, float x, float y)

Description

Parameters

Example Usage

Related

void SetSimpleUnitMoveTargetDirection(unit unit, float dx, float dy)

Description

Parameters

Example Usage

Related

void SetSimpleUnitTeamId(unit unit, int teamId)

Description

Parameters

Example Usage

Related

void RegisterSimpleAnimationSequence(int id, SimpleAnimationSequence sequence)

Description

Parameters

Example Usage

void ApplyTransformAnimationToSimpleUnit(unit unit, SimpleUnitTransformAnimationOptions options)

Description

Parameters

Example Usage

Related

void ApplyTintColorAnimationToSimpleUnit(unit unit, SimpleUnitTintColorAnimationOptions options)

Description

Parameters

Example Usage

Related

void ClearTintColorAnimationToSimpleUnit(unit unit)

Description

Parameters

Example Usage

void AddKillTimerToSimpleUnit(unit unit, float seconds)

Description

Parameters

Example Usage

Related