ig.

Ability

new Ability()

Base class for Abilities.
- abilities are great for when your characters need to do special actions such as shooting, interacting, etc Tip: abilities include a visual casting / using system, see ig.Ability#activateCastSettings for examples. IMPORTANT: always use abilities by calling the ig.Ability#activate method, and if the ability ig.Ability#requiresTarget make sure it ig.Ability#canFindTarget or you supply one via ig.Ability#setEntityTarget or ig.Ability#setEntityTargetFirst!

Author:
  • Collin Hover - collinhover.com
Source:
Example 
// using abilities is easy
// each character already has an abilities list
// which is a special hierarchy object
// that has built in methods to facilitate ability use
character.abilities = new ig.Hierarchy();
// but this abilities list is empty
// so create a new melee ability
// and don't forget to pass the entity
// so the ability has a reference to its user
character.melee = new ig.AbilityMelee( character );
// then, optionally, add the ability
// to the character's ability list
character.abilities.addDescendant( character.melee );
// now when our character needs to get violent
// and really punch something
character.melee.activate();
// the melee ability is a SPAMMABLE type
// so we can also find all SPAMMABLE abilities
// in the character's abilities list
var spammables = character.abilities.getDescendantsByType(ig.Ability.TYPE.SPAMMABLE);
// and activate each spammable ability
// which in this case is only the melee ability
for (var i = 0, il = spammables.length; i < il; i++) {
     spammables[ i ].activate();
}
// some abilities, such as melee
// will automatically find the closest target in range
// when activated, based on the canFindTarget property
character.melee.canFindTarget = true;
character.melee.activate();
// but what if we need to activate the ability
// on a specific entity?
character.melee.setEntityTarget( mySpecificTarget );
character.melee.activate();
// or, how about using the player's tap or click target
// get all input points that have tapped
var inputPoints = ig.input.getInputPoints([ 'tapped' ], [ true ]);
// for the example, use only the first
var inputPoint = inputPoints[ 0 ];
if ( inputPoint ) {
     // give the ability a list of targets under the tap
     // and let the ability choose the best
     character.melee.setEntityTargetFirst(inputPoint.targets);
     // now punch again!
     character.melee.activate();
}
// in the case of the player, melee works automatically with tapping
// this is because the melee ability is of the type spammable
// and the player is setup by default to use spammable abilities when a tap occurs
// ( as long as the tap is not on an interactive target )
ig.AbilityMelee = ig.AbilityDamage.extend({
     ...
     initTypes: function () {
         this.parent();
         ig.utils.addType(ig.Ability, this, 'type', "SPAMMABLE");
     }
     ...
});

Members

<static, readonly> FAIL

Failure reasons for when an ability fails.

Properties:
Name Type Description
UNKNOWN String unknown.
COST String user can't pay cost.
TARGET String no target.
DISTANCE String target is too far away.
COOLDOWN String ability on cooldown.
INTERRUPT String casting interrupted.
Source:

<static, readonly> TYPE

Bitwise flags for abilities to designate types, via ig.Ability#type.
- some flags are already defined for convenience
- up to 32 flags can be defined

Properties:
Name Type Description
PASSIVE Bitflag passive type
SPAMMABLE Bitflag spoammable type
TOGGLEABLE Bitflag toggleable type
Source:
See:

activateCastSettings :Object

Activate cast settings.

Default Value:
  • null
Source:
See:

activated :Boolean

Whether ability has been activated.

Default Value:
  • false
Source:

activatePassCastSettings :Object

Activate checks pass cast settings.

Default Value:
  • null
Source:
See:

activateSetupCastSettings :Object

Activate setup cast settings.

Default Value:
  • null
Source:
See:

activateStrict :Boolean

Whether ability should check distance twice during activate process. IMPORTANT: this only applies when casting!

Default Value:
  • true
Source:

activateToggle :Boolean

Whether ability should toggle activate / deactivate instead of just activating.

Default Value:
  • false
Source:

autoStopMoving :Boolean

Whether ability should automatically force the entity to stop moving so it won't interrupt itself immediately.

Default Value:
  • true
Source:

blocking :Boolean

Whether ability blocks other abilities of lower ig.Ability#priority when this ability is activated first via ig.Hierarchy#activate.

