---

Trigger API Reference\DCEI Events\Unit

TriggerHandle TriggerAddUnitSelectedEvent(unit unit, TypedCallback trigger)

TriggerHandle TriggerAddUnitSelectedEvent(unit unit, TypedCallback trigger)

Description

This event is triggered when a unit is selected.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback trigger the callback function that is run when the event is triggered.

Example Usage

local function OnUnitSelected()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    DCEI.LogMessage(unit_name .. " has been selected.")
end

DCEI.TriggerAddUnitSelectedEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitSelected)

Related

• UnitAny
• TriggeringUnit
  

TriggerHandle TriggerAddUnitDeselectedEvent(unit unit, TypedCallback trigger)

TriggerHandle TriggerAddUnitDeselectedEvent(unit unit, TypedCallback trigger)

Description

This event is triggered when a unit is deselected.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback trigger the callback function that is run when the event is triggered.

Example Usage

local function OnUnitDeselected()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)
    DCEI.LogMessage(unit_name .. " has been deselected.")
end

DCEI.TriggerAddUnitDeselectedEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitDeselected)

Related

• UnitAny
• TriggeringUnit
  

TriggerHandle TriggerAddUnitDamageEvent(unit unit, TypedCallback<float, unit> trigger, CriticalFilter filter = default)

TriggerHandle TriggerAddUnitDamageEvent(unit unit, TypedCallback<float, unit> trigger, CriticalFilter filter = default)

Description

This event is triggered when a unit is damaged. Inputs the damage done to the unit into the trigger as the first parameter, and passes the target unit to the second parameter.

Note: DCEI.Wait is explicitly disabled in callbacks for TriggerAddUnitDamageEvent, TriggerAddUnitCriticalDamageEvent, TriggerAddUnitHealEvent as these triggers may each fire multiple times per second and DCEI.Wait is relatively costly. To circumvent this, you should wrap trigger into a DCEI.TriggerAddTimerEventElapsed (or Core.Timer).

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<float, unit> trigger the callback function that is run when the event is triggered.
• CriticalFilter filter whether this event is triggered on all damage event, or just critical ones, or just non-critical ones.

Callback Parameters

• Single amount
• Unit target_unit

Example Usage

local function OnUnitDamaged(damage, target_unit)
    local context = DCEI.TriggeringEffectContext
    local effect = DCEI.TriggeringEffectName
    local caster_name = DCEI.GetUnitType(context.caster)
    local source_name = DCEI.GetUnitType(context.source)
    local target_name = DCEI.GetUnitType(context.target)
    -- Alternatively;
    -- local target_name = DCEI.GetUnitType(target_unit)
    DCEI.LogMessage(target_name .. " was damaged for " .. damage .. " by " .. caster_name .. " via " .. source_name .. " through the use of " .. effect .. ".")
end

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

Related

• UnitAny
• TriggeringUnit
• TriggeringEffectContext
• TriggeringEffectId
• TriggeringEffectName
  

TriggerHandle TriggerAddUnitCriticalDamageEvent(unit unit, TypedCallback<float, unit> trigger)

TriggerHandle TriggerAddUnitCriticalDamageEvent(unit unit, TypedCallback<float, unit> trigger)

Description

This event is triggered when a unit is damaged by a critical hit from a weapon. Inputs the damage done to the unit into the trigger as the first parameter, and passes the target unit to the second parameter.

Note: DCEI.Wait is explicitly disabled in callbacks for TriggerAddUnitDamageEvent, TriggerAddUnitCriticalDamageEvent, TriggerAddUnitHealEvent as these triggers may each fire multiple times per second and DCEI.Wait is relatively costly. To circumvent this, you should wrap trigger into a DCEI.TriggerAddTimerEventElapsed (or Core.Timer).

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<float, unit> trigger the callback function that is run when the event is triggered.

Callback Parameters

• Single amount
• Unit target_unit

Example Usage

local function OnUnitCriticalDamaged(damage, target_unit)
    local context = DCEI.TriggeringEffectContext
    local effect = DCEI.TriggeringEffectName
    local caster_name = DCEI.GetUnitType(context.caster)
    local source_name = DCEI.GetUnitType(context.source)
    local target_name = DCEI.GetUnitType(context.target)
    -- Alternatively;
    -- local target_name = DCEI.GetUnitType(target_unit)
    DCEI.LogMessage(target_name .. " was damaged for " .. damage .. " by " .. caster_name .. " via " .. source_name .. " through the use of " .. effect .. ".")
end

DCEI.TriggerAddUnitCriticalDamageEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitCriticalDamaged)

Related

• UnitAny
• TriggeringUnit
• TriggeringEffectContext
• TriggeringEffectId
• TriggeringEffectName
  

TriggerHandle TriggerAddUnitHealEvent(unit unit, TypedCallback<float, unit> trigger)

TriggerHandle TriggerAddUnitHealEvent(unit unit, TypedCallback<float, unit> trigger)

Description

This event is triggered when a unit is healed. Inputs the amount healed by the unit into the trigger as the first parameter, and passes the target unit to the second parameter.

