Hook types


AdjustFID

HOOK_ADJUSTFID (hs_adjustfid.int)

Runs after calculating character figure FID on the inventory screen, whenever the game decides that character appearance might change. Also happens on other screens, like barter.

NOTE: FID has following format: 0x0ABBCDDD, where A is object type, BB - animation code (always 0 in this case), C - weapon code, DDD - FRM index in LST file.

int     arg1 - the vanilla fid calculated by the engine according to critter base FID and armor/weapon being used

int     ret1 - overrides the calculated FID with provided value

AfterHitRoll

HOOK_AFTERHITROLL (hs_afterhitroll.int)

Runs after Fallout has decided if an attack will hit or miss.

int     arg1 - If the attack will hit. (0 - critical miss, 1 - miss, 2 - hit, 3 - critical hit)
critter arg2 - The attacker
critter arg3 - The target of the attack
int     arg4 - The bodypart
int     arg5 - The hit chance

int     ret1 - Override the hit/miss
int     ret2 - Override the targeted bodypart
critter ret3 - Override the target of the attack

AmmoCost

HOOK_AMMOCOST (hs_ammocost.int)

Runs when calculating ammo cost for a weapon. Doesn’t affect damage, only how much ammo is spent. By default, weapon will shoot when at least 1 round is left, regardless of ammo cost calculations. To add proper check for ammo before shooting and proper calculation of number of burst rounds (hook type 1 and 2 in arg4), set Misc.CheckWeaponAmmoCost=1 in ddraw.ini

Item    arg1 - weapon
int     arg2 - Number of bullets in burst (1 for single shots)
int     arg3 - Ammo cost calculated by original function (this is basically 2 for Super Cattle Prod and Mega Power Fist)
int     arg4 - Type of hook (0 - when subtracting ammo after single shot attack, 1 - when checking for "out of ammo" before attack, 2 - when calculating number of burst rounds, 3 - when subtracting ammo after burst attack)

int     ret1 - new ammo cost value (set to 0 for unlimited ammo)

BarterPrice

HOOK_BARTERPRICE (hs_barterprice.int)

Runs whenever the value of goods being purchased is calculated.

critter arg1 - the critter doing the bartering (either dude_obj or inven_dude)
critter arg2 - the critter being bartered with
int     arg3 - the default value of the goods
critter arg4 - table of requested goods (being bought from NPC)
int     arg5 - the amount of actual caps in the barter stack (as opposed to goods)
int     arg6 - the value of all goods being traded before skill modifications
critter arg7 - table of offered goods (being sold to NPC)
int     arg8 - the total cost of the goods offered by the player
int     arg9 - set 1 if the "offers" button was pressed (not for a party member), otherwise 0

int     ret1 - the modified value of all of the goods (pass -1 if you just want to modify offered goods)
int     ret2 - the modified value of all offered goods

CalcAPCost

HOOK_CALCAPCOST (hs_calcapcost.int)

Runs whenever Fallout is calculating the AP cost of using the weapon (or unarmed attack). Doesn’t run for using other item types or moving. Note that the first time a game is loaded, this script doesn’t run before the initial interface is drawn, so if the script effects the AP cost of whatever is in the player’s hands at the time the wrong AP cost will be shown. It will be fixed the next time the interface is redrawn. You can get the weapon object by checking item slot based on attack type (ATKTYPE_LWEP1, ATKTYPE_LWEP2, etc) and then calling critter_inven_obj().

critter arg1 - The critter performing the action
int     arg2 - Attack Type (see ATKTYPE_* constants)
int     arg3 - Is aimed attack (1 or 0)
int     arg4 - The normal AP cost

int     ret1 - The new AP cost

CarTravel

HOOK_CARTRAVEL (hs_cartravel.int)

Runs continuously during worldmap travel on car.

int     arg1 - vanilla car speed (between 3 and 8 "steps")
int     arg2 - vanilla fuel consumption (100 and below)

int     ret1 - car speed override (pass -1 if you just want to override fuel consumption)
int     ret2 - fuel consumption override