Default Value:
  • true
Source:
Example 
// if a character has two abilities
character.abilityA = new ig.Ability( character );
character.abilityB = new ig.Ability( character );
// and these are added to the character's abilities list
character.abilities.addDescendants( [ character.abilityA, character.abilityB ] );
// when abilities are all activated together
character.abilities.activate( target );
// we can set abilities to block
// the execution of all lower priority abilities
// for example, to block B from executing if A is activated successfully
// (assuming A priority is > B priority)
character.abilityA.blocking = true;

canFindTarget :Boolean

Whether can find a target in range when has none while executing.

Default Value:
  • false
Source:

canTargetFixed :Boolean

Whether can target fixed entities (usually UI elements).

Default Value:
  • false
Source:

canTargetOthers :Boolean

Whether can target others.

Default Value:
  • true
Source:

canTargetSelf :Boolean

Whether can target self.

Default Value:
  • true
Source:

<readonly> casting :Boolean

Whether to ability is casting.

Default Value:
  • false
Source:

castTimer :ig.Timer

Timer for casting.
- created on init

Source:

channelled :Boolean

Whether ability is channelled after activated.

Default Value:
  • false
Source:

<readonly> channelling :Boolean

Whether ability is currently channelling.

Default Value:
  • false
Source:

cooldownDelay :Number

Time in seconds ability needs to cooldown between uses.

Default Value:
  • 0
Source:

cooldownTimer :ig.Timer

Timer for cooldown.
- created on init

Source:

costActivate :Number

Energy cost to activate.

Default Value:
  • 0
Source:

costChannel :Number

Energy cost to channel.

Default Value:
  • 0
Source:

deactivateCastSettings :Object

Deactivate cast settings.

Default Value:
  • null
Source:
See:

deactivateSetupCastSettings :Object

Deactivate setup cast settings.

Default Value:
  • null
Source:
See:

enabled :Boolean

Whether ability is able to activate.

Default Value:
  • true
Source:

entity :ig.EntityExtended

Entity that is using this ability.

Default Value:
  • null
Source:

entityOptions :ig.EntityExtended

Entity that provides options / settings for ability use.

Default Value:
  • null
Source:

entityTarget :ig.EntityExtended

Entity that is the target of this ability

Default Value:
  • null
Source:

faceTarget :Boolean

Whether to face target.

Default Value:
  • true
Source:

failCastSettings :Object

Fail cast settings.

Default Value:
  • null
Source:
See:

failReason :String

Reason for ability failure.

Source:

groupTargetable :Number

Flag for groups of entities that can be targeted. Tip: a target must match ALL groups in this flag!

Default Value:
  • 0
Source:
See:
Example 
// target any group except for own group
ability.groupTargetable = 0;
// target enemy
ig.utils.addType( ig.EntityExtended, ability, 'typeTargetable', 'ENEMY', 'GROUP' );
// target enemy zombies
ig.utils.addType( ig.EntityExtended, ability, 'typeTargetable', 'ENEMY ZOMBIES', 'GROUP' );

id :String

Unique instance id.

Source:

movable :Boolean

Whether ability can be used while moving.

Default Value:
  • false
Source:

name :String

Unique instance name.
- usually names are used to map instances for faster searching.

Source:

needsDeactivate :Boolean

Whether ability needs deactivate.

Default Value:
  • false
Source:

onActivated :ig.Signal

Signal dispatched when ability activates.
- created on init.

Source:

once :Boolean

Whether ability should activate once and stay activated.

Default Value:
  • false
Source:

onDeactivated :ig.Signal

Signal dispatched when ability deactivates.
- created on init.

Source:

onFailed :ig.Signal

Signal dispatched when ability fails a check.
- created on init.

Source:

paused :Boolean

Whether ability is paused.

Default Value:
  • false
Source:

priority :Number

Priority of ability where higher is activated sooner when using ig.Hierarchy#activate.

Default Value:
  • 0
