ig.

Character

new Character()

Base character entity.
- includes handling for actions such as move, jump, climb, and use abilities
- automatically tries to swap animations based on state via ig.Character#updateCurrentAnim
- fixes entity movement on slopes IMPORTANT: this is an abstract entity that should be extended.

Author:
  • Collin Hover - collinhover.com
Source:
Example 
// by default, the abstract character looks for a set of animations
// to use as the current animation based on various properties
// the set is controlled by the "animsExpected" property
character.animsExpected = [ "idle", "move", "stairs", "climb", "jump", "fall" ];
// this behavior can be skipped using the "animAutomatic" property
character.animAutomatic = false;
// the actual animation switching is done in the updateCurrentAnim method
// for example, when the character is moving
// the animation is automatically set to move
if ( character.moving )
     character.currentAnim = character.anims[ character.getDirectionalAnimName( "move" ) ];
// note here the directional animation name
// animations in Impact++ are directional and based on flip and facing
// so if an entity can flip X and Y
// you should have animations for both X and Y
// i.e. "moveX" and "moveY"
// if an entity cannot flip X and Y
// you should have animations for Up, Down, Left, and Right
// i.e. "moveUp", "moveDown", "moveLeft", "moveRight"
if ( character.jumping )
     character.currentAnim = character.anims[ character.getDirectionalAnimName( "jump" ) ];
if ( character.falling )
     character.currentAnim = character.anims[ character.getDirectionalAnimName( "fall" ) ];
if ( character.climbing )
     character.currentAnim = character.anims[ character.getDirectionalAnimName( "climb" ) ];
if ( character.climbing && character.withinStairs )
     character.currentAnim = character.anims[ character.getDirectionalAnimName( "stairs" ) ];
// and if all else fails, characters will default to idle
character.currentAnim = character.anims[ character.getDirectionalAnimName( "idle" ) ];

Members

abilities :ig.Hierarchy

Abilities collection that character starts with.
- created on init

Source:

abilitiesOriginal :ig.Hierarchy

Reference to abilities collection that character starts with, ig.Character#abilities.
- references on init

Source:

animAutomatic :Boolean

Whether character is allowed to set own ig.EntityExtended#currentAnim automatically based on current state.

Source:
See:

animsExpected :Array

List of names of animations this entity is expected to have. IMPORTANT: when any animation in this list is not present, it will be filled by a placeholder animation!

Source:

canClimb :Boolean

Whether character is able to climb.

Source:

canJump :Boolean

Whether character is able to jump.

Source:

canPathfind :Boolean

Whether character is able to pathfind.

Source:
See:

<readonly> climbing :Boolean

Whether character is climbing.

Default Value:
  • false
Source:

climbingControl :Number

Amount of acceleration control while climbing.

Source:
See:
Example 
// no control of direction while climbing
character.climbingControl = 0;
// full control of direction while climbing
character.climbingControl = 1;

damageDelay :Number

Time in seconds between taking damage.
- automatically makes character invulnerable for delay length after taking damage

Default Value:
  • 0
Source:

damageSettings :Object

Settings for particle explosion when damaged.
- settings exactly map to those of an ig.EntityExplosion

Default Value:
  • white particles
Source:

damageTimer :ig.Timer

Timer for damage delay.
- created on init

Default Value:
  • null
Source:

deathSettings :Object

Settings for particle explosion when killed.
- settings exactly map to those of an ig.EntityExplosion

Default Value:
  • white particles
Source:

energy :Number

Energy statistic, by default used in abilities.

Source:
See:

energyMax :Number

Maximum energy statistic.

Source:
See:

explodingDamage :Boolean

Whether characters should have a particle explosion when damaged
- explosions are created through an ig.EntityExplosion

Source:
See:

explodingDeath :Boolean

Characters should have a particle explosion when killed.
- explosions are created through an ig.EntityExplosion

Source:
See:

<readonly> falling :Boolean

Whether character has not been grounded for a duration above ig.Character.ungroundedForAndFallingThreshold.

Default Value:
  • false
Source:

frictionGrounded :Vector2

Friction while on ground.

Source:
See:

frictionUngrounded :Vector2

Friction while in air.

Source:
See:

health

Source:

healthMax

Source:

<readonly> jumpAscend :Boolean

Whether character is in initial, ascending portion of jump.

Default Value:
  • false
Source:

