Unit extends Entity

A Unit is an individual entity that participates in the battle phase. They move and perform abilities automatically.

The player can spawn its own units, usually through Cards. Enemy units are spawned at the start of the battle.

The Unit class provides methods for controlling and interacting with units. An instance of Unit will usually be provided in an ability callback.

Summary

Properties

• position Read only vector

  The current position of the unit. […]

• family Read only Family?

  The Family of the unit. […]

• team Read only Team

  The Team this unit belongs to. […]

• source Read only Entity?

  The Entity that spawned this unit. […]

• corpse_on_die boolean

  Whether the unit should leave a corpse when it dies. […]

Methods

• find_targets_in_range (find_targets: FindTargets) → { Unit }

  Find targets within a given radius of this unit. […]

• add_excluded (excluded: Unit)

  Excludes the excluded unit from this unit's UnitInRange and find_targets_in_range results. […]

• remove_excluded (excluded: Unit)

  Allows the excluded unit to be included in this unit's UnitInRange and find_targets_in_range results again. […]

• get_stat (stat: Stat, ...: Adjective) → number

  Get the current value of a Stat for this unit, after applying any active buffs. […]

• buff (buff: StatBuffDefinition)

  Applies a buff to this unit. […]

• buff_health (buff: HealthBuffDefinition)

  Applies a buff to the health of this unit. […]

• remove_buffs_from (owner: Entity)

  Removes all buffs from this unit that were granted by the given owner. […]

• damage (damage: number, adjectives: Adjective | { Adjective }, source: Entity?, cause: Entity?)

  Damages this unit. […]

• die (source: Entity?, cause: Entity?)

  Instantly kills this unit. […]

• heal (amount: number, source: Entity?, cause: Entity?)

  Heals this unit. […]

• get_ability (ability: string) → Ability?

  Gets a unique ability from this unit by an ability ID. […]

• insert_ability (ability: string, source: Entity?) → Ability

  Adds a unique ability to this unit, by ID. […]

• add_ability (ability: string, source: Entity?) → Ability

  Unconditionally adds an ability to this unit. […]

• get_or_insert_ability (ability: string, source: Entity?) → Ability

  Gets a unique ability from this unit by an ability ID, if present. […]

• stack_ability (ability: string, stack: number, source: Entity?) → Ability

  Convenience method that gets or inserts an ability to this unit, and automatically sets (if newly added) or increments (if already inserted) its [Ability. […]

• remove_abilities_from (owner: Entity)

  Removes all abilities from this unit that were granted by the given owner. […]

• set_steering (...: SteeringBehavior)

Inherited Methods from Entity

• despawn ()

  Despawns this entity. […]

• is_ability () → boolean

  Whether this entity is an Ability. […]

• as_ability () → Ability?

  Typecasts this entity to an Ability, if possible. […]

• to_ability () → Ability

  Forces this entity into an Ability type. […]

• is_unit () → boolean

  Whether this entity is a Unit. […]

• as_unit () → Unit?

  Typecasts this entity to a Unit, if possible. […]

• to_unit () → Unit

  Forces this entity into a Unit type. […]

Properties

position Read only

position: vector

The current position of the unit. The z value will always be 0.

family Read only

family: Family?

The Family of the unit. nil if the unit has no family.

team Read only

team: Team

The Team this unit belongs to.

source Read only

source: Entity?

The Entity that spawned this unit. nil if unknown.

corpse_on_die

corpse_on_die: boolean

Whether the unit should leave a corpse when it dies.

Methods

find_targets_in_range

Unit:find_targets_in_range(find_targets: FindTargets) → { Unit }

Find targets within a given radius of this unit.

TODO: expand on this, add examples, etc.

Parameters

{ radius: number, max: number?, allegiance: Allegiance?, corpse: CorpseFilter?, health: HealthFilter?, priority: TargetPriority?, sticky: boolean? }

A table with the following fields:

• radius Required number

  The radius of the area to search the targets in, in pixels. The area is centered on the unit. Must be positive.

• max Optional number?

  The maximum number of targets to find. Defaults to all. Must be a positive integer.

• allegiance Optional Allegiance?

  The Allegiance of the targets to find. Defaults to opponent.

• corpse Optional CorpseFilter?

  Whether to include corpses in the search. Defaults to no. yes will only include corpses, any will include both corpses and units.

• health Optional HealthFilter?

  Filters the units in the search based on their health. Defaults to any.

• priority Optional TargetPriority?

  The TargetPriority of the targets to find when max is set. Defaults to closest.

• sticky Optional boolean?

  Whether the targets should be sticky (not implemented yet). Defaults to false.

Returns

• { Unit }

  All units found.

add_excluded

Unit:add_excluded(excluded: Unit)

Excludes the excluded unit from this unit's UnitInRange and find_targets_in_range results.

All units are included by default, unless specifically excluded through this method.

Parameters

• excluded Required Unit

  The unit to add to the excluded list.

remove_excluded

Unit:remove_excluded(excluded: Unit)

Allows the excluded unit to be included in this unit's UnitInRange and find_targets_in_range results again.

All units are included by default, but this method allows you to include units again after add_excluded is called.

Parameters

• excluded Required Unit

  The unit to remove from the exclusion list.

get_stat

Unit:get_stat(stat: Stat, ...: Adjective) → number

Get the current value of a Stat for this unit, after applying any active buffs.

Any stat is qualified by at least one Adjective. For instance, a unit's physical attack may be different from its poison attack.

When passing in multiple adjectives, the total value will take into account the base value and buffs for all adjectives.

Parameters

• stat Required Stat

  The stat to get the value of.

• ... Required Adjective

  The adjectives to qualify the stat with. Can be one or more.

Returns

• number

Examples

Getting a unit's attack

Let's say this unit has a base physical attack of 5, but it also has a buff that is increasing its attack by 2. The function would return 7.

unit:get_stat(game.enums.Stat.attack, game.enums.Adjective.physical) -- will return 7

Multiple adjectives

This unit has:

• Physical attack: 3.
• Poison attack: 5.
• Buff that increases physical attack by 2.
• Buff that multiplies poison attack by 3.
• Buff that increases physical poison attacks by 1.

-- will return 5 (3 + 2)
unit:get_stat(game.enums.Stat.attack, game.enums.Adjective.physical)
-- will return 15 (5 * 3)
unit:get_stat(game.enums.Stat.attack, game.enums.Adjective.poison)
-- will return 33 ((3 + 2 + 5 + 1) * 3)
unit:get_stat(game.enums.Stat.attack, game.enums.Adjective.physical, game.enums.Adjective.poison)

buff

Unit:buff(buff: StatBuffDefinition)

Applies a buff to this unit.

A buff affects one Stat and is qualified by one or more Adjectives. See Unit:get_stat for details on how adjectives affect a buff. (TODO add Guide page explaining stats, buffs and adjectives in detail)

Buffs can either be additive or multiplicative, by setting either add or mul. Additive buffs will always be applied first. Multiplicative buffs will multiply the total.

For instance, assuming a base attack of 5:

unit:buff({ add = 2, stat = game.enums.Stat.attack, adjectives = game.enums.Adjective.physical })
unit:buff({ mul = 3, stat = game.enums.Stat.attack, adjectives = game.enums.Adjective.physical })
unit:buff({ add = -1, stat = game.enums.Stat.attack, adjectives = game.enums.Adjective.physical })
unit:buff({ mul = 0.5, stat = game.enums.Stat.attack, adjectives = game.enums.Adjective.physical })

Will result in a total attack of 9: (5 + 2 - 1) * 3 * 0.5.

The total value of a stat after applying all the buffs will be rounded to the nearest integer.

Here's some pseudocode of how the stat formula works:

value = round(base + sum(additive_buffs) * mult(multiplicative_buffs))

Setting an owner for the buff will cause the buff to be removed when the owner dies, if the owner is a Unit. If the owner is an Ability, the buff will be removed either when the ability is removed, or when the unit the ability belongs to dies.

If a duration is set, the buff will automatically be removed after that amount of seconds passes. If both duration and owner are set, the buff will be removed when either condition is met.

Parameters

({ add: number } | { mul: number }) & { stat: Stat, adjectives: Adjective | { Adjective }, owner: Entity?, duration: number? }

A table with the following fields:

• Either:
  • add Required number

    The amount to add to the stat. Must be an integer (can be negative).

  • mul Required number

    The amount to multiply the stat by. Floating number.

• stat Required Stat

  The stat to buff.

• adjectives Required Adjective | { Adjective }

  The adjectives to qualify the buff with.

• owner Optional Entity?

  The unit or ability that owns the buff.

• duration Optional number?

  The duration of the buff, in seconds.

Example

-- Additive buff of 3 to physical + poison attacks, for a duration of 5.5 seconds.
unit:buff({
    add = 3,
    stat = game.enums.Stat.attack,
    adjectives = {game.enums.Adjective.physical, game.enums.Adjective.poison},
    duration = 5.5,
})

-- Multiplicative buff of 1.5 to poison attacks, until the buffer unit dies.
unit:buff({
    mul = 1.5,
    stat = game.enums.Stat.attack,
    adjectives = game.enums.Adjective.poison,
    owner = buffer_unit,
})

buff_health

Unit:buff_health(buff: HealthBuffDefinition)

Applies a buff to the health of this unit.

A health buff will affect both the current and maximum health of the unit.

You can think of a health buff as an additional health bar that will be added to the total health.

Let's say we have a unit with 8/10 HP. If the unit receives a health buff of 2, its HP will be 8/10 + 2/2.

If a unit receives damage, HP from the buff will be reduced first, in order of most recent buffs. Let's say it receives 5 points of damage, its HP will become 5/10 + 0/2.

If the unit were to lose the buff, its HP would remain at 5/10, since the 0/2 extra "bar" would be removed.

Healing is prioritized in the opposite direction: base HP will be healed first, and then buffs in least recent order.

(TODO An image showing multiple buffs, damage and healing would be ideal for the Guide page when releasing the game).

owner and duration work exactly like Unit:buff.

Parameters

{ add: number, owner: Entity?, duration: number? }

A table with the following fields:

• add Required number

  The amount to add to health. Must be a positive integer.

• owner Optional Entity?

  The unit or ability that owns the buff.

• duration Optional number?

  The duration of the buff, in seconds.

Example

-- Permanent bonus of 5 HP
unit:buff_health({ add = 5 })

-- Bonus of 10 HP that expires whenever the buffer unit dies,
-- or after 10 seconds, whichever comes first
unit:buff_health({ add = 10, owner = buffer_unit, duration = 10 })

remove_buffs_from

Unit:remove_buffs_from(owner: Entity)

Removes all buffs from this unit that were granted by the given owner.

Removes both stat buffs and health buffs.

The owner of a buff is whatever was assigned to the owner field when the buff was created. Buffs with no owner assigned will not be affected.

Tip

Useful for implementing custom buff conditions, such as buff areas.

Parameters

• owner Required Entity

Example

-- Buff A
unit:buff({
    add = 20,
    stat = game.enums.Stat.attack,
    adjectives = game.enums.Adjective.physical,
    owner = buffer_unit,
})
-- Buff B
unit:buff_health({ add = 5, owner = buffer_unit })
-- Buff C
unit:buff_health({ add = 10, owner = other_unit })
-- Buff D
unit:buff_health({ add = 3 })

-- Buffs A and B will be removed.
unit:remove_buffs_from(buffer_unit)

damage

Unit:damage(damage: number, adjectives: Adjective | { Adjective }, source: Entity?, cause: Entity?)

Damages this unit.

The adjectives will be considered to apply any bonuses or penalties to the damage dealt, according to the target unit's resistances and vulnerabilities. It will also affect the color of the damage numbers.

Parameters

• damage Required number

  The amount of damage to be done. Positive integer.

• adjectives Required Adjective | { Adjective }

  The adjectives to qualify the damage with. Can be one or a list of many.

• source Optional Entity?

  The entity that is directly dealing the damage (e.g. the projectile or the unit in a melee attack)

• cause Optional Entity?

  The entity that originally triggered the events that led to this damage being dealt. (e.g. the unit that shot the projectile)

Example

-- In a melee attack, set both the source and the cause as the unit attacking
target:deal_damage(10, game.enums.Adjective.physical, unit, unit)

A common pattern to determine the damage to deal is to use the Unit:get_stat method to get the unit's attack stat.

local adjective = game.enums.Adjective.physical
damage = projectile:get_stat(game.enums.Stat.attack, adjective)
-- The projectile is the source, the unit that shot it is the cause
unit:deal_damage(damage, adjective, projectile, projectile.source)

die

Unit:die(source: Entity?, cause: Entity?)

Instantly kills this unit.

Parameters

• source Optional Entity?

  The entity that directly killed this unit (e.g. the projectile or the unit in a melee attack)

• cause Optional Entity?

  The entity that originally triggered the events that led to this unit being killed. (e.g. the unit that shot the projectile)

Example

-- This ability causes the unit to die.
unit:die(ability, ability.source)
-- Kill another unit
other_unit:die(unit, unit)
-- Kill self
unit:die(unit, unit)

heal

Unit:heal(amount: number, source: Entity?, cause: Entity?)

Heals this unit.

Parameters

• amount Required number

  The amount to heal the unit by. Positive integer.

• source Optional Entity?

  The entity that is directly healing (e.g. the projectile that heals or the unit in a spell)

• cause Optional Entity?

  The entity that originally triggered the events that led to this healing. (e.g. the unit that shot the projectile that heals)

get_ability

Unit:get_ability(ability: string) → Ability?

Gets a unique ability from this unit by an ability ID.

The ability ID is the full path of the ability definition, for instance abilities/poison.ability.ron. For abilities inserted directly inside the unit definition, the ID is the path of the script; for instance, abilities/melee_attack.lua.

If there are multiple abilities with the same ID, the first one is returned.

Parameters

• ability Required string

  The ability ID of the ability to get.

Returns

• Ability?

  s The ability, or nil if this unit doesn't have it.

insert_ability

Unit:insert_ability(ability: string, source: Entity?) → Ability

Adds a unique ability to this unit, by ID.

The ability ID is the full path of the ability definition, for instance abilities/poison.ability.ron.

If the ability is already present, an error is thrown.

Parameters

• ability Required string

  The ability ID of the ability to insert.

• source Optional Entity?

  The entity that will be assigned as the source of the ability.

Returns

• Ability

  s The ability that was inserted.

add_ability

Unit:add_ability(ability: string, source: Entity?) → Ability

Unconditionally adds an ability to this unit.

If the ability is already present, a new one will be added as well.

Parameters

• ability Required string

  The full path of the ability definition, for instance abilities/poison.ability.ron.

• source Optional Entity?

  The entity that will be assigned as the source of the ability.

Returns

• Ability

  The ability that was added.

get_or_insert_ability

Unit:get_or_insert_ability(ability: string, source: Entity?) → Ability

Gets a unique ability from this unit by an ability ID, if present.

Otherwise, adds the unique ability to this unit.

See Unit:get_ability and Unit:insert_ability for details.

Parameters

• ability Required string
• source Optional Entity?

  The entity that will be assigned as the source of the ability, if created.

Returns

• Ability

  s The ability that was retrieved or inserted.

stack_ability

Unit:stack_ability(ability: string, stack: number, source: Entity?) → Ability

Convenience method that gets or inserts an ability to this unit, and automatically sets (if newly added) or increments (if already inserted) its Ability.stack property.

The ability ID is the full path of the ability definition, for instance abilities/poison.ability.ron.

As a result of this method, [script.on_stack] will be triggered.

Parameters

• ability Required string

  The ability ID of the ability to insert and increment its stack.

• stack Required number

  The amount to increment or set the ability's stack.

• source Optional Entity?

  The entity that will be assigned as the source of the ability, if newly inserted.

Returns

• Ability

remove_abilities_from

Unit:remove_abilities_from(owner: Entity)

Removes all abilities from this unit that were granted by the given owner.

The owner of aan ability is whatever was assigned to the owner field. Abilities with no owner assigned will not be affected.

Tip

Useful for implementing custom ability conditions, such as AoE abilities.

See Ability.owner for an example.

Parameters

• owner Required Entity

Example

local ability_a = target:insert_ability("a.lua")
ability_a.owner = unit
local ability_b = target:insert_ability("b.lua")

-- Ability A will be removed.
target:remove_abilities_from(unit)

set_steering

Unit:set_steering(...: SteeringBehavior)

Parameters

• ... Required SteeringBehavior