Source:
Example 
// if a character has two abilities
character.abilityA = new ig.Ability( character );
character.abilityB = new ig.Ability( character );
// and these are added to the character's abilities list
character.abilities.addDescendants( [ character.abilityA, character.abilityB ] );
// when these abilities are all activated together
character.abilities.activate( target );
// there is no guaranteed order of execution
// though in this case it would likely be A then B
// to change this order (or to guarantee order) use priorities
// for example, to guarantee execution order of B then A
character.abilityA.priority = 1;
character.abilityB.priority = 0;
// this only applies when these abilities are all activated together
character.abilities.activate( target );

rangeX :Number

Horizontal distance for finding targets from ability user, or to determine if ability user is close enough to target.

Default Value:
  • 0
Source:
Example 
// does not find targets and treats all targets as if within range
ability.rangeX = 0;

rangeY :Number

Vertical distance for finding targets from ability user, or to determine if ability user is close enough to target.

Default Value:
  • 0
Source:
Example 
// does not find targets and treats all targets as if within range
ability.rangeY = 0;

rank :Number

Upgrade rank.

Default Value:
  • 0
Source:

regenBlocking :Boolean

Whether blocks user from regenerating while channelling.

Default Value:
  • true
Source:

requiresTarget :Boolean

Whether needs target to activate.

Default Value:
  • false
Source:

retainTarget :Boolean

Whether to retain target after execution.

Default Value:
  • false
Source:

type :Number

Flag for type of ability.

Default Value:
  • 0
Source:
See:
  • ig.utils#addType

typeTargetable :Number

Flag for types of entities that can be targeted. Tip: a target must match ALL types in this flag!

Default Value:
  • 0
Source:
See:
Example 
// target any type
ability.typeTargetable = 0;
// target characters
ig.utils.addType( ig.EntityExtended, ability, 'typeTargetable', 'CHARACTER' );
// target characters that are zombies
ig.utils.addType( ig.EntityExtended, ability, 'typeTargetable', 'CHARACTER ZOMBIE' );

upgrades :Array

Upgrades to apply, where each index corresponds to a rank.

Source:

Methods

activate()

Activates ability and starts activation process. Can also toggle between activate and deactivate using ig.Ability#activateToggle property. Tip: for best results, your custom ability should do all of its activate magic by overriding the ig.Ability#activateComplete method!

Source:

activateComplete()

Completes activate. Step 4 of activate process. Tip: for best results, your custom ability should do all of its activate magic by overriding the ig.Ability#activateComplete method! IMPORTANT: If overriding, always call this.parent() at the end of overriding method as target is dropped at the end of this method.

Source:

activatePass()

Called when activate checks passed. Step 3 of activate process. Tip: for best results, your custom ability should do all of its activate magic by overriding the ig.Ability#activateComplete method!

Source:

activatePlain()

Activate without any parameters, used when setting entity to activate passive abilities.

Source:

activateSetup()

Sets up ability to activate. Step 1 of activate process. Tip: for best results, your custom ability should do all of its activate magic by overriding the ig.Ability#activateComplete method!

Source:

activateTry()

Tries to activate by doing checks. Step 2 of activate process. Tip: for best results, your custom ability should do all of its activate magic by overriding the ig.Ability#activateComplete method!

Source:

addUpgrades(upgrades)

Adds upgrades to the upgrades list, where each upgrade is mapped by index to a rank.

Parameters:
Name Type Description
upgrades Object | function | Array object with properties to merge into this, a function to call upon upgrade, or an array of the previous.
Source:

assert(checkResult, failReason) → {Boolean}

Evaluates a check result and triggers fail if a check is false.

Parameters:
Name Type Description
checkResult * result of a check evaluated as truthy or falsy.
failReason String reason assert may fail.
Source:
Returns:
{ Boolean } Whether a check is true.

blockRegen(entity)

Blocks energy regeneration in entity.

Parameters:
Name Type Description
entity ig.EntityExtended block regeneration in this entity.
Source:

canPayCost() → {Boolean}

Source:
Returns:
{ Boolean } Whether entity can pay energy cost.

cast(settings, internalCallback, internalArgs)

Casts using delay and/or animation and then does callback. IMPORTANT: casting only works when ability is also updated.

Parameters:
Name Type Argument Description
settings Object settings for casting.
internalCallback function <optional>
 internal callback.
internalArgs Array <optional>
 internal arguments.
Source:
Example 
// cast settings is a plain object
castSettings = {};
// casts based on 1 second delay
castSettings.delay = 1;
// add an animation to casting
// which will loop until delay complete
// if no delay is provided
// cast will only last as long as animation
castSettings.animName = 'casting';
// if the game is in top down mode
// the anim name may be changed
// based on the casting entity facing
// i.e. "shoot" becomes "shootX" when facing x
// i.e. "shoot" becomes "shootY" when facing y and can flip y
// i.e. "shoot" becomes "shootUp" when facing up and CANNOT flip y
// i.e. "shoot" becomes "shootDown" when facing down and CANNOT flip y
// this behavior can be overriden by making the anim omni directional
castSettings.animOmniDirectional = true;
// casting is by default interrupted by any movement
// but this can be changed in 2 ways
// either set the ability to movable
ability.movable = true;
// or set the particular cast to movable
castSettings.movable = true;
// sometimes we want to cast
// but we don't want the cast to block the ability activation process
// i.e. this cast should be asynchronous
castSettings.async = true;
// when casting is complete, we can call a function
castSettings.callback = function () { ... };
// in a context
castSettings.context = someObject;
// and pass a settings object to that callback
castSettings.settings = {...};
// while casting, we can also add a list of effects
castSettings.effects = [
     // where each effect is spawned by a plain object
     {
         // that consists of an entity class to spawn as the effect
         // which will be automatically killed when casting is ended
         // (usually effects should be particles, so they are garaunteed to die)
         entityClass: ig.EntityClass
         // a settings object that will be merged into the spawned entity effect
         settings: {...},
         // effect can ignore the duration of the cast
         // and live beyond the casting time
         ignoreDuration: true,
         // effect can be automatically faded
         // i.e. it will fade slowly from 1 to 0 over its life
         fade: true,
         // effects will default to follow the ability user
         // if follow settings are included
        // and these settings map to ig.EntityExtended's moveTo settings
         followSettings: {...},
         // and effects can also follow the ability target
         followTarget: true
     }
     // and we can create as many effects as needed (but don't be a jerk and overload)
     ...
];

castComplete()

Completes casting.

Source:

castEffects(settings)

Shows all effects for effects settings.

Parameters:
Name Type Description
settings Object effects settings (i.e. castSettings.effects).
Source:

castEnd()

Ends casting.

Source:

castStart(settings, internalCallback, internalArgs)

Starts casting.

Parameters:
Name Type Argument Description
settings Object settings object.
internalCallback function <optional>
 internal callback.
internalArgs Array <optional>
 internal arguments.
Source:

castUpdate()

Updates casting.

Source:

changegrade(rank)

Shifts current upgrade rank up or down based on current vs passed.

Parameters:
Name Type Description
rank Number rank to upgrade to.
Source:

channel()

Channels ability. Step 2 of channel process.

Source:

channelStop()

Stops channelling ability.

Source:

channelTry(args)

Trys to channel ability by doing checks. Step 1 of channel process.

Parameters:
Name Type Argument Description
args Array <optional>
 arguments to use in channel process.
Source:

cleanup()

Cleans up ability by immediately and silently deactivating.

Source:

cleanupPlain()

Cleanup without parameters.

Source:

clone(c) → {ig.Ability}

Clones this ability object. IMPORTANT: any class that extends ig.Ability must define ig.Ability#clone and call parent last.

Parameters:
Name Type Argument Description
c ig.Ability <optional>
 ability object to clone into.
Source:
Returns:
{ ig.Ability } copy of this.

closeEnough() → {Boolean}

Source:
Returns:
{ Boolean } if entity is close enough to entityTarget

cooledDown() → {Boolean}

Gets whether ability is finished cooling down.

Source:
Returns:
{ Boolean } whether cooled down.

deactivate()

Deactivates ability and stops channelling. Tip: for best results, your custom ability should do all of its deactivate magic by overriding the ig.Ability#deactivateComplete method!

Source:

deactivateComplete()

Finishes deactivate. Step 2 of deactivate process. Tip: for best results, your custom ability should do all of its deactivate magic by overriding the ig.Ability#deactivateComplete method! IMPORTANT: If overriding, always call this.parent() at the end of overriding method as target is dropped at the end of this method.

Source:

deactivateSetup()

Sets up ability to deactivate. Step 1 of deactivate process. Tip: for best results, your custom ability should do all of its deactivate magic by overriding the ig.Ability#deactivateComplete method!

Source:

disable()

Disables ability, disallowing it to ig.Ability#activate and deactivating it if activated.

Source:

downgrade(rank)

Downgrades ability to rank, or, if no rank passed, to previous rank possible. NOTE: Be cautious when using this on abilities that upgrade with a function and not properties.

Parameters:
Name Type Argument Default Description
rank Number | Boolean <optional>
 this.rank-1 rank to upgrade to, where boolean true downgrades to min rank.
Source:

dropEntityTarget()

Retains or drops current entityTarget automatically.

Source:

effectEnd(effect)

Ends an effect.

Parameters:
Name Type Description
effect ig.Effect effect.
Source:

effectStart(effect)

Creates an effect.

Parameters:
Name Type Description
effect ig.Effect effect.
Source:

enable()

Enables ability, allowing it to ig.Ability#activate.

Source:

execute()

DEPRECATED: please use ig.Ability#activate instead.

Source:

extractCost()

Makes entity pay energy cost.

Source:

fail(failReason)

Called when ability fails assert.

Parameters:
Name Type Argument Default Description
failReason String <optional>
 unknown reason for failure.
Source:

getActivelyUsing() → {Boolean}

Whether ability is in active use (i.e. activated or cast or channel).

Source:
Returns:
{ Boolean } whether in use.

getInterrupted() → {Boolean}

Whether ability is interrupted (currently only by movement)

Source:
Returns:
{ Boolean } whether interrupted (currently only by movement).

getUsing() → {Boolean}

Whether ability is in use (i.e. cast or channel).

Source:
Returns:
{ Boolean } whether in use.

hasTarget() → {Boolean}

Source:
Returns:
{ Boolean } if this has entityTarget. May also attempt to find target if possible.

hasValidTarget()

Checks if entityTarget is a valid target, as opposed to if is targetable.

Source:

init(entity, settings)

Initializes ability, called upon construction.

Parameters:
Name Type Argument Description
entity ig.EntityExtended entity using ability.
settings Object <optional>
 settings object.
Source:

initProperties()

Initializes ability properties.

Source:

initTypes()

Initializes ability types.

Source:

initUpgrades()

Initializes upgrades.

Source:

isEntityTargetable(entity) → {Boolean}

Parameters:
Name Type Description
entity ig.EntityExtended entity target.
Source:
Returns:
{ Boolean } Whether entity can (or should) be targeted.

isEntityTargetDroppable() → {Boolean}

Source:
Returns:
{ Boolean } Whether current entityTarget can (or should) be dropped.

pause()

Pauses ability.

Source:

setClosestEntityTarget()

Finds and sets closest targetable entity.

Source:

setEnabled(enabled)

Sets enabled state ability.

Parameters:
Name Type Argument Default Description
enabled Boolean <optional>
 true whether enabled.
Source:

setEntity(entity)

Sets the entity that is using this ability.

Parameters:
Name Type Description
entity ig.EntityExtended ability user.
Source:

setEntityOptions(entity)

Sets the entity for passing to bindings as options. Normally the entity that the ability originated with.

Parameters:
Name Type Description
entity ig.EntityExtended options provider.
Source:

setEntityTarget(entity)

Sets the entity for use as a target.

Parameters:
Name Type Description
entity ig.EntityExtended entity target.
Source:

setEntityTargetFirst(entities)

Sets first targetable entity from a list.

Parameters:
Name Type Description
entities Array array of entities to test.
Source:

unblockRegen(entity)

Unblocks energy regeneration in entity.

Parameters:
Name Type Description
entity ig.EntityExtended block regeneration in this entity.
Source:

unpause()

Unpauses ability.

Source:

update()

Updates ability.

Source:

upgrade(rank)

Upgrades ability to rank, or, if no rank passed, to next rank possible.

Parameters:
Name Type Argument Default Description
rank Number | Boolean <optional>
 this.rank+1 rank to upgrade to, where boolean true will upgrade to max rank.
Source: