New onXYZ Functions

• Create a new skill event
• MSU added events
  • Skill execution
    • onBeforeAnySkillExecuted
    • onAnySkillExecuted
  • Items
    • onEquip
    • onUnequip
  • Actor movement
    • onMovementStarted
    • onMovementFinished
    • onMovementStep
  • Actor death
    • onDeathWithInfo
    • onOtherActorDeath
  • Tooltips
    • onQueryTooltip
    • onQueryTileTooltip
    • onGetHitFactors
    • onGetHitFactorsAsTarget
    • onAffordablePreview
  • Other
    • onSkillsUpdated
    • onAfterDamageReceived
    • onNewMorning
    • onUpdateLevel
    • onEnterSettlement

Create a new skill event

MSU allows modders to easily create new events in skill.nut without having to manually hook different files. This is done as follows:

::MSU.Skills.addEvent( _name, _function = null, _update = true, _aliveOnly = false )
// _name is a string
// _function is a function
// _update is a boolean
// _aliveOnly is a boolean

The above code will create a new event function in skill.nut and skill_container.nut with the name of _name. If _function is null, then a new empty function is used otherwise the passed function will be used as the event. If _update is true then skill_container update() is called at the end of the event. If _aliveOnly is true then the events will only be called as long as the actor is alive.

Example

::MSU.Skills.addEvent( "onSomeTrigger")

The above code will create a new event called "onSomeTrigger" which can then be triggered from any part of the code. For example, one could write in an actor file:

// inside some function
this.getSkills().onSomeTrigger();

The function can then be overwritten manually just like other similar functions in individual skills. For example, in a new perk called myNewPerk, one can write:

function onSomeTrigger()
{
  // stuff to do when this event triggers
}

MSU added events

MSU adds the following onXYZ functions to all skills. These functions are called on all skills of an actor whenever they trigger.

Skill execution

onBeforeAnySkillExecuted( _skill, _targetTile, _targetEntity, _forFree )
onAnySkillExecuted( _skill, _targetTile, _targetEntity, _forFree )
// _skill is the skill being executed
// _targetTile is the tile on which the skill is being executed
// _targetEntity is the entity occupying _targetTile and is null if the tile is empty
// _forFree is a boolean which is true if the skill usage is for free

The first function is called before the used skill's use function triggers, whereas the second function is called after the use function is complete.

Items

onEquip

onEquip( _item )
// _item is the item being equipped

This event is called after the item has been equipped.

onUnequip

onUnequip( _item )
// _item is the item being unequipped

This event is called before the item is unequipped.

Actor movement

onMovementStarted

onMovementStarted( _tile, _numTiles ) // called when starting a movement
// _tile is the starting tile
// _numTiles is the number of tiles being moved

During the call to this function the this.m.IsMoving Boolean of the actor is true.

onMovementFinished

onMovementFinished( _tile ) // called after finishing a movement
// _tile is the tile on which movement is finished

During the call to this function the this.m.IsMoving Boolean of the actor is true.

onMovementStep

onMovementStep( _tile, _levelDifference ) // called on every tile of movement
// _tile is the tile currently being moved on
// _levelDifference is the level difference of this tile from the previous tile

Note that onMovementStep is triggered even when the movement is prevented e.g. due to an attack of opportunity from an adjacent enemy. Therefore, if you really want to be sure that the actor actually moved, you should do a check such as if (!_tile.isSameTileAs(this.getContainer().getActor().getTile()).

Actor death

onDeathWithInfo

onDeathWithInfo( _killer, _skill, _deathTile, _corpseTile, _fatalityType )
// _killer is an actor who killed this actor, can be null if there is no killer
// _skill is the skill used to kill
// _deathTile is the tile on which the dying entity was placed when the killing blow was struck. It will be null if the actor died while `isPlacedOnMap()` is false
// _corpseTile is the tile on which the dying entity's corpse spawned and can be null if no valid corpse tile existed
// _fatalityType is the type of fatality of this kill

This function is more useful than the standard onDeath() function of skills as it passes several parameters. Note, however, that this function is called via a hook into the onDeath function of actor.nut. That function is normally called at the end of each entity's own individual onDeath function. Hence, this function runs after the entity's own onDeath() function but before the base actor.nut onDeath() function.

onOtherActorDeath

onOtherActorDeath( _killer, _victim, _skill, _deathTile, _corpseTile, _fatalityType )
// _killer is an actor who killed _victim. Can be null if there is no killer
// _victim is the dying actor
// _skill is the skill used to kill
// _deathTile is the tile on which the dying entity was placed when the killing blow was struck
// _corpseTile is the tile on which the dying entity's corpse spawned. Can be null if no valid corpse tile existed
// _fatalityType is the type of fatality of this kill

This function is called for all actors on the tactical map when an actor dies. Note that this function is only called when the tactical state is not Fleeing and when the _deathTile is not null i.e. the dying actor isPlacedOnMap(). This function is called via a hook into the onDeath() function of the dying actor and hence is called before the onOtherActorDeath() functions of the actors on the battlefield are called.

Tooltips

onQueryTooltip

onQueryTooltip( _skill, _tooltip )
// _skill is the skill for which the tooltip has been queried
// _tooltip is the tooltip returned by _skill's getTooltip() function

This function is called for all skills the character has when the tooltip for any skill is queried. This allows other skills to modify the tooltip before it is displayed to the user.

onQueryTileTooltip

onQueryTileTooltip( _tile, _tooltip )
// _tile is a Tile instance
// _tooltip is the tooltip returned by _skill's getTooltip() function

This function is called for all skills of the currently active character in the turn sequence, if that character is player controlled, when the player moves the mouse over a tile and triggers its tooltip. This allows skills to modify the tooltip before it is displayed to the user.

onGetHitFactors

onGetHitFactors( _skill, _targetTile, _tooltip )
// _skill is the skill being used
// _targetTile is the tile on which _skill is being used
// _tooltip is what is generated by the getHitFactors(_targetTile) function of _skill

This function is called for all skills the character has when the hit factors tooltip is displayed. This allows individual skills to modify and/or add entries to the hit factors tooltip before it is displayed to the user.

onGetHitFactorsAsTarget

onGetHitFactorsAsTarget( _skill, _targetTile, _tooltip )
// _skill is the skill being used
// _targetTile is the tile on which _skill is being used
// _tooltip is what is generated by the getHitFactors(_targetTile) function of _skill

This function is called for all skills the entity on _targetTile has when the hit factors tooltip is displayed as long as the target entity is not the same as the entity using the skill. This allows individual skills to modify and/or add entries to the hit factors tooltip before it is displayed to the user.

onAffordablePreview

onAffordablePreview( _skill, _movementTile )
// _skill is the skill whose use is being previewed. Will be null if the preview is a movement instead of skill usage.
// _movementTile is the furthest tile that can be moved to while previewing a movement. Will be null if if the preview is a skill usage instead of movement.

This allows skills to modify the preview costs of other skills. See Affordability Preview for details.

Other

onAfterDamageReceived

onAfterDamageReceived()

This function is called after the actor has received damage as long as the actor is still alive.

onNewMorning

onNewMorning()

This function is called when the time of day reaches Morning. This is different from onNewDay() which runs at noon.

onUpdateLevel

onUpdateLevel()

This function is called when the player character levels up.
Use this.getContainer().getActor().getLevel() to get the current level of the player.

onEnterSettlement

onEnterSettlement( _settlement )
// _settlement is the settlement being entered

This function is called when the player party enters a settlement.