CombatDamage

HOOK_COMBATDAMAGE (hs_subcombatdmg.int)

Runs when:

  1. Game calculates how much damage each target will get. This includes primary target as well as all extras (explosions and bursts). This happens BEFORE the actual attack animation.
  2. AI decides whether it is safe to use area attack (burst, grenades), if he might hit friendlies.

Does not run for misses, or non-combat damage like dynamite explosions.

critter arg1  - The target
critter arg2  - The attacker
int     arg3  - The amount of damage to the target
int     arg4  - The amount of damage to the attacker
int     arg5  - The special effect flags for the target (use bwand DAM_* to check specific flags)
int     arg6  - The special effect flags for the attacker (use bwand DAM_* to check specific flags)
int     arg7  - The weapon used in the attack
int     arg8  - The bodypart that was struck
int     arg9  - Damage Multiplier (this is divided by 2, so a value of 3 does 1.5x damage, and 8 does 4x damage. Usually it's 2; for critical hits, the value is taken from the critical table; with Silent Death perk and the corresponding attack conditions, the value will be doubled)
int     arg10 - Number of bullets actually hit the target (1 for melee attacks)
int     arg11 - The amount of knockback to the target
int     arg12 - Attack Type (see ATKTYPE_* constants)

int     ret1 - The damage to the target
int     ret2 - The damage to the attacker
int     ret3 - The special effect flags for the target
int     ret4 - The special effect flags for the attacker
int     ret5 - The amount of knockback to the target

CombatTurn

HOOK_COMBATTURN (hs_combatturn.int)

Runs before and after each turn in combat (for both PC and NPC).

int     arg1 - event type: 1 - start of turn, 0 - normal end of turn, -1 - combat ends abruptly (by script or by pressing Enter during PC turn), -2 - combat ends normally (hook always runs at the end of combat)
int     arg2 - critter doing the turn
bool    arg3 - 1 at the start/end of the player's turn after loading a game saved in combat mode, 0 otherwise

int     ret1 - pass 1 at the start of turn to skip the turn, pass -1 at the end of turn to force end of combat

DeathAnim1

HOOK_DEATHANIM1 (hs_deathanim1.int)

Runs before Fallout tries to calculate the death animation. Lets you switch out which weapon Fallout sees.

int     arg1 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
critter arg2 - The attacker
critter arg3 - The target
int     arg4 - The amount of damage

int     ret1 - The pid of an object to override the attacking weapon with

DeathAnim2

HOOK_DEATHANIM2 (hs_deathanim2.int)

Runs after Fallout has calculated the death animation. Lets you set your own custom frame id, so more powerful than hs_deathanim1, but performs no validation. When using critter_dmg function, this script will also run. In that case weapon pid will be -1 and target will point to an object with obj_art_fid == 0x20001F5.

item    arg1 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
critter arg2 - The attacker
critter arg3 - The target
int     arg4 - The amount of damage
int     arg5 - The death anim id calculated by Fallout

int     ret1 - The death anim id to override with

Deprecated hooks

  • hs_hexmoveblocking.int
  • hs_hexaiblocking.int
  • hs_hexshootblocking.int
  • hs_hexsightblocking.int

Run when checking to see if a hex blocks movement or shooting. (or ai-ing, presumably…)

NOTE: these hook scripts can become very CPU-intensive and you should avoid using them. For this reason, they may be removed in future versions. If you want to check if some tile or path is blocked, use functions: obj_blocking_tile, obj_blocking_line, path_find_to. If you want script to be called every time NPC moves by hex in combat, use hs_movecost hook.

Critter arg1 - the critter doing the moving
int     arg2 - the tile number being checked
int     arg3 - the elevation being checked
int     arg4 - 1 if the hex would normally be blocking

object* ret1 - 0 if the hex doesn't block, or any sort of object pointer if it does

DescriptionObj

HOOK_DESCRIPTIONOBJ (hs_descriptionobj.int)

Runs when using the examine action icon to display item description. You can override the description of the item. An example usage would be to add an additional description to the item based on player’s stats/skills.

Obj     arg1 - the item

int     ret1 - a pointer to the new text received by using "get_string_pointer" function

ExplosiveTimer

HOOK_EXPLOSIVETIMER (hs_explosivetimer.int)

Runs after setting the explosive timer. You can override the result.

int     arg1 - the time in ticks set in the timer
Obj     arg2 - the explosive object
int     arg3 - the result of engine calculation of whether the timer was set successfully: 1 - failure, 2 - success (similar to ROLL_* in Condtion.h)

int     ret1 - overrides the time of the timer (maximum 18000 ticks)
int     ret2 - overrides the result of engine calculation: 0/1 - failure, 2/3 - success (similar to ROLL_*), any other value - use engine handler

FindTarget

HOOK_FINDTARGET (hs_findtarget.int)

Runs when the ai is trying to pick a target in combat. Fallout first chooses a list of 4 likely suspects, then normally sorts them in order of weakness/distance/etc depending on the ai caps of the attacker. This hook replaces that sorting function, allowing you to sort the targets in some arbitrary way. Use sfall_return to give the 4 targets, in order of preference. If you want to specify less than 4 targets, fill in the extra spaces with 0’s. Pass -1 to skip the return value.

The return values can include critters that weren’t in the list of possible targets, but the additional targets may still be discarded later on in the combat turn if they are out of the attackers perception or the chance of a successful hit is too low. The list of possible targets often includes duplicated entries.

critter arg1 - The attacker
critter arg2 - A possible target
critter arg3 - A possible target
critter arg4 - A possible target
critter arg5 - A possible target

critter ret1 - The first choice of target
critter ret2 - The second choice of target
critter ret3 - The third choice of target
critter ret4 - The fourth choice of target

GameModeChange

HOOK_GAMEMODECHANGE (hs_gamemodechange.int)

Runs once every time when the game mode was changed, like opening/closing the inventory, character screen, pipboy, etc.

int     arg1 - event type: 1 - when the player exits the game, 0 - otherwise

InvenWield

HOOK_INVENWIELD (hs_invenwield.int)

Runs before wielding or unwielding an armor or a weapon by a critter (except when using inventory by PC). An example usage would be to change critter art depending on armor being used or to dynamically customize weapon animations. NOTE: when replacing a previously wielded armor or weapon, the unwielding hook will not be executed. If you need to rely on this, try checking if armor/weapon is already equipped when wielding hook is executed.

Critter arg1 - critter
Obj     arg2 - item being wielded or unwielded (weapon/armor)
int     arg3 - slot (INVEN_TYPE_*)
int     arg4 - 1 when wielding, 0 when unwielding

int     ret1 - overrides hard-coded handler (-1 - use engine handler, any other value - override) - NOT RECOMMENDED

InventoryMove

HOOK_INVENTORYMOVE (hs_inventorymove.int)

Runs before moving items between inventory slots in dude interface. You can override the action. What you can NOT do with this hook:

  • force moving items to inappropriate slots (like gun in armor slot) What you can do:
  • restrict player from using specific weapons or armors
  • add AP costs for all inventory movement including reloading
  • apply or remove some special scripted effects depending on PC’s armor
int     arg1 - Target slot (0 - main backpack, 1 - left hand, 2 - right hand, 3 - armor slot, 4 - weapon, when reloading it by dropping ammo, 5 - container, like bag/backpack, 6 - dropping on the ground, 7 - picking up item, 8 - dropping item on the character portrait)
Item    arg2 - Item being moved
Item    arg3 - Item being replaced, weapon being reloaded, or container being filled (can be 0)

int     ret1 - Override setting (-1 - use engine handler, any other value - prevent relocation of item/reloading weapon/picking up item)

ItemDamage

HOOK_ITEMDAMAGE (hs_itemdamage.int)

Runs when retrieving the damage rating of the player’s used weapon. (Which may be their fists.)

int     arg1 - The default min damage
int     arg2 - The default max damage
Item    arg3 - The weapon used. (0 if unarmed)
Critter arg4 - The critter doing the attacking
int     arg5 - The type of attack
int     arg6 - non-zero if this is an attack using a melee weapon

int     ret1 - Either the damage to be used, if ret2 isn't given, or the new minimum damage if it is
int     ret2 - The new maximum damage

KeyPress

HOOK_KEYPRESS (hs_keypress.int)

Runs once every time when any key was pressed or released.

NOTE: if you want to override a key, the new key DX scancode should be the same for both pressed and released events.

int     arg1 - event type: 1 - pressed, 0 - released
int     arg2 - key DX scancode
int     arg3 - key VK code (very similar to ASCII codes)

int     ret1 - overrides the pressed key (a new key DX scancode or 0 for no override)

MouseClick

HOOK_MOUSECLICK (hs_mouseclick.int)

Runs once every time when a mouse button was pressed or release.

int     arg1 - event type: 1 - pressed, 0 - released
int     arg2 - button number (0 - left, 1 - right, up to 7)

MoveCost

HOOK_MOVECOST (hs_movecost.int)

Runs when calculating the AP cost of movement

Critter arg1 - the critter doing the moving
int     arg2 - the number of hexes being moved
int     arg3 - the original AP cost

int     ret1 - the new AP cost

OnDeath

HOOK_ONDEATH (hs_ondeath.int)

Runs immediately after a critter dies for any reason. No return values; this is just a convenience for when you need to do something after death for a large number of different critters and don’t want to have to script each and every one of them.

Critter arg1 - The critter that just died

OnExplosion

HOOK_ONEXPLOSION (hs_onexplosion.int)

Runs when Fallout is checking all the tiles within the explosion radius for targets before an explosion occurs. The tile checking will be interrupted when 6 additional targets (critters) are received.

int     arg1 - event type: 1 - when checking objects within the explosion radius without causing damage (e.g. the player drops an active explosive), 0 - otherwise
Critter arg2 - The attacker
int     arg3 - The tile on which the explosion occurs
int     arg4 - checked tile within the explosion radius
Obj     arg5 - first found object on the checked tile as an additional target
Critter arg6 - The target critter, may be 0 or equal to the attacker
int     arg7 - 1 when using throwing weapons (e.g. grenades), 0 otherwise

int     ret1 - overrides the found object on the checked tile, pass 0 to skip the object

RemoveInvenObj

HOOK_REMOVEINVENOBJ (hs_removeinvenobj.int)

Runs when an object is removed from a container or critter’s inventory for any reason.

Obj     arg1 - the owner that the object is being removed from
item    arg2 - the item that is being removed
int     arg3 - the number of items to remove
int     arg4 - The reason the object is being removed (see RMOBJ_* constants)
Obj     arg5 - The destination object when the item is moved to another object, otherwise 0

RestTimer

HOOK_RESTTIMER (hs_resttimer.int)

Runs continuously while the player is resting (using pipboy alarm clock).

int     arg1 - the game time in ticks
int     arg2 - event type: 1 - when the resting ends normally, -1 - when pressing ESC to cancel the timer, 0 - otherwise
int     arg3 - the hour part of the length of resting time
int     arg4 - the minute part of the length of resting time

int     ret1 - pass 1 to interrupt the resting, pass 0 to continue the rest if it was interrupted by pressing ESC key

SetGlobalVar

HOOK_SETGLOBALVAR (hs_setglobalvar.int)

Runs when setting the value of a global variable.

int     arg1 - the index number of the global variable being set
int     arg2 - the set value of the global variable

int     ret1 - overrides the value of the global variable

SetLighting

HOOK_SETLIGHTING (hs_setlighting.int)

Runs before setting the light level for an object or a map. You can override the result.

Obj     arg1 - the object being set, or -1 when setting the light level for a map
int     arg2 - the light intensity
int     arg3 - the light radius, or -1 when setting the light level for a map

int     ret1 - overrides the light intensity. Intensity range is from 0 to 65536
int     ret2 - overrides the light radius. Radius range is from 0 to 8 (works only for the object)

Sneak

HOOK_SNEAK (hs_sneak.int)

Runs when the Sneak skill is activated, or when the game rolls another Sneak check after the duration for the current one is over. You can override the result of a random Sneak check or the duration time for the current result.

int     arg1 - Sneak check result: 1 - success, 0 - failure
int     arg2 - the duration in ticks for the current Sneak check (time depends on Sneak skill level)
Critter arg3 - the critter (usually dude_obj)

int     ret1 - overrides the result of the Sneak check
int     ret2 - overrides the duration time for the current result

Steal

HOOK_STEAL (hs_steal.int)

Runs when checking an attempt to steal or plant an item in other inventory using Steal skill.

This is fired before the default handlers are called, which you can override. In this case you MUST provide message of the result to player (“You steal the %s”, “You are caught planting the %s”, etc.). Example message (vanilla behavior): display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg4*2), obj_name(arg3)));

Critter arg1 - Thief
Obj     arg2 - The target
Item    arg3 - Item being stolen/planted
int     arg4 - 0 when stealing, 1 when planting

int     ret1 - overrides hard-coded handler (1 - force success, 0 - force fail, -1 - use engine handler)

SubCombatDamage

HOOK_SUBCOMBATDAMAGE (hs_subcombatdamage.int)

This hook overrides the vanilla damage calculation formula. Runs when:

  1. Before the game calculates how much damage each target will get. This includes primary target as well as all extras (explosions and bursts).
  2. AI decides whether it is safe to use area attack (burst, grenades), if he might hit friendlies.

Does not run for misses, non-combat damage like dynamite explosions, or if one of the damage formulas is selected in ddraw.ini.

Critter arg1 - The attacker
Critter arg2 - The target
Obj     arg3 - The weapon used in the attack
int     arg4 - Attack Type (see ATKTYPE_* constants)
int     arg5 - Number of bullets actually hit the target (1 for melee attacks)
int     arg6 - Target's Damage Resistance (DR) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
int     arg7 - Target's Damage Threshold (DT) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
int     arg8 - Bonus ranged damage from the perk
int     arg9 - Damage Multiplier (this is divided by 2, so a value of 3 does 1.5x damage, and 8 does 4x damage. Usually it's 2; for critical hits, the value is taken from the critical table; with Silent Death perk and the corresponding attack conditions, the value will be doubled)
int     arg10 - Combat Difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it's always 100)
int     arg11 - The calculated amount of damage (usually 0, required when using multiple hook scripts to calculate damage and using the set_sfall_arg function)
mixed   arg12 - Computed attack results (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)

int     ret1 - The returned amount of damage

ToHit

HOOK_TOHIT (hs_tohit.int)

Runs when Fallout is calculating the chances of an attack striking a target. Runs after the hit chance is fully calculated normally, including applying the 95% cap.

int     arg1 - The unmodified hit chance
critter arg2 - The attacker
critter arg3 - The target of the attack
int     arg4 - The targeted bodypart
int     arg5 - Source tile (may differ from attacker's tile, when AI is considering potential fire position)
int     arg6 - Attack Type (one of ATKTYPE_*)
int     arg7 - Ranged flag (0 or 1, actually passed 1 even for unarmed attacks, may be a vanilla bug)

int     ret1 - the new hit chance

UseAnimObj

HOOK_USEANIMOBJ (hs_useanimobj.int)

Runs before playing the “use” (usually “magic hands”) animation when a critter uses a scenery/container object on the map, or before walking/running animation if the player is at a distance from the object.

Critter arg1 - the critter that uses an object (usually dude_obj)
Obj     arg2 - the object being used
int     arg3 - the animation code being used (see ANIM_* in Animcomd.h)

int     ret1 - overrides the animation code (pass -1 if you want to skip the animation)

UseObj

HOOK_USEOBJ (hs_useobj.int)

Runs when:

  1. a critter uses an object from inventory which have “Use” action flag set or it’s an active flare or dynamite.
  2. player uses an object from main interface

This is fired before the object is used, and the relevant use_obj script procedures are run. You can disable default item behavior. NOTE: you can’t remove and/or destroy this object during the hookscript (game will crash otherwise). To remove it, return 1.

Critter arg1 - The user
int     arg2 - The object used

int     ret1 - overrides hard-coded handler and selects what should happen with the item (0 - place it back, 1 - remove it, -1 - use engine handler)

UseObjOn

HOOK_USEOBJON (hs_useobjon.int)

Runs when:

  1. a critter uses an object on another critter. (Or themselves)
  2. a critter uses an object from inventory screen AND this object does not have “Use” action flag set and it’s not active flare or explosive.
  3. player or AI uses any drug

This is fired before the object is used, and the relevant use_obj_on script procedures are run. You can disable default item behavior. NOTE: you can’t remove and/or destroy this object during the hookscript (game will crash otherwise). To remove it, return 1.

Critter arg1 - The target
Critter arg2 - The user
int     arg3 - The object used

int     ret1 - overrides hard-coded handler and selects what should happen with the item (0 - place it back, 1 - remove it, -1 - use engine handler)

UseSkill

HOOK_USESKILL (hs_useskill.int)

Runs when using any skill on any object.

This is fired before the default handlers are called, which you can override. In this case you should write your own skill use handler entirely, or otherwise nothing will happen (this includes fade in/fade out, time lapsing and messages - all of this can be scripted; to get vanilla text messages - use message_str_game() along with sprintf()). Suggested use - override first aid/doctor skills to buff/nerf them, override steal skill to disallow observing NPCs inventories in some cases. Doesn’t seem to run when lock picking.

Critter arg1 - The user critter
Obj     arg2 - The target object
int     arg3 - skill being used
int     arg4 - skill bonus from items such as first aid kits

int     ret1 - overrides hard-coded handler (-1 - use engine handler, any other value - override)

UseSkillOn

HOOK_USESKILLON (hs_useskillon.int)

Runs before using any skill on any object. Lets you override the critter that uses the skill. NOTE: the user critter can’t be overridden when using Steal skill.

Critter arg1 - The user critter (usually dude_obj)
Obj     arg2 - The target object/critter
int     arg3 - skill being used

int     ret1 - a new critter to override the user critter. Pass -1 to cancel the skill use, pass 0 to skip this return value
int     ret2 - pass 1 to allow the skill being used in combat (only for dude_obj or critter being controlled by the player)

WithinPerception

HOOK_WITHINPERCEPTION (hs_withinperception.int)

Runs when checking if one critter sees another critter. This is used in different situations like combat AI. You can override the result.

NOTE: obj_can_see_obj calls this first when deciding if critter can possibly see another critter with regard to perception, lighting, sneak factors. If check fails, the end result is false. If check succeeds (e.g. critter is within perception range), another check is made if there is any blocking tile between two critters (which includes stuff like windows, large bushes, barrels, etc.) and if there is - check still fails. You can override “within perception” check by returning 0 or 1, OR, as a convenience, you can also override blocking check after the perception check by returning 2 instead. In this case you should add “line of sight” check inside your hook script, otherwise critters will detect you through walls.

This is fired after the default calculation is made.

Critter arg1 - Watcher object
Obj     arg2 - Target object
int     arg3 - Result of vanilla function: 1 - within perception range, 0 - otherwise
int     arg4 - Type of hook: 1 - when being called from obj_can_see_obj script function, 2 when being called from obj_can_hear_obj script function (need to set ObjCanHearObjFix=1 in ddraw.ini), 0 for all other cases

int     ret1 - overrides the returned result of the function: 0 - not in range (can't see), 1 - in range (will see if not blocked), 2 - forced detection (will see regardless, only used in obj_can_see_obj scripting function which is called by every critter in the game)