Note: DCEI.Wait is explicitly disabled in callbacks for TriggerAddUnitDamageEvent, TriggerAddUnitCriticalDamageEvent, TriggerAddUnitHealEvent as these triggers may each fire multiple times per second and DCEI.Wait is relatively costly. To circumvent this, you should wrap trigger into a DCEI.TriggerAddTimerEventElapsed (or Core.Timer).

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<float, unit> trigger the callback function that is run when the event is triggered.

Callback Parameters

• Single amount
• Unit target_unit

Example Usage

local function OnUnitHealed(amount, target_unit)
    local context = DCEI.TriggeringEffectContext
    local effect = DCEI.TriggeringEffectName
    local caster_name = DCEI.GetUnitType(context.caster)
    local source_name = DCEI.GetUnitType(context.source)
    local target_name = DCEI.GetUnitType(context.target)
    -- Alternatively;
    -- local target_name = DCEI.GetUnitType(target_unit)
    DCEI.LogMessage(target_name .. " was healed for " .. amount .. " by " .. caster_name .. " via " .. source_name .. " through the use of " .. effect .. ".")
end

DCEI.TriggerAddUnitHealEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitHealed)

Related

• UnitAny
• TriggeringUnit
  

TriggerHandle TriggerAddUnitSpawnEvent(unit unit, TypedCallback trigger, bool simple = False)

TriggerHandle TriggerAddUnitSpawnEvent(unit unit, TypedCallback trigger, bool simple = False)

Description

This event is triggered when a unit is spawned.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback trigger the callback function that is run when the event is triggered.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not utilize DCEI.Wait() at all.

Example Usage

local function OnUnitSpawned()
    local unit = DCEI.TriggeringUnit
    local name = DCEI.GetUnitType(unit)
    DCEI.LogMessage(name .. " was spawned.")
end

DCEI.TriggerAddUnitSpawnEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitSpawned)

Related

• UnitAny
• TriggeringUnit
  

TriggerHandle TriggerAddUnitDiedEvent(unit unit, TypedCallback<unit> trigger, bool simple = False)

TriggerHandle TriggerAddUnitDiedEvent(unit unit, TypedCallback<unit> trigger, bool simple = False)

Description

This event is triggered when a unit dies.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<unit> trigger the callback function that is run when the event is triggered. This function can also pass the killing unit as a parameter to the callback function.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not utilize DCEI.Wait() at all.

Callback Parameters

• Unit killing_unit

Example Usage

local function OnUnitDeath(killing_unit)
    local unit = DCEI.TriggeringUnit
    local name = DCEI.GetUnitType(unit)
    local killing_unit_name = DCEI.GetUnitType(killing_unit)
    DCEI.LogMessage(killing_unit_name .. " has killed " .. name)
end

DCEI.TriggerAddUnitDiedEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitDeath)

Related

• UnitAny
• TriggeringUnit
• TriggerAddUnitRemovedEvent
  

TriggerHandle TriggerAddUnitMoveCommandEvent(unit unit, TypedCallback<Float2> trigger)

TriggerHandle TriggerAddUnitMoveCommandEvent(unit unit, TypedCallback<Float2> trigger)

Description

This event is triggered when a unit starts moving. Inputs the destination into the first parameter of the trigger as a float2 value.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback<Float2> trigger the callback function that is run when the event is triggered.

Callback Parameters

• Float2 target_position

Example Usage

local 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.TriggerAddUnitMoveCommandEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitMoveCommand)

Related

• UnitAny
• TriggeringUnit
• GetUnitPosition2D
  

TriggerHandle TriggerAddOnUnitIdleEvent(unit unit, TypedCallback trigger)

TriggerHandle TriggerAddOnUnitIdleEvent(unit unit, TypedCallback trigger)

Description

This event is triggered when a unit goes into the idle state (no commands queued).

Parameters

• unit unit the unit that triggers this event.
• TypedCallback trigger the callback function that is run when the event is triggered.

Example Usage

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

local function OnUnitIdle()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)

    DCEI.LogMessage(unit_name .. " has become idle.")
end

DCEI.TriggerAddOnUnitIdleEvent(test_subject, OnUnitIdle)

Related

• UnitAny
• TriggeringUnit
  

TriggerHandle TriggerAddUnitRemovedEvent(unit unit, TypedCallback trigger, bool simple = False)

TriggerHandle TriggerAddUnitRemovedEvent(unit unit, TypedCallback trigger, bool simple = False)

Description

This event is triggered when a unit is removed.

Parameters

• unit unit the unit that triggers this event.
• TypedCallback trigger the callback function that is run when the event is triggered.
• bool simple this flag reduces overhead by preventing the usage of DCEI.Wait() within the trigger. You should only set this to true if the trigger does not utilize DCEI.Wait() at all.

Example Usage

local function OnUnitRemoved()
    local unit = DCEI.TriggeringUnit
    local unit_name = DCEI.GetUnitType(unit)

    DCEI.LogMessage(unit_name .. " has been removed.")
end

DCEI.TriggerAddUnitRemovedEvent(DCEI.CreateUnitFilter({name = DCEI.Unit("Test Unit")}), OnUnitRemoved)

Related

• UnitAny
• TriggeringUnit
• TriggerAddUnitDiedEvent