jumpControl :Number

Amount of acceleration control while in air.

Source:
See:
Example 
// no control of direction while in air
character.jumpControl = 0;
// full control of direction while in air
character.jumpControl = 1;

jumpForce :Number

Speed modifier to apply on each jump step.

Source:
See:
Example 
// jump is slow and not very high
character.jumpForce = 1;
// jump is faster and higher
character.jumpForce = 10;

<readonly> jumping :Boolean

Whether character is jumping.
- to check if character is not on ground, use ig.Character#grounded.

Default Value:
  • false
Source:

jumpSteps :Number

Number of update steps to apply jump force.

Source:
See:
Example 
// jump is short
character.jumpSteps = 1;
// jump is long
character.jumpSteps = 10;

maxVelClimbing :Vector2

Max velocity while climbing.

Source:
See:

maxVelGrounded :Vector2

Max velocity while on ground.

Source:
See:

maxVelUngrounded :Vector2

Max velocity while in air.

Source:
See:

mimicLevel :Number

How high of a mimic power is needed to mimic this character's abilities.

Default Value:
  • 0
Source:
See:

<readonly> moveToUnsafe :Boolean

Whether character tried to move but stopped because movement was unsafe. Tip: this is only set while pathfinding!

Default Value:
  • false
Source:

<readonly> movingFrom :Boolean

Whether character is moving from another entity.

Default Value:
  • false
Source:

needsNewPath :Boolean

Whether character needs new path for pathfinding.

Default Value:
  • false
Source:

offset :Vector2|Object

Character base offset.

Source:
See:

path :Array

Path for pathfinding.

Source:
See:

pathfindingDelay :Number

Delay in seconds between pathfinding.

Source:
See:

pathfindingSimpleDelay :Number

Delay in seconds between pathfinding when following a path.

Source:
See:

pathfindingUpdateDelay :Number

Delay in seconds between pathfinding when following a path.

Source:
See:

pathingTimer :ig.Timer

Pathing update timer.
- created on first pathfind

Source:

performance

Character performance should be movable.
- set to dynamic to take advantage of run, jump, and climb

Default Value:
  • movable
Source:

regen :Boolean

Whether character regenerates stats.

Default Value:
  • false
Source:

regenAsPctEnergy :Boolean

Whether to treat energy regen as a percentage of max.

Default Value:
  • false
Source:

regenAsPctHealth :Boolean

Whether to treat health regen as a percentage of max.

Default Value:
  • false
Source:

regenDelay :Number

Time in seconds between regeneration ticks.

Default Value:
  • 0
Source:

regenEnergy :Boolean

Whether character can regenerate the energy statistic.
- use to block regeneration dynamically

Default Value:
  • true
Source:

regenHealth :Boolean

Whether character can regenerate the health statistic.
- use to block regeneration dynamically

Default Value:
  • true
Source:

regenRateEnergy :Number

Amount of energy to regenerate per tick.

Source:
See:

regenRateHealth :Number

Amount of health to regenerate per tick.

Source:
See:

regenTimer :ig.Timer

Timer for regeneration ticks.
- created on init

Default Value:
  • null
Source:

size :Vector2|Object

Character base size should be effective size accounting for offset.

Source:
See:
  • ig.CONFIG.CHARACTER.SIZE_EFFECTIVE_X
  • ig.CONFIG.CHARACTER.SIZE_EFFECTIVE_Y

slopeSticking

Source:
See:
  • ig.CONFIG.CHARACTER.SLOPE_STICKING

speed :Vector2

Movement speed to be applied to acceleration.

Source:
See:

<readonly> stuck :Boolean

Whether character thinks it may be stuck while following a path.

Default Value:
  • false
Source:

stuckDelay :Number

Delay in seconds, after first becoming stuck, when character will throw path away.

Source:
See:

stuckTimer :ig.Timer

Stuck delay timer.
- created on first pathfind

Source:

targetable

Default Value:
  • true
Source:

temporaryInvulnerabilityAlpha :Number

Temporary invulnerability pulse alpha.

Default Value:
  • 0.5
Source:

temporaryInvulnerabilityPulses :Number

Number of times to pulse alpha while temporarily invulnerable.

Default Value:
  • 2
Source:

<readonly> ungroundedFor :Number

Duration since character was grounded.

Default Value:
  • 0
Source:

