Module `Hooks`

Defines the hooks provided by FTSE, for the Lua script to be notified when certain game events occur.

The FTSE engine will call the corresponding function in ftse.lua at the time the event occurs, with parameters corresponding to the state of the Fallout: Tactics game engine. Most hooks have one or more parameters, which will contain either information from the Fallout: Tactics executable (translated through the FTSE engine), or class objects corresponding to game state (world, entities, etc.). Some hooks also have an optional or required return value, which will often result in a change in game state depending on the hook.

Types

TimeStamp	Timestamp format used in MsecToDayHMS and AddBaseToGameTime.
CriticalEffects	CriticalEffects table format used in OnCriticalEffect1 and OnCriticalEffect2, and given as a parameter in OnDamageCalc.
TargetInfo	TargetInfo table format passed as a parameter to OnStraightAttack et al, describing eligible targets for an attack.
TargetResults	TargetResults table format returned by OnStraightAttack et al, describing actual hits made on any eligible targets for an attack.

Startup hooks

OnStart ()	OnStart is called immediately after start of the FTSE engine.
DefaultStyleChanges (style)	DefaultStyleChanges is called when the Fallout: Tactics executable sets up the default style object, used for text coloring.
OnLocaleLoad ()	OnLocaleLoad is called after the Fallout: Tactics executable has set up the table for locale strings.

Utility hooks

MsecToDayHMS (msec, scale)	MsecToDayHMS is called whenever Fallout: Tactics needs to convert the internal game time millisecond counter to an in-game date/time value.
AddBaseToGameTime (timestamp)	AddBaseToGameTime is called whenever Fallout: Tactics needs to convert a day+hour+minute+second timestamp to a year/month/day hh:mm:ss time.

Event hooks

OnLongTick (ent)	OnLongTick is called once per 10 seconds of game time, per entity.
OnRadiated (ent)	OnRadiated is called whenever an entity suffers radiation damage.
OnVariableChanged (key, value, isCampaign)	OnVariableChanged is called whenever a mission or campaign variable is updated.

Combat hooks

OnChanceToHitCalc (attacker, target, weapon, chanceInfo)	OnChanceToHitCalc is called whenever the game needs to calculate the chance of an attack hitting a desired target.
OnChanceToCritical1 (attacker, target, weapon, loc, chance)	OnChanceToCritical1 is called whenever an attack hits a target, and a check needs to be made to determine if the attack is a critical hit.
OnChanceToCritical2 (attacker, target, weapon, loc, chance)	OnChanceToCritical2 is called whenever an attack hits a target, and a check needs to be made to determine if the attack is a critical hit.
OnCriticalEffect1 (attacker, target, weapon, loc, roll)	OnCriticalEffect1 is called whenever an attack critically hits a target, and a check needs to be made to determine the effects of the critical hit.
OnCriticalEffect2 (attacker, target, weapon, loc, roll)	OnCriticalEffect2 is called whenever an attack critically hits a target, and a check needs to be made to determine the effects of the critical hit.
OnDamageCalc (attacker, target, weapon, loc, damage, critTable, rollArray)	OnDamageCalc is called whenever the game needs to calculate the final damage of an attack.
OnStraightAttack (attacker, shots, targetsArray, weapon)	OnStraightAttack is called whenever the game needs to calculate the effects of a "Straight" or "Normal" arc weapon.
OnAreaAttack (attacker, shots, targetsArray, weapon)	OnAreaAttack is called whenever the game needs to calculate the effects of an area-effect hit, usually an explosion (grenades, rockets, etc).
OnRadialAttack (attacker, shots, targetsArray, weapon)	OnRadialAttack is called whenever the game needs to calculate the effects of a "Radial" arc weapon.
OnSprayAttack (attacker, shots, targetsArray, weapon)	OnSprayAttack is called whenever the game needs to calculate the effects of a "Spray" arc weapon.
OnConeAttack (attacker, shots, targetsArray, weapon)	OnConeAttack is called whenever the game needs to calculate the effects of a "Cone" arc weapon (usually shotguns)
OnBurstAttack (attacker, shots, targetsArray, weapon)	OnBurstAttack is called whenever the game needs to calculate the effects of a "Burst" arc weapon.
OnProjectileAttack (attacker, shots, targetsArray, weapon)	OnProjectileAttack is called whenever the game needs to calculate the effects of an attack which draws a projectile.

Inventory hooks

OnInventoryAdd (receiver, item, quantity)	OnInventoryAdd is called whenever the game is preparing to add an item to an entity's inventory.
OnInventoryRemove (source, item, quantity)	OnInventoryRemove is called whenever the game is preparing to remove an item from an entity's inventory.
OnCheckItemAllowed (actor, item)	OnCheckItemAllowed is called whenever the game needs to check if an Actor can use the given item.
OnCheckEquip (actor, item, slot)	OnCheckEquip is called before an Actor equips an item.
OnEquip (actor, item, slot)	OnEquip is called after an Actor equips an item.
OnCheckUnequip (actor, item, slot)	OnCheckUnequip is called before an Actor unequips an item.
OnUnequip (actor, item, slot)	OnUnequip is called after an Actor unequips an item.

Types

TimeStamp

Timestamp format used in MsecToDayHMS and AddBaseToGameTime.

Fields:

year Year value in timestamp.
month Month value in timestamp.
day Day value in timestamp.
hour Hour value in timestamp.
minute Minute value in timestamp.
second Second value in timestamp.
msec Leftover milliseconds after timestamp conversion.

CriticalEffects

CriticalEffects table format used in OnCriticalEffect1 and OnCriticalEffect2, and given as a parameter in OnDamageCalc.

Fields:

bypassdefenses Set to true to ignore target resistances.
wickedhit Set to true to double damage.
knockdown Set to true to knock target down.
injure Set to true to injure the target at the aimed location, or a random location for unaimed attacks.
disarmright Set to true to force target to drop its right hand weapon (currently broken).
disarmleft Set to true to force target to drop its left hand weapon (currently broken).
knockout Set to true to knock target unconscious.
breakweapon Set to true to break the target's currently active weapon.
tornapart Set to true to cause a massive critical on the target. Depending on the result of a luck roll by the target, the damage is either multiplied by 4, or by a random value between 4 and 103.

TargetInfo

TargetInfo table format passed as a parameter to OnStraightAttack et al, describing eligible targets for an attack.

Fields:

actor The Entity object of the eligible target. Most often an Actor, but can be other Entity types as well.
hit_chance The normal chance of that target being hit from the attacker's current position and weapon.
distance The distance between attacker and this target.
angle (optional) The angle between the attacker's shot direction (to its intended target), and this particular target. May be used by Cone or Burst attack types to adjust chance to hit based on distance from the actual angle of fire. Not present for OnProjectileAttack.
intended A boolean field indicating if this target is the intended target of the attack.

TargetResults

TargetResults table format returned by OnStraightAttack et al, describing actual hits made on any eligible targets for an attack.

Fields:

id The "id" value from the Entity that is being hit.
hits The number of hits applied to this target.
mult A multiplier to the damage applied to this target. Used normally in the Cone and Radial attack types (shotguns, explosions) to make close shots more damaging.
deltax (optional) For OnProjectileAttack, how far to show the attack missing the target in the X direction. (Used in the animation of the projectile, but also has an effect if the projectile causes radial damage.)
deltaz (optional) For OnProjectileAttack, how far to show the attack missing the target in the Z direction. (Used in the animation of the projectile, but also has an effect if the projectile causes radial damage.)

Startup hooks

These hooks are generally called once at the start of the game process.

OnStart ()

OnStart is called immediately after start of the FTSE engine. This hook allows the Lua script a chance to update the internal tables (currently only perks are supported) prior to the game actually starting.

Returns:

None.

DefaultStyleChanges (style)

DefaultStyleChanges is called when the Fallout: Tactics executable sets up the default style object, used for text coloring. The Lua script can use the given DefaultStyle object to customize text colors.

Parameters:

style The DefaultStyle object, which can be called to make the desired text color customization.

Returns:

None.

OnLocaleLoad ()

OnLocaleLoad is called after the Fallout: Tactics executable has set up the table for locale strings. The Lua script can use the AddLocaleString function of the hookexecutor global object to add new locale strings.

Returns:

None.

Utility hooks

These hooks are called when the game needs to calculate some value for which a Lua script may want to override the result.

MsecToDayHMS (msec, scale)

MsecToDayHMS is called whenever Fallout: Tactics needs to convert the internal game time millisecond counter to an in-game date/time value. The conversion takes place in two steps. MsecToDayHMS converts the millisecond counter to days, hours, minutes, seconds, and milliseconds, optionally scaling it by the normal game scaling factor (by default, 3 game seconds to 1 real second). This is then added to the mission/campaign start offset by AddBaseToGameTime.

Parameters:

msec The current time on the game millisecond timer.
scale Whether this conversion should use the scaling factor.

Returns:

TimeStamp

AddBaseToGameTime (timestamp)

AddBaseToGameTime is called whenever Fallout: Tactics needs to convert a day+hour+minute+second timestamp to a year/month/day hh:mm:ss time. The conversion takes place in two steps. MsecToDayHMS first converts the millisecond timer to a day+hour+minute+second format. Then, AddBaseToGameTime adds starting year, month, day, etc. to that to give a final date/time.

Parameters:

timestamp The TimeStamp value returned from MsecToDayHMS.

Returns:

TimeStamp

Event hooks

These hooks are called when game events occur.

OnLongTick (ent)

OnLongTick is called once per 10 seconds of game time, per entity. This interval is used internally for checking radiation exposure, and nearby entities for Leader, Team Player, Loner, and Vat Skin perks/traits.

Parameters:

ent The entity whose long tick is being triggered.

Returns:

None.

OnRadiated (ent)

OnRadiated is called whenever an entity suffers radiation damage. This function is deprecated and will be replaced in the future with a more general damage notification hook.

Parameters:

ent Entity which suffered radiation damage.

Returns:

None.

OnVariableChanged (key, value, isCampaign)

OnVariableChanged is called whenever a mission or campaign variable is updated. Mission and campaign variables are stored as key/value pairs, with both key and value being strings. Fallout: Tactics will use these variables for updating its own triggers and actions. This hook allows Lua to be notified similarly whenever a variable is changed.

Parameters:

key The key (name) of the variable which changed.
value The new value for the variable.
isCampaign Boolean field indicating if the changed variable is a campaign variable (true) or mission variable (false).

Returns:

None.

Combat hooks

These hooks are called whenever combat results are being calculated.

OnChanceToHitCalc (attacker, target, weapon, chanceInfo)

OnChanceToHitCalc is called whenever the game needs to calculate the chance of an attack hitting a desired target. This is used in showing the percentage chance on the mouse cursor prior to an attack, in determining whether an attack meets the necessary chance for the sentry mode, and finally on the attack calculation itself. Note that the raw chance is important even if greater than 95%, as the reduction in chance due to aim location is taken into account after this function is processed.

Parameters:

attacker An Entity corresponding to the attacker. Usually an instance of the Actor class.
target The target being aimed at. Can be an Actor, Vehicle, Trap, Breakable, or StateBreakable.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.
chanceInfo A table holding the fields "hit_chance" (game calculated chance to hit), "raw_chance" (game calculated chance to hit, not capped at 95%), "location" (text string indicating the aimed location), and "ineligible_flags" (an integer, non-zero if the target can't be hit due to obstruction or range limit).

Returns:

(optional) The chanceInfo struct can be modified and returned by the function. Modifications to hit chance or eligibility are passed to Fallout: Tactics.

OnChanceToCritical1 (attacker, target, weapon, loc, chance)

OnChanceToCritical1 is called whenever an attack hits a target, and a check needs to be made to determine if the attack is a critical hit. Version 1 of this function is called for every attack type.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
target The target being aimed at. Can be an Actor, Vehicle, Trap, Breakable, or StateBreakable.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.
loc The location of an aimed attack, or an empty string for an unaimed attack.
chance The calculated chance for critical hit as determined by the game's default behavior.

Returns:

(required) The modified chance of a critical hit. Return the value of "chance" parameter to make no changes to critical chance.

OnChanceToCritical2 (attacker, target, weapon, loc, chance)

OnChanceToCritical2 is called whenever an attack hits a target, and a check needs to be made to determine if the attack is a critical hit. Version 2 of this function is called for unarmed or melee attacks only, and uses a separate set of criteria to determine critical chance.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
target The target being aimed at. Can be an Actor, Vehicle, Trap, Breakable, or StateBreakable.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.
loc The location of an aimed attack, or an empty string for an unaimed attack.
chance The calculated chance for critical hit as determined by the game's default behavior.

Returns:

(required) The modified chance of a critical hit. Return the value of "chance" parameter to make no changes to critical chance.

OnCriticalEffect1 (attacker, target, weapon, loc, roll)

OnCriticalEffect1 is called whenever an attack critically hits a target, and a check needs to be made to determine the effects of the critical hit. Version 1 of this function is called when the critical check for all attack types (version 1 of OnChanceToCritical1) succeeds.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
target The target being aimed at. Can be an Actor, Vehicle, Trap, Breakable, or StateBreakable.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.
loc The location of an aimed attack, or an empty string for an unaimed attack.
roll The modified roll value for the critical attack. The value is not capped at 100.

Returns:

(either-or required) A modified value for the critical effect roll, to be used in the default lookup table. If no modifications are desired, return the value of the "roll" parameter.

Or

CriticalEffects

OnCriticalEffect2 (attacker, target, weapon, loc, roll)

OnCriticalEffect2 is called whenever an attack critically hits a target, and a check needs to be made to determine the effects of the critical hit. Version 1 of this function is called when the critical check for unarmed/melee attack types (version 2 of OnChanceToCritical2) succeeds.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
target The target being aimed at. Can be an Actor, Vehicle, Trap, Breakable, or StateBreakable.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.
loc The location of an aimed attack, or an empty string for an unaimed attack.
roll The modified roll value for the critical attack. The value is not capped at 100.

Returns:

(either-or required) A modified value for the critical effect roll, to be used in the default lookup table. If no modifications are desired, return the value of the "roll" parameter.

Or

CriticalEffects

OnDamageCalc (attacker, target, weapon, loc, damage, critTable, rollArray)

OnDamageCalc is called whenever the game needs to calculate the final damage of an attack.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
target The target being aimed at. Can be an Actor, Vehicle, Trap, Breakable, or StateBreakable.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.
loc The location of an aimed attack, or an empty string for an unaimed attack.
damage The total damage as calculated by the game's default behaviors.
critTable A table formatted as a CriticalEffects value, indicating what critical effects are being applied.
rollArray An array of integers providing the individual damage rolls perfomed by Fallout: Tactics for each shot in a multi-shot weapon, prior to any resistances being applied. These can be used for more complex damage calculation, or for overriding resistances.

Returns:

(optional) A new damage value to pass to Fallout: Tactics for the given attack scenario. This damage will override that calculated by the game.

OnStraightAttack (attacker, shots, targetsArray, weapon)

OnStraightAttack is called whenever the game needs to calculate the effects of a "Straight" or "Normal" arc weapon.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
shots The number of shots in the attack. Usually 1, but can be different for some weapons (e.g. triple-fire pistols use 3).
targetsArray A Lua array containing a TargetInfo value for each eligible target. For Straight/Normal attacks, this is the intended target only.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.

Returns:

TargetResults

OnAreaAttack (attacker, shots, targetsArray, weapon)

OnAreaAttack is called whenever the game needs to calculate the effects of an area-effect hit, usually an explosion (grenades, rockets, etc).

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
shots The number of shots in the attack. Unsure what effect this has for area attacks.
targetsArray A Lua array containing a TargetInfo value for each eligible target in range.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.

Returns:

TargetResults

OnRadialAttack (attacker, shots, targetsArray, weapon)

OnRadialAttack is called whenever the game needs to calculate the effects of a "Radial" arc weapon. Note that this does not include explosions. One example is the electrical effect of the Pacifier Bot.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
shots The number of shots in the attack.
targetsArray A Lua array containing a TargetInfo value for each eligible target in range.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.

Returns:

TargetResults

OnSprayAttack (attacker, shots, targetsArray, weapon)

OnSprayAttack is called whenever the game needs to calculate the effects of a "Spray" arc weapon.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
shots The number of shots in the attack.
targetsArray A Lua array containing a TargetInfo value for each eligible target.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.

Returns:

TargetResults

OnConeAttack (attacker, shots, targetsArray, weapon)

OnConeAttack is called whenever the game needs to calculate the effects of a "Cone" arc weapon (usually shotguns)

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
shots The number of shots in the attack.
targetsArray A Lua array containing a TargetInfo value for each eligible target.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.

Returns:

TargetResults

OnBurstAttack (attacker, shots, targetsArray, weapon)

OnBurstAttack is called whenever the game needs to calculate the effects of a "Burst" arc weapon.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
shots The number of shots in the attack.
targetsArray A Lua array containing a TargetInfo value for each eligible target.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.

Returns:

TargetResults

OnProjectileAttack (attacker, shots, targetsArray, weapon)

OnProjectileAttack is called whenever the game needs to calculate the effects of an attack which draws a projectile. This includes thrown weapons, energy weapons with visible laser/energy bursts, and rocket launcher attacks, among others.

Parameters:

attacker An entity corresponding to the attacker. Usually an instance of the Actor class.
shots The number of shots in the attack. The game will only animate a single projectile, but will calculate effects for all attacks.
targetsArray A Lua array containing a TargetInfo value for each eligible target. For projectile attacks, this array includes only the intended target.
weapon The weapon being used in the attack. Usually a Weapon or VehicleWeapon, but could possibly be a Trap or a Breakable.

Returns:

TargetResults

Inventory hooks

These hooks are called whenever inventory or equipment operations or events occur in the game.

OnInventoryAdd (receiver, item, quantity)

OnInventoryAdd is called whenever the game is preparing to add an item to an entity's inventory. The call occurs once it has been determined that the item can be added to inventory successfully, but before the item is actually added. NOTE that the "id" value of the item will change once it is moved to the inventory of the receiver, so do not save the "id" value for any purpose.

Parameters:

receiver The Entity receiving the item. Can be an Actor, Container, or Vehicle.
item The item being received. Must be a subclass of Collectable.
quantity How many of the indicated item will be added to inventory.

Returns:

None.

OnInventoryRemove (source, item, quantity)

OnInventoryRemove is called whenever the game is preparing to remove an item from an entity's inventory. The call occurs once it has been determined that the item can be remvoed from the inventory successfully, but before the item is actually removed. NOTE that the "id" value of the removed entity will change once it is removed, so do not save the "id" value for any purpose.

Parameters:

source The Entity losing the item Can be an Actor, Container, or Vehicle.
item The item being removed. Must be a subclass of Collectable.
quantity How many of the indicated item will be removed from inventory.

Returns:

None.

OnCheckItemAllowed (actor, item)

OnCheckItemAllowed is called whenever the game needs to check if an Actor can use the given item. This is called for weapons and armours. Unsure if it is called for skill items or consumables.

Parameters:

actor The Actor to check for ability to use the item.
item The item being checked for eligibility.

Returns:

(optional) A boolean value indicating if the item can be used (true) or not (false). If not specified, the game will use its default behavior.

OnCheckEquip (actor, item, slot)

OnCheckEquip is called before an Actor equips an item.

Parameters:

actor The actor that is equipping an item.
item The Entity being equipped.
slot The hand or armor slot being equipped into. Values are EQUIP_SLOT_LEFT, EQUIP_SLOT_RIGHT, or EQUIP_SLOT_ARMOR.

Returns:

Return nothing if the equip should be allowed, or a locale-defined string if it should not. The string must be defined in locale with a "log_" prefix. An example of an existing string is "cannotRemove".

OnEquip (actor, item, slot)

OnEquip is called after an Actor equips an item.

Parameters:

actor The actor that equipped an item.
item The Entity being equipped.
slot The hand or armor slot being equipped into. Values are EQUIP_SLOT_LEFT, EQUIP_SLOT_RIGHT, or EQUIP_SLOT_ARMOR.

Returns:

None.

OnCheckUnequip (actor, item, slot)

OnCheckUnequip is called before an Actor unequips an item.

Parameters:

actor The actor that is unequipping an item.
item The Entity being unequipped.
slot The hand or armor slot being unequipped from. Values are EQUIP_SLOT_LEFT, EQUIP_SLOT_RIGHT, or EQUIP_SLOT_ARMOR.

Returns:

Return nothing if the unequip should be allowed, or a locale-defined string if it should not. The string must be defined in locale with a "log_" prefix. An example of an existing string is "cannotRemove".

OnUnequip (actor, item, slot)

OnUnequip is called after an Actor unequips an item.

Parameters:

actor The actor that unequipped an item.
item The Entity being unequipped.
slot The hand or armor slot being unequipped from. Values are EQUIP_SLOT_LEFT, EQUIP_SLOT_RIGHT, or EQUIP_SLOT_ARMOR.

Returns:

None.

FTSE

Contents

Hooks

Entity classes

Global Classes

Manual

Examples

Module Hooks

Types

Startup hooks

Utility hooks

Event hooks

Combat hooks

Inventory hooks

Types

Fields:

Fields:

Fields:

Fields:

Startup hooks

Returns:

Parameters:

Returns:

Returns:

Utility hooks

Parameters:

Returns:

Parameters:

Returns:

Event hooks

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Combat hooks

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Or

Parameters:

Returns:

Or

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Inventory hooks

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Module `Hooks`