Ability extends Entity

TODO: explain that properties can be get/set from the definition.

Summary

Properties

• cancellable boolean

  Whether the ability can be cancelled or not. […]

• source Read only Entity?

  The Entity that spawned this ability. […]

• owner Entity?

  An optional Entity that "owns" this ability. […]

• stack number

  Convenience attribute that allows for ability stacking. […]

Methods

• complete ()

  Completes the ability. […]

• on_change (attribute: string, callback: ((attribute: string, old: any, data: any) -> ())?, data: any)

  Assigns a callback to be called after an ability attribute changes. […]

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

cancellable

cancellable: boolean

Whether the ability can be cancelled or not.

TODO: explain what cancellation means.

source Read only

source: Entity?

The Entity that spawned this ability. nil if unknown.

owner

owner: Entity?

An optional Entity that "owns" this ability. The ability will be automatically removed when its owner is despawned. Useful for applying abilities in the range of a unit.

Example

Adds an ability "example.lua" on all units in range. The ability will be automatically removed when the unit gets out of range or this unit is despawned.

function on_enter_area(unit: Unit, holder: AbilityHolder, ability: Ability)
    local added_ability = unit.insert_ability("example.lua")
    added_ability.owner = ability
end

function on_exit_area(unit: Unit, holder: AbilityHolder, ability: Ability)
    unit:remove_abilities_from(ability)
end

stack

stack: number

Convenience attribute that allows for ability stacking.

When set to 0, the ability will automatically be removed.

Additionally, any changes to the stack will trigger the [script.on_stack] event.

Can be used for status effect abilities such as Poison or Weak.

Do note that [Ability.on_change] does not track changes to the stack. Use [script.on_stack] instead.

Methods

complete

Ability:complete()

Completes the ability.

TODO: explain what completing an ability means.

on_change

Ability:on_change(attribute: string, callback: ((attribute: string, old: any, data: any) -> ())?, data: any)

Assigns a callback to be called after an ability attribute changes.

The callback will be called with the following arguments:

• attribute: The name of the attribute that changed.
• old: The old value of the attribute.
• data: The additional data passed to data.

You can set the callback to nil to remove it.

Multiple callbacks can't be assigned to the same attribute. Newly added callbacks will replace the previous one.

Caution

Only custom attributes can be listened to for changes. Ability properties changes such as cancellable or owner won't trigger the callback.

Caution

This is a shallow listener. If the attribute is a Table, any changes to its properties will not trigger the callback.

You can use the metatable of the table to implement such listeners.

Parameters

• attribute Required string

  The name of the attribute to listen to changes for.

• callback Optional ((attribute: string, old: any, data: any) -> ())?

  The function to call when attribute changes.

• data Required any

  Additional data to pass to the callback.

Examples

ability:on_change("foo", function(attribute, old)
    print(
        "changed " .. attribute ..
        " from " .. tostring(old) ..
        " to " .. tostring(ability[attribute])
    )
end)

local function damage(attribute, old, data)
    local unit = data :: Unit
    unit:damage(ability[attribute])
end

script.on_insert = function(holder, ability)
    ability:on_change("stack", damage, holder)
end