ungroundedForAndFallingThreshold :Number

Duration after character leaves ground to start playing fall animation.

Source:
See:

ungroundedForThreshold :Number

Duration after character leaves ground during which they can still jump.
- this is intended to help players with slower reaction time
- this does not allow another jump while jumping

Source:
See:

<readonly> withinClimbables :Boolean

Whether character is intersecting a climbable entity.

Default Value:
  • false
Source:

<readonly> withinClimbablesAbove :Boolean

Whether character is intersecting a climbable entity above its feet (i.e. inside body).

Default Value:
  • false
Source:

<readonly> withinOneWay :Boolean

Whether character is intersecting a one-way entity.

Default Value:
  • false
Source:

<readonly> withinStairs :Boolean

Whether character is intersecting a climbable stairs entity.

Default Value:
  • false
Source:

Methods

cleanup()

Source:

cleanupCollision()

Source:

clearPath()

Clears path.

Source:

climb()

Attempts to start climbing.

Source:

climbDown()

Attempts to start climbing and climb down.

Source:

climbEnd()

Stops climb in progress.

Source:

climbUp()

Attempts to start climbing and climb up.

Source:

climbUpdate()

Updates climb in progress.

Source:

collideWith()

Collides with another entity.
- sets grounded if other entity is ig.EntityExtended.COLLIDES.ACTIVE or {@link ig.EntityExtended.COLLIDES.FIXED}
- updates visible and animation if collision caused character to stop moving

Source:

die()

Automatically called when character finished being killed.
- removes invulnerability
- explodes if has ig.Character#explodingDeath and not ig.EntityExtended#dieingSilently

Source:

drainEnergy(amount, from, unblockable) → {Boolean}

Drain energy amount.

Parameters:
Name Type Argument Description
amount Number amount of energy.
from ig.EntityExtended <optional>
 entity source.
unblockable Boolean <optional>
 whether drain is unblockable.
Source:
Returns:
{ Boolean } whether applied.

explode(settings)

Creates particle explosion.

Parameters:
Name Type Argument Description
settings Object <optional>
 settings object for an ig.EntityExplosion.
Source:

findMoveToPath(settings)

Gets and processes a path from this character to an entity.

Parameters:
Name Type Argument Description
settings Object <optional>
 settings for finding path
Source:
See:

getIsCollidingWithOneWay()

Checks if character is colliding with a one-way climbable entity.

Source:

initProperties()

Initializes character properties.
- creates timers for things such as regen and damage delay
- creates ability collection

Source:

initTypes()

Initializes Character types.
- adds ig.EntityExtended.TYPE.CHARACTER to {@link ig.EntityExtended#type}

Source:

intersectWith()

Intersects and checks intersected for various properties such as one-way and climbable.

Source:

jump()

Attempts to start jumping.

Source:

jumpEnd()

Stops any jump in progress.

Source:

jumpPush()

Does jump push for number of jump steps.

Source:

jumpUpdate()

Updates jump in progress.

Source:

kill()

Kills character.

Source:

manageStart()

Characters stop moving to and pathfinding when managed.

Source:

moveFrom(entity, settings) → {Boolean}

Moves character away from entity or position instead of towards.
- this method hooks into the moveTo method and adds some extra properties

Parameters:
Name Type Argument Description
entity ig.EntityExtended entity to move away from
settings Object <optional>
 settings object
Source:
See:
Returns:
{ Boolean } whether a new move from has been started

moveTo()

Move to an entity or position using pathfinding when dynamic or the original method when not.

Source:
Example 
// if a character's performance is DYNAMIC
myCharacter.performance = ig.EntityExtended.PERFORMANCE.DYNAMIC;
// and the character can pathfind
myCharacter.canPathfind = true;
// this method will use pathfinding
// and not the original method
// which also means the settings change
// settings is still a plain object
settings = {};
// we can only search for paths
// that keep us within range of our target
// this also helps improve performance
settings.searchDistance = 100;
// if not doing simple pathfinding
// we can avoid other entities
settings.avoidEntities = true;
// but sometimes, all we care about is not going off an edge into the air
// so if we never want to fall off the edge of a platform
settings.avoidUngrounded = true;
// to do simple pathfinding
// or move towards target 1 node at a time
// this has much better performance
// but it is far less accurate and cannot avoid obstacles
// i.e. it is stupid (sometimes)
settings.simple = true;
// normally a character will do its best to treat slopes as safe
// but if you want to force it to avoid walking on slopes
// (note this only works on simple pathfinding)
settings.avoidSlopes = true;
// a character can often figure out
// when the next node in the path is not safe
// ex: a climbing area when the character cannot climb
// if we don't care and want to try to follow the path anyway
// (note this only works on simple pathfinding)
settings.unsafe = true;
// in most cases, the first node in the path is removed
// which fixes many silly pathfinding behaviors
// but if you want to keep it
settings.alwaysKeepFirst = true;

moveToComplete()

Source:

moveToDown(mod)

Accelerates character down at ig.Character#speed.

Parameters:
Name Type Argument Description
mod Number <optional>
 modifier to apply to speed.
Source:

moveToHere()

Zeroes all current acceleration and clears path.

Source:

moveToHereHorizontal()

Zeroes current horizontal acceleration.

Source:

moveToHereVertical()

Zeroes current vertical acceleration.

Source:

moveToLeft(mod)

Accelerates character left at ig.Character#speed.

Parameters:
Name Type Argument Description
mod Number <optional>
 modifier to apply to speed.
Source:

moveToPath(path, settings)

Moves a character along a path.

Parameters:
Name Type Argument Default Description
path Array <optional>
 this.path list of points to move to.
settings Object settings for moving along path
Source:
See:

moveToRight(mod)

Accelerates character right at ig.Character#speed.

Parameters:
Name Type Argument Description
mod Number <optional>
 modifier to apply to speed.
Source:

moveToSequenceNext()

Source:

moveToStop()

Source:

moveToUp(mod)

Accelerates character up at ig.Character#speed.

Parameters:
Name Type Argument Description
mod Number <optional>
 modifier to apply to speed.
Source:

moveToUpdate()

Source:

pause()

Source:

placeholdAnims()

Ensures all expected animations are present so checks don't have to be made at runtime. IMPORTANT: when an expected animation is missing, it is placeholded by the init anim or the current anim. This is not a smart fix!

Source:

ready()

Called by game when character added to game world.
- restores all stats to full
- adds temporary invulnerability

Source:

receiveDamage() → {Boolean}

Receives damage.
- optionally, creates explosion based on ig.Character#explodingDamage
- optionally, becomes temporarily invulnerable based on ig.Character#damageDelay

Source:
Returns:
{ Boolean } whether applied.

receiveEnergy(amount, from)

Restore energy amount.

Parameters:
Name Type Argument Description
amount Number amount to restore.
from ig.EntityExtended <optional>
 entity source.
Source:

receiveHealing(amount, from)

Restore health amount.

Parameters:
Name Type Argument Description
amount Number amount to restore.
from ig.EntityExtended <optional>
 entity source.
Source:

recordResetState()

Source:

regenerate()

Restores stats at a steady rate.

Source:

removeControl()

Removes control from character.

Source:

resetExtras()

Resets character movement, velocity, and flip.

Source:

restoreStats(from)

Restores all stats to their max values.

Parameters:
Name Type Argument Description
from ig.EntityExtended <optional>
 entity source.
Source:

setGrounded()

Source:

setUngrounded()

Source:

spawn()

Called when character spawned.

Source:

temporaryInvulnerability(duration)

Makes character temporarily invulnerable.

Parameters:
Name Type Argument Default Description
duration Number <optional>
 ig.Character#damageDelay duration in seconds of invulnerability
Source:

temporaryInvulnerabilityEnd()

Ends a temporary invulnerability in progress.

Source:

unpause()

Source:

updateChanges()

Changes character by updating various actions.
- updates temporary invulnerability
- regenerates stats
- updates abilities
- updates jump
- updates climb

Source:

updateCurrentAnim() → {Boolean}

Updates the current animation based on the status of the character.
- tries to swap to climb animation when climbing
- tries to swap to stairs animation when climbing stairs
- tries to swap to jump animation when jumping
- tries to swap to fall animation when in air but not jumping
- tries to swap to moveX/Y/Left/Right/Up/Down animation when moving
- defaults to idle animation

Source:
Returns:
{ Boolean } whether using non-idle animation

updateVelocity()

Updates various velocities and frictions based on whether grounded, climbing, etc.

Source:

updateVisible()

Updates visible and current animation via ig.Character#updateCurrentAnim.

Source: