diff --git a/assets/js/search-data.json b/assets/js/search-data.json index 0eaeaadf..803f8be3 100644 --- a/assets/js/search-data.json +++ b/assets/js/search-data.json @@ -316,7 +316,7 @@ },"45": { "doc": "Hook types", "title": "Hook types", - "content": ". | AdjustFID | AdjustPoison | AdjustRads | AfterHitRoll | AmmoCost | BarterPrice | BestWeapon | BuildSfxWeapon | CalcAPCost | CanUseWeapon | . ", + "content": ". | AdjustFID | AdjustPoison | AdjustRads | AfterHitRoll | AmmoCost | BarterPrice | BestWeapon | BuildSfxWeapon | CalcAPCost | CanUseWeapon | CarTravel | CombatDamage | CombatTurn | DeathAnim1 | DeathAnim2 | Deprecated hooks | DescriptionObj | Encounter | ExplosiveTimer | FindTarget | GameModeChange | InvenWield | InventoryMove | ItemDamage | KeyPress | MouseClick | MoveCost | OnDeath | OnExplosion | RemoveInvenObj | RestTimer | RollCheck | SetGlobalVar | SetLighting | Sneak | StdProcedure | StdProcedureEnd | Steal | SubCombatDamage | TargetObject | ToHit | UseAnimObj | UseObj | UseObjOn | UseSkill | UseSkillOn | WithinPerception | . ", "url": "/sfall/hook-types/", "relUrl": "/hook-types/" @@ -372,7 +372,7 @@ },"53": { "doc": "Hook types", "title": "BuildSfxWeapon", - "content": "HOOK_BUILDSFXWEAPON (hs_buildsfxweapon.int) . Runs before each weapon sound effect is played or put in the animation queue to determine the name of sound effect file based on the weapon, target and action being performed. int arg0 - weapon sound effect type: 0 - ready/reload, 1 - attack, 2 - out of ammo, 3 - flying (for projectile weapons), 4 - hit Item arg1 - the weapon being used int arg2 - attack type (see ATKTYPE_* constants) Obj arg3 - target of the attack (can be 0) String ret0 - the new sound file name to use, without extension (relative to \"sound\\sfx\" path) . ", + "content": "HOOK_BUILDSFXWEAPON (hs_buildsfxweapon.int) . Runs before each weapon sound effect is played or added to the animation queue to determine the name of the sound effect file based on the weapon, target, and action being performed. int arg0 - weapon sound effect type: 0 - ready/reload 1 - attack 2 - out of ammo 3 - flying (for projectiles from weapons) 4 - hit Item arg1 - the weapon being used int arg2 - attack type (see ATKTYPE_* constants) Obj arg3 - the target of the attack (can be 0) String ret0 - the filename of the new sound effect to use, without extension (relative to the sound\\sfx\\ directory) . ", "url": "/sfall/hook-types/#buildsfxweapon", "relUrl": "/hook-types/#buildsfxweapon" @@ -386,585 +386,844 @@ },"55": { "doc": "Hook types", "title": "CanUseWeapon", - "content": "HOOK_CANUSEWEAPON (hs_canuseweapon.int) . Run when the AI checks whether it can use a weapon. This mostly happens when NPCs try to find weapons in their inventory or on the map. Critter arg0 - the critter doing the check Item arg1 - the weapon being checked int arg2 - attack type (see ATKTYPE_* constants) int arg3 - original result of engine function: 1 - can use, 0 - cannot use int ret0 - overrides the result of engine function. Any non-zero value allows using the weapon ## CarTravel `HOOK_CARTRAVEL` (hs_cartravel.int) Runs continuously during world map travel by car. int arg0 - vanilla car speed (between 3 and 8 “steps”) int arg1 - vanilla fuel consumption (100 and below) . int ret0 - car speed override (pass -1 if you just want to override fuel consumption) int ret1 - 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 arg0 - The target Critter arg1 - The attacker int arg2 - The amount of damage to the target int arg3 - The amount of damage to the attacker int arg4 - The special effect flags for the target (use bwand DAM_* to check specific flags) int arg5 - The special effect flags for the attacker (use bwand DAM_* to check specific flags) Item arg6 - The weapon used in the attack int arg7 - The bodypart that was struck int arg8 - 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 arg9 - Number of bullets actually hit the target (1 for melee attacks) int arg10 - The amount of knockback to the target int arg11 - Attack Type (see ATKTYPE_* constants) mixed arg12 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data) . int ret0 - The damage to the target int ret1 - The damage to the attacker int ret2 - The special effect flags for the target int ret3 - The special effect flags for the attacker int ret4 - The amount of knockback to the target . ## CombatTurn `HOOK_COMBATURN` (hs_combatturn.int) Runs before and after each turn in combat (for both PC and NPC). int arg0 - 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) Critter arg1 - critter doing the turn int arg2 - 1 at the start/end of the player’s turn after loading a game saved in combat mode, 0 otherwise . int ret0 - 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. Does not run for critters in the knockdown/out state. int arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed) Critter arg1 - The attacker Critter arg2 - The target int arg3 - The amount of damage int arg4 - Unused, always -1. Use this if you are using the same procedure for HOOK_DEATHANIM1 and HOOK_DEATHANIM2 (since sfall 4.1/3.8.24) . int ret0 - 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 `HOOK_DEATHANIM1`, but performs no validation.<br> When using `critter_dmg` function, this script will also run. In that case weapon pid will be -1 and attacker will point to an object with `obj_art_fid == 0x20001F5`. Does not run for critters in the knockdown/out state. int arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed) Critter arg1 - The attacker Critter arg2 - The target int arg3 - The amount of damage int arg4 - The death anim id calculated by Fallout . int ret0 - 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, these hooks are not thoroughly supported in sfall, and may be removed in future versions.<br> If you want to check if some tile or path is blocked, use functions: `obj_blocking_tile`, `obj_blocking_line`, `path_find_to`.<br> If you want script to be called every time NPC moves by hex in combat, use `HOOK_MOVECOST` hook. Critter arg0 - the critter doing the moving int arg1 - the tile number being checked int arg2 - the elevation being checked int arg3 - 1 if the hex would normally be blocking . Obj ret0 - 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 the description of an object. You can override the description text. An example usage would be to add an additional description to the item based on player's stats/skills. Does not run if the script of the object overrides the description. __NOTE:__ Returning a pointer to the new text received from the `get_string_pointer` function is still valid, but the method is DEPRECATED and is left for backward compatibility only. Obj arg0 - the object . String ret0 - the new description text to use . ## Encounter `HOOK_ENCOUNTER` (hs_encounter.int) Runs whenever a random encounter occurs (except the Horrigan meeting and scripted encounters), or when the player enters a local map from the world map. You can override the map for loading or the encounter. int arg0 - event type: 0 - when a random encounter occurs, 1 - when the player enters from the world map int arg1 - the map ID that the encounter will load (see MAPS.h or Maps.txt) int arg2 - 1 when the encounter occurs is a special encounter, 0 otherwise int arg3 - encounter table number, or -1 if not an encounter int arg4 - encounter index in the table, or -1 if not an encounter . int ret0 - overrides the map ID, or pass -1 for event type 0 to cancel the encounter and continue traveling int ret1 - pass 1 to cancel the encounter and load the specified map from the ret0 (only for event type 0) . ## ExplosiveTimer `HOOK_EXPLOSIVETIMER` (hs_explosivetimer.int) Runs after setting the explosive timer. You can override the result. int arg0 - the time in ticks set in the timer Obj arg1 - the explosive object int arg2 - the result of engine calculation of whether the timer was set successfully: 1 - failure, 2 - success (similar to ROLL_* in Condtion.h) . int ret0 - overrides the time of the timer (maximum 18000 ticks) int ret1 - 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.<br> This hook replaces that sorting function, allowing you to sort the targets in some arbitrary way. 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, but this is fixed in sfall 4.2.3/3.8.23. Use `set_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 or pass -1 to skip the return value. __NOTE:__ The engine can choose targets by the following criteria: 1) The nearest enemy to the attacker. 2) The enemy that attacked the attacker. 3) The enemy that attacked an NPC from the same team as the attacker. 4) The enemy that is attacked by an NPC from the same team as the attacker. Critter arg0 - The attacker Critter arg1 - A possible target Critter arg2 - A possible target Critter arg3 - A possible target Critter arg4 - A possible target . Critter ret0 - The first choice of target Critter ret1 - The second choice of target Critter ret2 - The third choice of target Critter ret3 - 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 arg0 - event type: 1 - when the player exits the game, 0 - otherwise int arg1 - the previous game mode . ## InvenWield `HOOK_INVENWIELD` (hs_invenwield.int) Runs before causing a critter or the player to wield/unwield an armor or a weapon (except when using the 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 arg0 - critter Item arg1 - item being wielded or unwielded (weapon/armor) int arg2 - slot (INVEN_TYPE_*) int arg3 - 1 when wielding, 0 when unwielding int arg4 - 1 when removing an equipped item from inventory, 0 otherwise . int ret0 - 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 arg0 - 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 arg1 - Item being moved Item arg2 - Item being replaced, weapon being reloaded, or container being filled (can be 0) . int ret0 - Override setting (-1 - use engine handler, any other value - prevent relocation of item/reloading weapon/picking up item) . Notes for the event of dropping items on the ground: - the event is called for each item when dropping multiple items from the stack - for ammo type items, the number of dropped ammo in a pack can be found by using the `get_weapon_ammo_count` function - for the `PID_BOTTLE_CAPS` item, the event is called only once, and the number of dropped units can be found from the value of the `OBJ_DATA_CUR_CHARGES` object field (or with the `get_weapon_ammo_count` function) ## ItemDamage `HOOK_ITEMDAMAGE` (hs_itemdamage.int) Runs when retrieving the damage rating of the player's used weapon. (Which may be their fists.) . int arg0 - The default min damage int arg1 - The default max damage Item arg2 - The weapon used (0 if unarmed) Critter arg3 - The critter doing the attacking int arg4 - The type of attack int arg5 - non-zero if this is an attack using a melee weapon . int ret0 - Either the damage to be used, if ret1 isn’t given, or the new minimum damage if it is int ret1 - The new maximum damage . ## KeyPress `HOOK_KEYPRESS` (hs_keypress.int) Runs once every time when any key was pressed or released. * DX codes: see **dik.h** header or https://kippykip.com/b3ddocs/commands/scancodes.htm * [VK codes](http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx) __NOTE:__ If you want to override a key, the new key DX scancode should be the same for both pressed and released events. int arg0 - event type: 1 - pressed, 0 - released int arg1 - key DX scancode int arg2 - key VK code (very similar to ASCII codes) . int ret0 - 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 released. int arg0 - event type: 1 - pressed, 0 - released int arg1 - button number (0 - left, 1 - right, up to 7) . ## MoveCost `HOOK_MOVECOST` (hs_movecost.int) Runs when calculating the AP cost of movement. Critter arg0 - the critter doing the moving int arg1 - the number of hexes being moved int arg2 - the original AP cost . int ret0 - 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 arg0 - 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 arg0 - event type: 1 - when checking objects within the explosion radius without causing damage (e.g. the player drops an active explosive), 0 - otherwise Critter arg1 - the attacker int arg2 - the tile on which the explosion occurs int arg3 - checked tile within the explosion radius Obj arg4 - first found object on the checked tile as an additional target Critter arg5 - the target critter, may be 0 or equal to the attacker int arg6 - 1 when using throwing weapons (e.g. grenades), 0 otherwise . int ret0 - 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 arg0 - the owner that the object is being removed from Item arg1 - the item that is being removed int arg2 - the number of items to remove int arg3 - The reason the object is being removed (see RMOBJ_* constants) Obj arg4 - The destination object when the item is moved to another object, 0 otherwise . ## RestTimer `HOOK_RESTTIMER` (hs_resttimer.int) Runs continuously while the player is resting (using pipboy alarm clock). int arg0 - the game time in ticks int arg1 - event type: 1 - when the resting ends normally, -1 - when pressing ESC to cancel the timer, 0 - otherwise int arg2 - the hour part of the length of resting time int arg3 - the minute part of the length of resting time . int ret0 - pass 1 to interrupt the resting, pass 0 to continue the rest if it was interrupted by pressing ESC key . ## RollCheck `HOOK_ROLLCHECK` (hs_rollcheck.int) Runs when a game event performs a random roll to check the chance of success or failure. int arg0 - event type: 1 - checks the chance of an attack hitting the target 2 - checks the chance of a bullet from a burst hitting the target (for burst attacks) 3 - checks the chance when using skills (not listed below) 4 - check the chance of using Repair skill 5 - check the chance of using Doctor skill 6 - check the chance of using Steal skill for the thief (usually the player) 7 - the second Steal skill chance check for the target to catch the thief, in which the target’s failure is the thief’s success result int arg1 - the value of roll result (see ROLL_* constants), which is calculated as: for ROLL_CRITICAL_SUCCESS: random(1, 100) <= (random_chance / 10) + bonus for ROLL_CRITICAL_FAILURE: random(1, 100) <= -random_chance / 10 int arg2 - the chance value int arg3 - the bonus value, used when checking critical success int arg4 - random chance (calculated as: chance - random(1, 100)), where a negative value is a failure check (ROLL_FAILURE) . int ret0 - overrides the roll result . ## SetGlobalVar `HOOK_SETGLOBALVAR` (hs_setglobalvar.int) Runs when setting the value of a global variable. int arg0 - the index number of the global variable being set int arg1 - the set value of the global variable . int ret0 - 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 arg0 - the object being set, or -1 when setting the light level for a map int arg1 - the light intensity int arg2 - the light radius, or -1 when setting the light level for a map . int ret0 - overrides the light intensity. Intensity range is from 0 to 65536 int ret1 - 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 arg0 - Sneak check result: 1 - success, 0 - failure int arg1 - the duration in ticks for the current Sneak check (time depends on Sneak skill level) Critter arg2 - the critter (usually dude_obj) . int ret0 - overrides the result of the Sneak check int ret1 - overrides the duration time for the current result . ## StdProcedure `HOOK_STDPROCEDURE` (hs_stdprocedure.int) Runs before Fallout executes a standard procedure (handler) in any script of any object. NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures. int arg0 - the number of the standard script handler (see *_proc in define.h) Obj arg1 - the object that owns this handler (self_obj) Obj arg2 - the object that called this handler (source_obj, can be 0) int arg3 - always 0 (1 for _END version) Obj arg4 - the object that is acted upon by this handler (target_obj, can be 0) int arg5 - the parameter of this call (fixed_param), useful for combat_proc . int ret0 - pass -1 to cancel the execution of the handler . ## StdProcedureEnd `HOOK_STDPROCEDURE_END` (hs_stdprocedure.int) Runs after Fallout executes a standard procedure (handler) in any script of any object. NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures. int arg0 - the number of the standard script handler (see *_proc in define.h) Obj arg1 - the object that owns this handler (self_obj) Obj arg2 - the object that called this handler (source_obj, can be 0) int arg3 - always 1 (procedure end) Obj arg4 - the object that is acted upon by this handler (target_obj, can be 0) int arg5 - the parameter of this call (fixed_param), useful for combat_proc . ## 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):<br> `display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg3 * 2), obj_name(arg2)));` . Critter arg0 - Thief Obj arg1 - The target Item arg2 - The item being stolen/planted int arg3 - 0 when stealing, 1 when planting int arg4 - quantity of the item being stolen/planted . int ret0 - overrides hard-coded handler (2 - force fail without closing window, 1 - force success, 0 - force fail, -1 - use engine handler) int ret1 - overrides experience points gained for stealing this item (must be greater than or equal to 0) . ## 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 arg0 - the attacker Critter arg1 - the target Item arg2 - the weapon used in the attack int arg3 - attack type (see ATKTYPE_* constants) int arg4 - number of bullets actually hit the target (1 for melee attacks) int arg5 - target’s Damage Resistance (DR) value (affected by critical hit effects, perks, traits, and special unarmed attacks) int arg6 - target’s Damage Threshold (DT) value (affected by critical hit effects, perks, traits, and special unarmed attacks) int arg7 - bonus ranged damage from the perk int arg8 - 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 arg9 - combat difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it’s always 100) int arg10 - the calculated amount of damage (usually 0, required when using multiple hook scripts to calculate damage and using the set_sfall_arg function) mixed arg11 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data) . int ret0 - the returned amount of damage . ## TargetObject `HOOK_TARGETOBJECT` (hs_targetobject.int) Runs when the targeting cursor hovers over an object, or when the player tries to attack the target object. You can override the target object or prevent the player from attacking the chosen target. int arg0 - event type: 0 - when the targeting cursor hovers over the object, 1 - when trying to attack the target object int arg1 - 1 when the target object is valid to attack, 0 otherwise Obj arg2 - the target object . mixed ret0 - overrides the target object, or pass -1 to prevent the player from attacking the object . ## ToHit `HOOK_TOHIT` (hs_tohit.int) Runs when Fallout is calculating the chances of an attack striking a target.<br> Runs after the hit chance is fully calculated normally, including applying the 95% cap. int arg0 - The hit chance (capped) Critter arg1 - The attacker Critter arg2 - The target of the attack int arg3 - The targeted bodypart int arg4 - Source tile (may differ from attacker’s tile, when AI is considering potential fire position) int arg5 - Attack Type (see ATKTYPE_* constants) int arg6 - Ranged flag. 1 if the hit chance calculation takes into account the distance to the target. This does not mean the attack is a ranged attack int arg7 - The raw hit chance before applying the cap . int ret0 - The new hit chance. The value is limited to the range of -99 to 999 . ## 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 arg0 - the critter that uses an object (usually dude_obj) Obj arg1 - the object being used int arg2 - the animation code being used (see ANIM_* in Animcomd.h) . int ret0 - 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 arg0 - The user Obj arg1 - The object used . int ret0 - 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) 1. 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. 1. 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 arg0 - The target Critter arg1 - The user int arg2 - The object used . int ret0 - 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. Does not run if the script of the object calls `script_overrides` for using the skill. Critter arg0 - The user critter Obj arg1 - The target object int arg2 - skill being used int arg3 - skill bonus from items such as first aid kits . int ret0 - overrides hard-coded handler (-1 - use engine handler, any other value - override; if it is 0, there will be a 10% chance of removing the used medical item) . ## 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 arg0 - the user critter (usually dude_obj) Obj arg1 - the target object/critter int arg2 - skill being used . int ret0 - a new critter to override the user critter. Pass -1 to cancel the skill use, pass 0 to skip this return value int ret1 - pass 1 to allow the skill to be used in combat (only for dude_obj or critter being controlled by the player) . ## WithinPerception `HOOK_WITHINPRECEPTION` (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.<br> 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.<br> 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 arg0 - Watcher object Obj arg1 - Target object int arg2 - Result of vanilla function: 1 - within perception range, 0 - otherwise int arg3 - 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) 3 - when AI determines whether it sees a potential target when selecting attack targets 0 - all other cases . int ret0 - 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 script function which is called by every critter in the game) ``` . ", + "content": "HOOK_CANUSEWEAPON (hs_canuseweapon.int) . Run when the AI checks whether it can use a weapon. This mostly happens when NPCs try to find weapons in their inventory or on the map. Critter arg0 - the critter doing the check Item arg1 - the weapon being checked int arg2 - attack type (see ATKTYPE_* constants) int arg3 - original result of engine function: 1 - can use, 0 - cannot use int ret0 - overrides the result of engine function. Any non-zero value allows using the weapon . ", "url": "/sfall/hook-types/#canuseweapon", "relUrl": "/hook-types/#canuseweapon" },"56": { + "doc": "Hook types", + "title": "CarTravel", + "content": "HOOK_CARTRAVEL (hs_cartravel.int) . Runs continuously during world map travel by car. int arg0 - vanilla car speed (between 3 and 8 \"steps\") int arg1 - vanilla fuel consumption (100 and below) int ret0 - car speed override (pass -1 if you just want to override fuel consumption) int ret1 - fuel consumption override . ", + "url": "/sfall/hook-types/#cartravel", + + "relUrl": "/hook-types/#cartravel" + },"57": { + "doc": "Hook types", + "title": "CombatDamage", + "content": "HOOK_COMBATDAMAGE (hs_subcombatdmg.int) . Runs when: . | 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. | 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 arg0 - The target Critter arg1 - The attacker int arg2 - The amount of damage to the target int arg3 - The amount of damage to the attacker int arg4 - The special effect flags for the target (use bwand DAM_* to check specific flags) int arg5 - The special effect flags for the attacker (use bwand DAM_* to check specific flags) Item arg6 - The weapon used in the attack int arg7 - The bodypart that was struck int arg8 - 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 arg9 - Number of bullets actually hit the target (1 for melee attacks) int arg10 - The amount of knockback to the target int arg11 - Attack Type (see ATKTYPE_* constants) mixed arg12 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data) int ret0 - The damage to the target int ret1 - The damage to the attacker int ret2 - The special effect flags for the target int ret3 - The special effect flags for the attacker int ret4 - The amount of knockback to the target . ", + "url": "/sfall/hook-types/#combatdamage", + + "relUrl": "/hook-types/#combatdamage" + },"58": { + "doc": "Hook types", + "title": "CombatTurn", + "content": "HOOK_COMBATURN (hs_combatturn.int) . Runs before and after each turn in combat (for both PC and NPC). int arg0 - 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) Critter arg1 - critter doing the turn int arg2 - 1 at the start/end of the player's turn after loading a game saved in combat mode, 0 otherwise int ret0 - pass 1 at the start of turn to skip the turn, pass -1 at the end of turn to force end of combat . ", + "url": "/sfall/hook-types/#combatturn", + + "relUrl": "/hook-types/#combatturn" + },"59": { + "doc": "Hook types", + "title": "DeathAnim1", + "content": "HOOK_DEATHANIM1 (hs_deathanim1.int) . Runs before Fallout tries to calculate the death animation. Lets you switch out which weapon Fallout sees. Does not run for critters in the knockdown/out state. int arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed) Critter arg1 - The attacker Critter arg2 - The target int arg3 - The amount of damage int arg4 - Unused, always -1. Use this if you are using the same procedure for HOOK_DEATHANIM1 and HOOK_DEATHANIM2 (since sfall 4.1/3.8.24) int ret0 - The pid of an object to override the attacking weapon with . ", + "url": "/sfall/hook-types/#deathanim1", + + "relUrl": "/hook-types/#deathanim1" + },"60": { + "doc": "Hook types", + "title": "DeathAnim2", + "content": "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 HOOK_DEATHANIM1, but performs no validation. When using critter_dmg function, this script will also run. In that case weapon pid will be -1 and attacker will point to an object with obj_art_fid == 0x20001F5. Does not run for critters in the knockdown/out state. int arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed) Critter arg1 - The attacker Critter arg2 - The target int arg3 - The amount of damage int arg4 - The death anim id calculated by Fallout int ret0 - The death anim id to override with . ", + "url": "/sfall/hook-types/#deathanim2", + + "relUrl": "/hook-types/#deathanim2" + },"61": { + "doc": "Hook types", + "title": "Deprecated hooks", + "content": ". | 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, these hooks are not thoroughly supported in sfall, and 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 HOOK_MOVECOST hook. Critter arg0 - the critter doing the moving int arg1 - the tile number being checked int arg2 - the elevation being checked int arg3 - 1 if the hex would normally be blocking Obj ret0 - 0 if the hex doesn't block, or any sort of object pointer if it does . ", + "url": "/sfall/hook-types/#deprecated-hooks", + + "relUrl": "/hook-types/#deprecated-hooks" + },"62": { + "doc": "Hook types", + "title": "DescriptionObj", + "content": "HOOK_DESCRIPTIONOBJ (hs_descriptionobj.int) . Runs when using the examine action icon to display the description of an object. You can override the description text. An example usage would be to add an additional description to the item based on player’s stats/skills. Does not run if the script of the object overrides the description. NOTE: Returning a pointer to the new text received from the get_string_pointer function is still valid, but the method is DEPRECATED and is left for backward compatibility only. Obj arg0 - the object String ret0 - the new description text to use . ", + "url": "/sfall/hook-types/#descriptionobj", + + "relUrl": "/hook-types/#descriptionobj" + },"63": { + "doc": "Hook types", + "title": "Encounter", + "content": "HOOK_ENCOUNTER (hs_encounter.int) . Runs whenever a random encounter occurs (except the Horrigan meeting and scripted encounters), or when the player enters a local map from the world map. You can override the map for loading or the encounter. int arg0 - event type: 0 - when a random encounter occurs, 1 - when the player enters from the world map int arg1 - the map ID that the encounter will load (see MAPS.h or Maps.txt) int arg2 - 1 when the encounter occurs is a special encounter, 0 otherwise int arg3 - encounter table number, or -1 if not an encounter int arg4 - encounter index in the table, or -1 if not an encounter int ret0 - overrides the map ID, or pass -1 for event type 0 to cancel the encounter and continue traveling int ret1 - pass 1 to cancel the encounter and load the specified map from the ret0 (only for event type 0) . ", + "url": "/sfall/hook-types/#encounter", + + "relUrl": "/hook-types/#encounter" + },"64": { + "doc": "Hook types", + "title": "ExplosiveTimer", + "content": "HOOK_EXPLOSIVETIMER (hs_explosivetimer.int) . Runs after setting the explosive timer. You can override the result. int arg0 - the time in ticks set in the timer Obj arg1 - the explosive object int arg2 - the result of engine calculation of whether the timer was set successfully: 1 - failure, 2 - success (similar to ROLL_* in Condtion.h) int ret0 - overrides the time of the timer (maximum 18000 ticks) int ret1 - overrides the result of engine calculation: 0/1 - failure, 2/3 - success (similar to ROLL_*), any other value - use engine handler . ", + "url": "/sfall/hook-types/#explosivetimer", + + "relUrl": "/hook-types/#explosivetimer" + },"65": { + "doc": "Hook types", + "title": "FindTarget", + "content": "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. 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, but this is fixed in sfall 4.2.3/3.8.23. Use set_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 or pass -1 to skip the return value. NOTE: The engine can choose targets by the following criteria: 1) The nearest enemy to the attacker. 2) The enemy that attacked the attacker. 3) The enemy that attacked an NPC from the same team as the attacker. 4) The enemy that is attacked by an NPC from the same team as the attacker. Critter arg0 - The attacker Critter arg1 - A possible target Critter arg2 - A possible target Critter arg3 - A possible target Critter arg4 - A possible target Critter ret0 - The first choice of target Critter ret1 - The second choice of target Critter ret2 - The third choice of target Critter ret3 - The fourth choice of target . ", + "url": "/sfall/hook-types/#findtarget", + + "relUrl": "/hook-types/#findtarget" + },"66": { + "doc": "Hook types", + "title": "GameModeChange", + "content": "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 arg0 - event type: 1 - when the player exits the game, 0 - otherwise int arg1 - the previous game mode . ", + "url": "/sfall/hook-types/#gamemodechange", + + "relUrl": "/hook-types/#gamemodechange" + },"67": { + "doc": "Hook types", + "title": "InvenWield", + "content": "HOOK_INVENWIELD (hs_invenwield.int) . Runs before causing a critter or the player to wield/unwield an armor or a weapon (except when using the 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 arg0 - critter Item arg1 - item being wielded or unwielded (weapon/armor) int arg2 - slot (INVEN_TYPE_*) int arg3 - 1 when wielding, 0 when unwielding int arg4 - 1 when removing an equipped item from inventory, 0 otherwise int ret0 - overrides hard-coded handler (-1 - use engine handler, any other value - override) - NOT RECOMMENDED . ", + "url": "/sfall/hook-types/#invenwield", + + "relUrl": "/hook-types/#invenwield" + },"68": { + "doc": "Hook types", + "title": "InventoryMove", + "content": "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 arg0 - 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 arg1 - Item being moved Item arg2 - Item being replaced, weapon being reloaded, or container being filled (can be 0) int ret0 - Override setting (-1 - use engine handler, any other value - prevent relocation of item/reloading weapon/picking up item) . Notes for the event of dropping items on the ground: . | the event is called for each item when dropping multiple items from the stack | for ammo type items, the number of dropped ammo in a pack can be found by using the get_weapon_ammo_count function | for the PID_BOTTLE_CAPS item, the event is called only once, and the number of dropped units can be found from the value of the OBJ_DATA_CUR_CHARGES object field (or with the get_weapon_ammo_count function) | . ", + "url": "/sfall/hook-types/#inventorymove", + + "relUrl": "/hook-types/#inventorymove" + },"69": { + "doc": "Hook types", + "title": "ItemDamage", + "content": "HOOK_ITEMDAMAGE (hs_itemdamage.int) . Runs when retrieving the damage rating of the player’s used weapon. (Which may be their fists.) . int arg0 - The default min damage int arg1 - The default max damage Item arg2 - The weapon used (0 if unarmed) Critter arg3 - The critter doing the attacking int arg4 - The type of attack int arg5 - non-zero if this is an attack using a melee weapon int ret0 - Either the damage to be used, if ret1 isn't given, or the new minimum damage if it is int ret1 - The new maximum damage . ", + "url": "/sfall/hook-types/#itemdamage", + + "relUrl": "/hook-types/#itemdamage" + },"70": { + "doc": "Hook types", + "title": "KeyPress", + "content": "HOOK_KEYPRESS (hs_keypress.int) . Runs once every time when any key was pressed or released. | DX codes: see dik.h header or https://kippykip.com/b3ddocs/commands/scancodes.htm | VK codes | . NOTE: If you want to override a key, the new key DX scancode should be the same for both pressed and released events. int arg0 - event type: 1 - pressed, 0 - released int arg1 - key DX scancode int arg2 - key VK code (very similar to ASCII codes) int ret0 - overrides the pressed key (a new key DX scancode or 0 for no override) . ", + "url": "/sfall/hook-types/#keypress", + + "relUrl": "/hook-types/#keypress" + },"71": { + "doc": "Hook types", + "title": "MouseClick", + "content": "HOOK_MOUSECLICK (hs_mouseclick.int) . Runs once every time when a mouse button was pressed or released. int arg0 - event type: 1 - pressed, 0 - released int arg1 - button number (0 - left, 1 - right, up to 7) . ", + "url": "/sfall/hook-types/#mouseclick", + + "relUrl": "/hook-types/#mouseclick" + },"72": { + "doc": "Hook types", + "title": "MoveCost", + "content": "HOOK_MOVECOST (hs_movecost.int) . Runs when calculating the AP cost of movement. Critter arg0 - the critter doing the moving int arg1 - the number of hexes being moved int arg2 - the original AP cost int ret0 - the new AP cost . ", + "url": "/sfall/hook-types/#movecost", + + "relUrl": "/hook-types/#movecost" + },"73": { + "doc": "Hook types", + "title": "OnDeath", + "content": "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 arg0 - The critter that just died . ", + "url": "/sfall/hook-types/#ondeath", + + "relUrl": "/hook-types/#ondeath" + },"74": { + "doc": "Hook types", + "title": "OnExplosion", + "content": "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 arg0 - event type: 1 - when checking objects within the explosion radius without causing damage (e.g. the player drops an active explosive), 0 - otherwise Critter arg1 - the attacker int arg2 - the tile on which the explosion occurs int arg3 - checked tile within the explosion radius Obj arg4 - first found object on the checked tile as an additional target Critter arg5 - the target critter, may be 0 or equal to the attacker int arg6 - 1 when using throwing weapons (e.g. grenades), 0 otherwise int ret0 - overrides the found object on the checked tile, pass 0 to skip the object . ", + "url": "/sfall/hook-types/#onexplosion", + + "relUrl": "/hook-types/#onexplosion" + },"75": { + "doc": "Hook types", + "title": "RemoveInvenObj", + "content": "HOOK_REMOVEINVENOBJ (hs_removeinvenobj.int) . Runs when an object is removed from a container or critter’s inventory for any reason. Obj arg0 - the owner that the object is being removed from Item arg1 - the item that is being removed int arg2 - the number of items to remove int arg3 - The reason the object is being removed (see RMOBJ_* constants) Obj arg4 - The destination object when the item is moved to another object, 0 otherwise . ", + "url": "/sfall/hook-types/#removeinvenobj", + + "relUrl": "/hook-types/#removeinvenobj" + },"76": { + "doc": "Hook types", + "title": "RestTimer", + "content": "HOOK_RESTTIMER (hs_resttimer.int) . Runs continuously while the player is resting (using pipboy alarm clock). int arg0 - the game time in ticks int arg1 - event type: 1 - when the resting ends normally, -1 - when pressing ESC to cancel the timer, 0 - otherwise int arg2 - the hour part of the length of resting time int arg3 - the minute part of the length of resting time int ret0 - pass 1 to interrupt the resting, pass 0 to continue the rest if it was interrupted by pressing ESC key . ", + "url": "/sfall/hook-types/#resttimer", + + "relUrl": "/hook-types/#resttimer" + },"77": { + "doc": "Hook types", + "title": "RollCheck", + "content": "HOOK_ROLLCHECK (hs_rollcheck.int) . Runs when a game event performs a random roll to check the chance of success or failure. int arg0 - event type: 1 - checks the chance of an attack hitting the target 2 - checks the chance of a bullet from a burst hitting the target (for burst attacks) 3 - checks the chance when using skills (not listed below) 4 - check the chance of using Repair skill 5 - check the chance of using Doctor skill 6 - check the chance of using Steal skill for the thief (usually the player) 7 - the second Steal skill chance check for the target to catch the thief, in which the target's failure is the thief's success result int arg1 - the value of roll result (see ROLL_* constants), which is calculated as: for ROLL_CRITICAL_SUCCESS: random(1, 100) <= (random_chance / 10) + bonus for ROLL_CRITICAL_FAILURE: random(1, 100) <= -random_chance / 10 int arg2 - the chance value int arg3 - the bonus value, used when checking critical success int arg4 - random chance (calculated as: chance - random(1, 100)), where a negative value is a failure check (ROLL_FAILURE) int ret0 - overrides the roll result . ", + "url": "/sfall/hook-types/#rollcheck", + + "relUrl": "/hook-types/#rollcheck" + },"78": { + "doc": "Hook types", + "title": "SetGlobalVar", + "content": "HOOK_SETGLOBALVAR (hs_setglobalvar.int) . Runs when setting the value of a global variable. int arg0 - the index number of the global variable being set int arg1 - the set value of the global variable int ret0 - overrides the value of the global variable . ", + "url": "/sfall/hook-types/#setglobalvar", + + "relUrl": "/hook-types/#setglobalvar" + },"79": { + "doc": "Hook types", + "title": "SetLighting", + "content": "HOOK_SETLIGHTING (hs_setlighting.int) . Runs before setting the light level for an object or a map. You can override the result. Obj arg0 - the object being set, or -1 when setting the light level for a map int arg1 - the light intensity int arg2 - the light radius, or -1 when setting the light level for a map int ret0 - overrides the light intensity. Intensity range is from 0 to 65536 int ret1 - overrides the light radius. Radius range is from 0 to 8 (works only for the object) . ", + "url": "/sfall/hook-types/#setlighting", + + "relUrl": "/hook-types/#setlighting" + },"80": { + "doc": "Hook types", + "title": "Sneak", + "content": "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 arg0 - Sneak check result: 1 - success, 0 - failure int arg1 - the duration in ticks for the current Sneak check (time depends on Sneak skill level) Critter arg2 - the critter (usually dude_obj) int ret0 - overrides the result of the Sneak check int ret1 - overrides the duration time for the current result . ", + "url": "/sfall/hook-types/#sneak", + + "relUrl": "/hook-types/#sneak" + },"81": { + "doc": "Hook types", + "title": "StdProcedure", + "content": "HOOK_STDPROCEDURE (hs_stdprocedure.int) . Runs before Fallout executes a standard procedure (handler) in any script of any object. NOTE: this hook will not be executed for start, critter_p_proc, timed_event_p_proc, and map_update_p_proc procedures. int arg0 - the number of the standard script handler (see *_proc in define.h) Obj arg1 - the object that owns this handler (self_obj) Obj arg2 - the object that called this handler (source_obj, can be 0) int arg3 - always 0 (1 for _END version) Obj arg4 - the object that is acted upon by this handler (target_obj, can be 0) int arg5 - the parameter of this call (fixed_param), useful for combat_proc int ret0 - pass -1 to cancel the execution of the handler . ", + "url": "/sfall/hook-types/#stdprocedure", + + "relUrl": "/hook-types/#stdprocedure" + },"82": { + "doc": "Hook types", + "title": "StdProcedureEnd", + "content": "HOOK_STDPROCEDURE_END (hs_stdprocedure.int) . Runs after Fallout executes a standard procedure (handler) in any script of any object. NOTE: this hook will not be executed for start, critter_p_proc, timed_event_p_proc, and map_update_p_proc procedures. int arg0 - the number of the standard script handler (see *_proc in define.h) Obj arg1 - the object that owns this handler (self_obj) Obj arg2 - the object that called this handler (source_obj, can be 0) int arg3 - always 1 (procedure end) Obj arg4 - the object that is acted upon by this handler (target_obj, can be 0) int arg5 - the parameter of this call (fixed_param), useful for combat_proc . ", + "url": "/sfall/hook-types/#stdprocedureend", + + "relUrl": "/hook-types/#stdprocedureend" + },"83": { + "doc": "Hook types", + "title": "Steal", + "content": "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) + arg3 * 2), obj_name(arg2))); . Critter arg0 - Thief Obj arg1 - The target Item arg2 - The item being stolen/planted int arg3 - 0 when stealing, 1 when planting int arg4 - quantity of the item being stolen/planted int ret0 - overrides hard-coded handler (2 - force fail without closing window, 1 - force success, 0 - force fail, -1 - use engine handler) int ret1 - overrides experience points gained for stealing this item (must be greater than or equal to 0) . ", + "url": "/sfall/hook-types/#steal", + + "relUrl": "/hook-types/#steal" + },"84": { + "doc": "Hook types", + "title": "SubCombatDamage", + "content": "HOOK_SUBCOMBATDAMAGE (hs_subcombatdamage.int) . This hook overrides the vanilla damage calculation formula. Runs when: . | Before the game calculates how much damage each target will get. This includes primary target as well as all extras (explosions and bursts). | 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 arg0 - the attacker Critter arg1 - the target Item arg2 - the weapon used in the attack int arg3 - attack type (see ATKTYPE_* constants) int arg4 - number of bullets actually hit the target (1 for melee attacks) int arg5 - target's Damage Resistance (DR) value (affected by critical hit effects, perks, traits, and special unarmed attacks) int arg6 - target's Damage Threshold (DT) value (affected by critical hit effects, perks, traits, and special unarmed attacks) int arg7 - bonus ranged damage from the perk int arg8 - 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 arg9 - combat difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it's always 100) int arg10 - the calculated amount of damage (usually 0, required when using multiple hook scripts to calculate damage and using the set_sfall_arg function) mixed arg11 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data) int ret0 - the returned amount of damage . ", + "url": "/sfall/hook-types/#subcombatdamage", + + "relUrl": "/hook-types/#subcombatdamage" + },"85": { + "doc": "Hook types", + "title": "TargetObject", + "content": "HOOK_TARGETOBJECT (hs_targetobject.int) . Runs when the targeting cursor hovers over an object, or when the player tries to attack the target object. You can override the target object or prevent the player from attacking the chosen target. int arg0 - event type: 0 - when the targeting cursor hovers over the object, 1 - when trying to attack the target object int arg1 - 1 when the target object is valid to attack, 0 otherwise Obj arg2 - the target object mixed ret0 - overrides the target object, or pass -1 to prevent the player from attacking the object . ", + "url": "/sfall/hook-types/#targetobject", + + "relUrl": "/hook-types/#targetobject" + },"86": { + "doc": "Hook types", + "title": "ToHit", + "content": "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 arg0 - The hit chance (capped) Critter arg1 - The attacker Critter arg2 - The target of the attack int arg3 - The targeted bodypart int arg4 - Source tile (may differ from attacker's tile, when AI is considering potential fire position) int arg5 - Attack Type (see ATKTYPE_* constants) int arg6 - Ranged flag. 1 if the hit chance calculation takes into account the distance to the target. This does not mean the attack is a ranged attack int arg7 - The raw hit chance before applying the cap int ret0 - The new hit chance. The value is limited to the range of -99 to 999 . ", + "url": "/sfall/hook-types/#tohit", + + "relUrl": "/hook-types/#tohit" + },"87": { + "doc": "Hook types", + "title": "UseAnimObj", + "content": "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 arg0 - the critter that uses an object (usually dude_obj) Obj arg1 - the object being used int arg2 - the animation code being used (see ANIM_* in Animcomd.h) int ret0 - overrides the animation code (pass -1 if you want to skip the animation) . ", + "url": "/sfall/hook-types/#useanimobj", + + "relUrl": "/hook-types/#useanimobj" + },"88": { + "doc": "Hook types", + "title": "UseObj", + "content": "HOOK_USEOBJ (hs_useobj.int) . Runs when: . | a critter uses an object from inventory which have “Use” action flag set or it’s an active flare or dynamite. | 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 arg0 - The user Obj arg1 - The object used int ret0 - overrides hard-coded handler and selects what should happen with the item (0 - place it back, 1 - remove it, -1 - use engine handler) . ", + "url": "/sfall/hook-types/#useobj", + + "relUrl": "/hook-types/#useobj" + },"89": { + "doc": "Hook types", + "title": "UseObjOn", + "content": "HOOK_USEOBJON (hs_useobjon.int) . Runs when: . | a critter uses an object on another critter. (Or themselves) | 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. | 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 arg0 - The target Critter arg1 - The user int arg2 - The object used int ret0 - overrides hard-coded handler and selects what should happen with the item (0 - place it back, 1 - remove it, -1 - use engine handler) . ", + "url": "/sfall/hook-types/#useobjon", + + "relUrl": "/hook-types/#useobjon" + },"90": { + "doc": "Hook types", + "title": "UseSkill", + "content": "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. Does not run if the script of the object calls script_overrides for using the skill. Critter arg0 - The user critter Obj arg1 - The target object int arg2 - skill being used int arg3 - skill bonus from items such as first aid kits int ret0 - overrides hard-coded handler (-1 - use engine handler, any other value - override; if it is 0, there will be a 10% chance of removing the used medical item) . ", + "url": "/sfall/hook-types/#useskill", + + "relUrl": "/hook-types/#useskill" + },"91": { + "doc": "Hook types", + "title": "UseSkillOn", + "content": "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 arg0 - the user critter (usually dude_obj) Obj arg1 - the target object/critter int arg2 - skill being used int ret0 - a new critter to override the user critter. Pass -1 to cancel the skill use, pass 0 to skip this return value int ret1 - pass 1 to allow the skill to be used in combat (only for dude_obj or critter being controlled by the player) . ", + "url": "/sfall/hook-types/#useskillon", + + "relUrl": "/hook-types/#useskillon" + },"92": { + "doc": "Hook types", + "title": "WithinPerception", + "content": "HOOK_WITHINPRECEPTION (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 arg0 - Watcher object Obj arg1 - Target object int arg2 - Result of vanilla function: 1 - within perception range, 0 - otherwise int arg3 - 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) 3 - when AI determines whether it sees a potential target when selecting attack targets 0 - all other cases int ret0 - 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 script function which is called by every critter in the game) . ", + "url": "/sfall/hook-types/#withinperception", + + "relUrl": "/hook-types/#withinperception" + },"93": { "doc": "Hooks", "title": "Hooks", "content": "Hook scripts are specially named scripts that are run by sfall at specific points to allow mods to override normally hardcoded behaviour in a more flexible way than sfall’s normal ini configuration. In addition to the bit of code it overrides, the script will be run once when first loaded and again at each player reload to allow for setup. Hook scripts have access to a set of arguments supplied to sfall, but aren’t required to use them all. They also return one or more values, but again they’re optional, and you only need to return a value if you want to override the default. See hook types and hook functions reference for details. ", "url": "/sfall/hooks/", "relUrl": "/hooks/" - },"57": { + },"94": { "doc": "Hooks", "title": "Hooks compatibility", "content": "To aid in mods compatibility, avoid using the predefined hs_<name>.int scripts. Instead it is recommended to use a normal global script combined with register_hook_proc or register_hook. Example setup for a hook-script based mod: . procedure tohit_hook_handler begin display_msg(\"Modifying hit_hook \" + get_sfall_arg); set_hit_chance_max(100); set_sfall_return(100); end procedure start begin if game_loaded then begin register_hook_proc(HOOK_TOHIT, tohit_hook_handler); end end . ", "url": "/sfall/hooks/#hooks-compatibility", "relUrl": "/hooks/#hooks-compatibility" - },"58": { + },"95": { "doc": "Home", "title": "sfall", "content": ". | Getting started | Questions and problems | . sfall is a set of engine modifications for the classic game Fallout 2 in the form of a DLL, which modifies executable in memory without changing anything in EXE file itself. Engine modifications include: . | Better support for modern operating systems | Externalizing many settings like starting map and game time, skills, perks, critical hit tables, books, etc. | Bug fixes | Many additional features for users, such as item highlight button, party member control, etc. | Extended scripting capabilities for modders (many new opcodes to control sfall features as well as previously unavailable vanilla engine functions) | . Note that this is documentation for sfall specifically, not Fallout scripting in general. For vanilla function reference, refer to the wiki. ", "url": "/sfall/#sfall", "relUrl": "/#sfall" - },"59": { + },"96": { "doc": "Home", "title": "Getting started", "content": "To get started with sfall, first familiarize yourself with new concepts: . | Global scripts and variables. | Arrays and lists. | Hooks. | Data types. | Object and script manipulation. | . Pay special attention to the best practices page. Also, take a look at SSLC features and optimization guide. Next, proceed to discover new functions. They are categorized, use the menu to find the one you need. If you can’t, check uncategorized functions list and sfall macros. Also, there’s search at the top of the page. ", "url": "/sfall/#getting-started", "relUrl": "/#getting-started" - },"60": { + },"97": { "doc": "Home", "title": "Questions and problems", "content": ". | Report bugs and suggest features on Github. | Ask questions and discuss on the forum. | . ", "url": "/sfall/#questions-and-problems", "relUrl": "/#questions-and-problems" - },"61": { + },"98": { "doc": "Home", "title": "Home", "content": " ", "url": "/sfall/", "relUrl": "/" - },"62": { + },"99": { "doc": "INI settings", "title": "INI settings", "content": " ", "url": "/sfall/ini-settings/", "relUrl": "/ini-settings/" - },"63": { + },"100": { "doc": "INI settings", "title": "Functions", "content": ". | get_ini_config | get_ini_config_db | get_ini_section | get_ini_sections | get_ini_setting | get_ini_string | modified_ini | set_ini_setting | . get_ini_config . sfall.h . array get_ini_config(string file) . Loads a given INI file and returns a permanent array (map) where keys are section names and values are permanent sub-arrays (maps) where keys and values are strings. | Searches the file in the regular file system, like with all other ini-related functions. | Subsequent calls for the same file will return the same array, unless it was disposed using free_array. | . get_ini_config_db . sfall.h . array get_ini_config_db(string file) . Works exactly like get_ini_config, except it searches the file in database (DAT) files. If not found, then it will try the regular file system. get_ini_section . sfall.h . array get_ini_section(string file, string sect) . Returns an associative array of keys and values for a given INI file and section. | If the INI file is not found, it returns an empty array. | NOTE: all keys and their values will be of String type. | . get_ini_sections . sfall.h . array get_ini_sections(string file) . Returns an array of names of all sections in a given INI file. | If the INI file is not found, it returns an empty array. | . get_ini_setting . int get_ini_setting(string setting) . Reads an integer value from an ini file in the Fallout directory. | It only takes a single argument; seperate the file name, section and key with a “|” character; e.g. myvar:=get_ini_setting(\"myini.ini|mysec|var1\") | If the file or key cannot be found or the setting argument is in an invalid format, it returns -1. | The file name is limited to 63 chars, including the extension. | The section name is limited to 32 characters. | It can also be used to get sfall settings by using ddraw.ini as the file name. | . get_ini_string . string get_ini_string(string setting) . Reads a string value from an ini file in the Fallout directory. | If the file or key cannot be found, it returns an empty string. | If the setting argument is in an invalid format, it returns -1 (integer). | . modified_ini . int modified_ini . Returns the value of ModifiedIni setting in [Main] section of the INI. set_ini_setting . sfall.h . void set_ini_setting(string setting, int/string value) . Writes an integer or a string value to an ini file in the Fallout directory. If the ini file does not exist, it will be created The setting argument works in the same way as in get_ini_setting, seperate the file name, section and key with a “|” character. Note: the file name is limited to 63 chars (including the extension), the section name is limited to 32 characters. ", "url": "/sfall/ini-settings/#functions", "relUrl": "/ini-settings/#functions" - },"64": { + },"101": { "doc": "Interface", "title": "Interface", "content": " ", "url": "/sfall/interface/", "relUrl": "/interface/" - },"65": { + },"102": { "doc": "Interface", "title": "Subcategories", "content": ". | Tags | Windows and images | Outline | Main interface | Inventory | Pip-Boy | Cursor | . ", "url": "/sfall/interface/#subcategories", "relUrl": "/interface/#subcategories" - },"66": { + },"103": { "doc": "Inventory", "title": "Inventory", "content": " ", "url": "/sfall/inventory/", "relUrl": "/inventory/" - },"67": { + },"104": { "doc": "Inventory", "title": "Functions", "content": ". | display_stats | inventory_redraw | . display_stats . sfall.h . void display_stats() . | Updates player’s stats in the inventory display window or on the character screen. | NOTE: works only when the interface window is opened | . inventory_redraw . sfall.h . void inventory_redraw(invSide) . Redraws inventory items list in the inventory/loot/barter screens. Argument invSide specifies which side needs to be redrawn: 0 - the player, 1 - target (container/NPC in loot/barter screens), -1 - both sides (same as without argument). ", "url": "/sfall/inventory/#functions", "relUrl": "/inventory/#functions" - },"68": { + },"105": { "doc": "Keyboard and mouse", "title": "Keyboard and mouse", "content": " ", "url": "/sfall/keyboard-and-mouse/", "relUrl": "/keyboard-and-mouse/" - },"69": { + },"106": { "doc": "Keyboard and mouse", "title": "Functions", "content": ". | get_mouse_buttons | get_mouse_x | get_mouse_y | key_pressed | tap_key | . get_mouse_buttons . int get_mouse_buttons() . Returns the number of the mouse button that is currently pressed (1 - left, 2 - right, 3 - left+right, 4 - middle, 0 otherwise). get_mouse_x . int get_mouse_x() . get_mouse_y . int get_mouse_y() . key_pressed . int key_pressed(int dxScancode) . tap_key . void tap_key(int dxScancode) . ", "url": "/sfall/keyboard-and-mouse/#functions", "relUrl": "/keyboard-and-mouse/#functions" - },"70": { + },"107": { "doc": "Knockback", "title": "Knockback", "content": "The type value in the weapon knockback functions can be 0 or 1. If 0, the value becomes an absolute distance that targets will be knocked back. If 1, the value is multiplied by the distance they would normally have been knocked back. Weapon knockback modifiers are applied in the order weapon -> attacker -> target, so a x2 weapon wielded by an abs 6 attacker hitting a /2 target will knock the target back 3 squares. The knockback functions will not override the stonewall perk or knockdowns resulting from criticals. knockback values set on weapons or critters are not saved, and must be reset each time the player reloads. ", "url": "/sfall/knockback/", "relUrl": "/knockback/" - },"71": { + },"108": { "doc": "Knockback", "title": "Functions", "content": ". | remove_attacker_knockback | remove_target_knockback | remove_weapon_knockback | set_attacker_knockback | set_target_knockback | set_weapon_knockback | . remove_attacker_knockback . void remove_attacker_knockback(CritterPtr) . remove_target_knockback . void remove_target_knockback(CritterPtr) . remove_weapon_knockback . void remove_weapon_knockback(WeaponPtr) . set_attacker_knockback . void set_attacker_knockback(CritterPtr, int type, float value) . set_target_knockback . void set_target_knockback(CritterPtr, int type, float value) . set_weapon_knockback . void set_weapon_knockback(WeaponPtr, int type, float value) . ", "url": "/sfall/knockback/#functions", "relUrl": "/knockback/#functions" - },"72": { + },"109": { "doc": "Lists", "title": "Lists", "content": "The list_xxx functions can be used to loop over all items on a map. list_begin takes an argument telling sfall what you want to list (defined in sfall.h). It returns a list pointer, which you iterate through with list_next. Finally, when you’ve finished with the list use list_end on it. Not calling list_end will result in a memory leak. Alternatively, use list_as_array to get the whole list at once as a temp array variable, which can be looped over using len_array and which you don’t need to remember to free afterwards. ", "url": "/sfall/lists/", "relUrl": "/lists/" - },"73": { + },"110": { "doc": "Lists", "title": "Functions", "content": ". | list_as_array | list_begin | list_end | list_next | party_member_list | . list_as_array . array list_as_array(int type) . list_begin . int list_begin(int type) . list_end . void list_end(int listid) . list_next . int list_next(int listid) . party_member_list . array party_member_list(int includeHidden) . Returns an array of all current party members (0 - only critter-type, alive and visible will be returned, 1 - all object, including Trunk, etc.) . ", "url": "/sfall/lists/#functions", "relUrl": "/lists/#functions" - },"74": { + },"111": { "doc": "Locks", "title": "Locks", "content": " ", "url": "/sfall/locks/", "relUrl": "/locks/" - },"75": { + },"112": { "doc": "Locks", "title": "Functions", "content": ". | lock_is_jammed | set_unjam_locks_time | unjam_lock | . lock_is_jammed . sfall.h . bool lock_is_jammed(ObjectPtr obj) . Returns 1 if the lock (container or scenery) is currently jammed, 0 otherwise. set_unjam_locks_time . sfall.h . void set_unjam_locks_time(int time) . Sets after how many hours (up to 127 hours) jammed locks will be unjammed if the player leaves the map. Also disables the auto unjam that occurs at midnight when the player is on the map. Passing 0 will disable the auto unjam mechanism completely. The auto unjam mechanism will be reset each time the player reloads the game. unjam_lock . sfall.h . void unjam_lock(ObjectPtr obj) . Unjams a lock immediately without having to wait until the next day, or leave the map and then return after 24 hours. Does not work in use_skill_on_p_proc procedure. ", "url": "/sfall/locks/#functions", "relUrl": "/locks/#functions" - },"76": { + },"113": { "doc": "Main interface", "title": "Main interface", "content": " ", "url": "/sfall/main-interface/", "relUrl": "/main-interface/" - },"77": { + },"114": { "doc": "Main interface", "title": "Functions", "content": ". | intface_hide | intface_is_hidden | intface_redraw | intface_show | . intface_hide . sfall.h . void intface_hide() . Hides main interface. intface_is_hidden . sfall.h . bool intface_is_hidden() . Returns 1 if interface is currently hidden, 0 otherwise. intface_redraw . sfall.h . void intface_redraw(bool winType) . Redraws main game interface. Useful after direct changes to current player weapons or stats to reflect changes. | redraws main game interface, useful to reflect changes after directly changing current player weapons or stats | winType: the type number of the interface window (see WINTYPE_* constants in sfall.h). Pass -1 to redraw all interface windows. | . intface_show . sfall.h . void intface_show() . Shows main interface. ", "url": "/sfall/main-interface/#functions", "relUrl": "/main-interface/#functions" - },"78": { + },"115": { "doc": "Maps and encounters", "title": "Maps and encounters", "content": " ", "url": "/sfall/maps-and-encounters/", "relUrl": "/maps-and-encounters/" - },"79": { + },"116": { "doc": "Maps and encounters", "title": "Subcategories", "content": ". | Rest | Worldmap | . ", "url": "/sfall/maps-and-encounters/#subcategories", "relUrl": "/maps-and-encounters/#subcategories" - },"80": { + },"117": { "doc": "Maps and encounters", "title": "Functions", "content": ". | exec_map_update_scripts | force_encounter | force_encounter_with_flags | get_map_enter_position | get_terrain_name | in_world_map | set_map_enter_position | set_map_time_multi | set_terrain_name | set_town_title | . exec_map_update_scripts . sfall.h . void exec_map_update_scripts() . Executes map_update_p_proc for all objects on map and global/hook scripts as well. force_encounter . void force_encounter(int map) . Can be called either from a global script while traveling on the world map, or from a normal script while on a local map. In either case the encounter occurs shortly after the next time the player moves on the world map. The player will not get an outdoorsman skill check. force_encounter_with_flags . void force_encounter_with_flags(int map, int flags) . Does the same thing as force_encounter, but allows the specification of some extra options (see sfall.h for available flags). Forcing a random encounter on a map that is not normally used for random encounters may cause the player to lose the car, if they have it. In this case use force_encounter_with_flags with the ENCOUNTER_FLAG_NO_CAR flag set. get_map_enter_position . array get_map_enter_position() . Returns an array of the player’s position data (index: 0 - tile, 1 - elevation, 2 - rotation) when entering the map through exit grids. If entering from the world map, the tile value will be -1. Should be called in map_enter_p_proc procedure to get the correct position data. get_terrain_name . sfall.h . string sfall_func2(\"get_terrain_name\", int x, int y) . Returns the terrain type name for the sub-tile on the world map by the specified coordinates, or by the player’s current position if called without arguments. in_world_map . bool in_world_map . Returns 1 if the player is looking at the world map, or 0 at any other time. Obviously this is only useful in global scripts, since normal scripts will never get the chance to run on the world map. set_map_enter_position . void set_map_enter_position(int tile, int elevation, int rotation) . Overrides the players entry position when entering the map through exit grids. Setting the tile to 0 will put the player on the start hex (default tile and elevation) of the map. Works only in map_enter_p_proc procedure. set_map_time_multi . void set_map_time_multi(float multi) . Adjusts how fast time passes while you’re on the world map. It takes a single float as an argument, where 1 is the normal speed. This function works in addition to the WorldMapTimeMod setting in ddraw.ini and the Pathfinder perk, rather than overriding it, so calling set_map_time_multi(0.5) when the player has 2 levels of Pathfinder would result in time passing at 25% the normal speed on the world map. set_terrain_name . sfall.h . void sfall_func3(\"set_terrain_name\", int x, int y, string name) . Overrides the terrain type name for the sub-tile on the world map by the specified coordinates. set_town_title . void sfall_func2(\"set_town_title\", int areaID, string title) . Sets a floating text for a town on the world map when hovering the cursor over the player’s marker. - areaID: the ID number of the town from city.txt . ", "url": "/sfall/maps-and-encounters/#functions", "relUrl": "/maps-and-encounters/#functions" - },"81": { + },"118": { "doc": "Math", "title": "Math", "content": " ", "url": "/sfall/math/", "relUrl": "/math/" - },"82": { + },"119": { "doc": "Math", "title": "Functions", "content": ". | ^ | abs | arctan | ceil | cos | div | exponent | floor2 | log | round | sin | sqrt | tan | . ^ . x^y . Exponentiation. Use as any other arithmetic operator, like 5^(1/3). If exponent is an integer, you can use a negative base, otherwise you will get “NaN” with a negative base. If both arguments are integers, the result will be an integer. abs . int/float abs(int/float x) . Absolute (positive) value of x. arctan . float arctan(float x, float y) . Arctangent of x. Pass 1 as y (don’t ask…). ceil . int ceil(float x) . Round x to the nearest integer that is not less than x. cos . float cos(float x) . Cosine of x . div . div(x, y) . Unsigned integer division. Use as a division operator, like 3 + (20 div 5). If both dividend and divisor are integers, they will be treated as unsigned integers. If one of them is a float, div will perform the signed division just like vanilla division operator. exponent . float exponent(float x) . E^X . floor2 . sfall.h . int floor2(int/float value) . Works just like vanilla floor function, but returns correct integers for negative floats. | NOTE: vanilla floor function works exactly the same as ceil for negative floats (i.e. basically trunc in C/C++). | . log . float log(float x) . Natural logarithm of x. round . int round(float x) . Round x to the nearest integer. sin . float sin(float x) . Sine of x . sqrt . float sqrt(float x) . Square root of x. tan . float tan(float x) . Tangent of x . ", "url": "/sfall/math/#functions", "relUrl": "/math/#functions" - },"83": { + },"120": { "doc": "NPC perks", "title": "NPC perks", "content": "These functions are similar to has_fake_*/set_fake_*/set_selectable_perk functions, but apply to the specified party member NPC (including dude_obj) . ", "url": "/sfall/npc-perks/", "relUrl": "/npc-perks/" - },"84": { + },"121": { "doc": "NPC perks", "title": "Functions", "content": ". | has_fake_perk_npc | has_fake_trait_npc | set_fake_perk_npc | set_fake_trait_npc | set_selectable_perk_npc | . has_fake_perk_npc . sfall.h . int has_fake_perk_npc(object npc, string namePerk) . has_fake_trait_npc . sfall.h . int has_fake_trait_npc(object npc, string nameTrait) . set_fake_perk_npc . sfall.h . void set_fake_perk_npc(object npc, string namePerk, int level, int image, string desc) . set_fake_trait_npc . sfall.h . void set_fake_trait_npc(object npc, string nameTrait, int active, int image, string desc) . set_selectable_perk_npc . sfall.h . void set_selectable_perk_npc(object npc, string namePerk, int active, int image, string desc) . ", "url": "/sfall/npc-perks/#functions", "relUrl": "/npc-perks/#functions" - },"85": { + },"122": { "doc": "Objects and scripts", "title": "Objects and scripts", "content": " ", "url": "/sfall/objects-and-scripts/", "relUrl": "/objects-and-scripts/" - },"86": { + },"123": { "doc": "Objects and scripts", "title": "Functions", "content": ". | dialog_obj | get_flags | get_object_data | get_script | loot_obj | obj_is_carrying_obj | obj_is_openable | obj_under_cursor | real_dude_obj | remove_script | set_dude_obj | set_flags | set_object_data | set_scr_name | set_script | set_self | set_unique_id | . dialog_obj . sfall.h . ObjectPtr dialog_obj() . Returns a pointer to the object (critter) the player is having a conversation or bartering with. get_flags . sfall.h . int get_flags(ObjectPtr obj) . Gets the current value of object flags (see define_extra.h for available flags). get_object_data . sfall.h . get_object_data(ObjectPtr object, int offset) . Returns the data at the specified offset of an object (see OBJ_DATA_* constants in define_extra.h for offsets). get_script . int get_script(ObjectPtr obj) . | accepts a pointer to an object and returns its scriptID (line number in scripts.lst), or 0 if the object is unscripted. | returns -1 on argument error. | . loot_obj . sfall.h . ObjectPtr loot_obj() . Returns a pointer to the target object (container or critter) of the loot screen. obj_is_carrying_obj . int (ObjectPtr invenObj, ObjectPtr itemObj) . Returns number of itemObj inside invenObj’s inventory, note that both arguments are object pointers. useful when dealing with different stacks of same item (obj_is_carrying_obj_pid just returns total for all stacks of the same PID.) . obj_is_openable . sfall.h . bool obj_is_openable(object obj) . Returns True if the object is openable (i.e. has an opening/closing animation), False otherwise . obj_under_cursor . sfall.h . ObjectPtr obj_under_cursor(bool onlyCritter, bool includeDude) . Returns the object under the cursor on the main game screen. | onlyCritter: . | True - only checks critters and ignores their cover (roof tiles, walls, scenery, etc.) | False - checks all objects (can’t check critters under objects) | . | passing False to the includeDude argument will ignore dude_obj . | NOTE: to get an object located on a tile when the cursor is in movement mode (hexagon cursor), use the tile_under_cursor function | . | . real_dude_obj . sfall.h . ObjectPtr real_dude_obj() . Returns the initial dude_obj after set_dude_obj was used. remove_script . void remove_script(ObjectPtr obj) . Accepts a pointer to an object and will remove the script from that object. set_dude_obj . sfall.h . void set_dude_obj(ObjectPtr critter) . Take control of a given critter. Passing value 0 will reset control back to “real” dude. set_flags . sfall.h . void set_flags(ObjectPtr obj, int flags) . Sets the current flags of an object. All flags are rewritten with given integer, so first get current flags with get_flags and use bwor/bwand to set/remove specific flag. set_object_data . sfall.h . set_object_data(ObjectPtr object, int offset, int data) . Sets the data at the specified offset of an object. set_scr_name . sfall.h . void set_scr_name(string name) . Overrides the name of the script object that was set from scrname.msg. | The changed name will be reset each time the player leaves the map or reloads the game | Passing an empty string (“”) to the name argument or omitting it will allow the game to get the name for the object from pro_*.msg files | NOTE: this function is intended for use in normal game scripts and overrides the name only once for the same object until reset | . set_script . void set_script(ObjectPtr obj, int scriptID) . Accepts a pointer to an object and scriptID, and applies the given script to an object (scriptID accept the same values as create_object_sid from sfall 3.6). If used on an object that is already scripted, it will remove the existing script first; you cannot have multiple scripts attached to a single object. Calling set_script on self_obj will have all sorts of wacky side effects, and should be avoided. If you add 0x80000000 to the sid when calling set_script, map_enter_p_proc will be SKIPPED. The start proc will always be run. set_self . void set_self(ObjectPtr setObj) . Overrides the script’s self_obj for the next function call. | It is primarily used to allow the calling of functions which take an implicit self_obj parameter (e.g. drop_obj) from global scripts, but it can also be used from normal scripts. | self_obj will be reverted to its original value after the next function call. | Calling set_self(0) will also revert self_obj to its original value. It is recommended to call this after each use of set_self in normal scripts in order to avoid unforeseen side effects. | source_obj, target_obj, and similar functions will not work if preceded by set_self. | NOTE: for use_obj, use_obj_on_obj vanilla functions to work correctly, it is required to call set_self twice. You can also access the local variables in the script of an object after calling set_self twice. | . set_unique_id . sfall.h . int set_unique_id(ObjectPtr object, int flag) . Assigns a unique ID number to the object and returns it. If a unique ID number has already been assigned to an object, then ID number is returned without reassignment. flag is optional. | items with unique IDs will not stack with other items of the same type in the inventory | to just get the current ID number of an object, use get_object_data(object, OBJ_DATA_ID) | unique ID numbers are saved in your savegame, and have a range from 0x10000000 to 0x7FFFFFFF | there is also a unique ID number range for the player and party members from 18000 to 83535 | to assign a new ID number generated by the engine to the object (i.e. unassign a unique ID), call the function with two arguments and pass -1 for the flag argument | . ", "url": "/sfall/objects-and-scripts/#functions", "relUrl": "/objects-and-scripts/#functions" - },"87": { + },"124": { "doc": "Optimization", "title": "Optimization", "content": ". | sslc -O option | Writing your own code | . The execution speed of scripts is not typically important in an unmodded game, given the difference in performance between a modern computer and what Fallout was designed for. When you start adding mods to the mix there’s the potential for problems again, since sfall’s global script system means that you can have a large amount of scripts being run every single frame. ", "url": "/sfall/optimization/", "relUrl": "/optimization/" - },"88": { + },"125": { "doc": "Optimization", "title": "sslc -O option", "content": "The sfall build of sslc supports a -O command line option to perform an optimization pass over the generated code. This isn’t a magic make-my-code-go-faster bullet; most of what it does is very limited in scope. It’s primary purpose was to strip out the procedures and variables which get automatically pulled into every script that includes define.h, whether you use them or not, and to do something about the additional variables that get created by foreach loops. There are several levels of optimization available: . | -O1 - Basic, only removes unreferenced variables and procedures, code itself remains untouched. | -O2 - Full, most code optimizations are on, but only those that were tested on complex scripts. | -O3 - Experimental, provides the most efficiency, but tends to break some complex code due to bugs. | . The following optimizations are performed: . | constant expression folding: if an expression depends only on values which are known at compile time, then the expression is replaced by its result. a := 2 + 2; -> a := 4; . | constant variable initialization: All variables are initialised to some value, (‘0’, if you don’t specify anything else,) so sslc attempts to make use of that fact to remove the first assignment to a variable if the first assignment is a constant expression. variable a; -> variable a := 4; a := 4; -> . | constant propagation: checks for values assigned to variables which can be computed at compile time, and replaces relevant references to the symbol by the constant. The original store is not removed by this optimization. Global variables are considered for this optimization only if they are not marked import or export, and are not assigned to anywhere in the script. a := 4; -> a := 4; foo(a); -> foo(4); . | dead code removal: Checks for and removes code which cannot be reached, either because it is hidden behind a return or because the argument to an if statement can be computed at compile time. if (True) then begin -> display_msg(\"foo\"); display_msg(\"foo\"); -> end else begin -> display_msg(\"bar\"); -> end -> . | unreferenced variable elimination: Checks for variables which are never referenced, and removes them. Also applies to global variables, as long as they are not marked for export. variable i, j, k; -> variable i; i := 1; -> i := 1; return; -> return; . | unreferenced procedure elimination: Checks for any procedures which are never called, and removes them. procedure foo begin return \"foo\"; end -> procedure foo begin return \"foo\"; end procedure bar begin return \"bar\"; end -> procedure start begin procedure start begin -> display_msg(foo); display_msg(foo); -> end end -> . | dead store removal: Removes variable assignments if the result of the variable is unused, and if the expression used to compute the value of the variable is provably free of side effects. (See pure keyword) a := \"moo\"; -> a := \"foo\"; a := \"foo\"; -> display_msg(a); display_msg(a); -> a := \"bar\"; -> . | store combination: Where there are two stores in a row to the same variable, the two expressions are combined. var1 := var2; -> var1 := var2 + var3; var1 += var3; -> . | variable combination: Where usage regions of variables do not overlap, combine the variables to provide additional candidates for unreferenced variable elimination. Very useful for scripts containing multiple foreach loops, which generate 2 or 3 hidden variables each. a := \"foo\"; -> a := \"foo\"; display_msg(a); -> display_msg(a); b := \"bar\"; -> a := \"bar\"; display_msg(b); -> display_msg(a); . | namelist compression: Fallout stores the names of all file scope variables and procedures in a namelist which is saved into the .int. Any of these that are unreferenced can be removed, and the names of global variables can be modified to make them shorter. | . ", "url": "/sfall/optimization/#sslc--o-option", "relUrl": "/optimization/#sslc--o-option" - },"89": { + },"126": { "doc": "Optimization", "title": "Writing your own code", "content": ". | Don’t have global scripts running any more often that you need them to. Not everything needs to be run every single frame. | Never concat constant strings with the + operator, as it forces the operation to be done at runtime. The compiler can cope with constant strings being placed next to each other without the need for a +, which results in far more efficient code as the combination is done at lex time. #define GLOB_PREFIX \"ts__\" -> #define GLOB_PREFIX \"ts__\" procedure start begin -> procedure start begin set_sfall_global(GLOB_PREFIX + \"foo1\", 0); -> set_sfall_global(GLOB_PREFIX \"foo1\", 0); end -> end . | Avoid function calls in while loops. Function calls are expensive in comparison to variable lookups, so it’s more efficient to move the function call out of the loop and store the result in a variable. while i < len_array(array) do begin -> tmp := len_array(array); ... -> while i < tmp do begin end -> ... -> end . | Mark functions with pure or inline where relevant. | pure is a hint to the optimizer that a procedure has no side effects. (i.e. there’s no way to tell that it’s been called aside from its return value.) Pure procedures cannot modify global variables, or call any other procedure that isn’t itself pure. Functions marked with pure can only be used in expressions (i.e. you cannot use the call <procedure> syntax to call them.) If there are non-pure terms in an expression, it prevents that expression being considered for dead store removal. Where no such optimizations can be performed, or if optimization is disabled, marking a procedure with pure will have no effect on the compiled code. | inline is an instruction to the compiler to replace calls to the marked procedure with a copy of the procedures code instead of having a separate call. Inlined procedures cannot use the return command, cannot be predefined, and cannot be used as part of an expression. Inlining if a procedure is only going to be called once is always a win, but if there are multiple calls to a procedure you will end up bloating the size of the generated code. | . | . ", "url": "/sfall/optimization/#writing-your-own-code", "relUrl": "/optimization/#writing-your-own-code" - },"90": { + },"127": { "doc": "Other", "title": "Other", "content": " ", "url": "/sfall/other/", "relUrl": "/other/" - },"91": { + },"128": { "doc": "Other", "title": "Functions", "content": ". | active_hand | add_g_timer_event | create_message_window | create_spatial | game_loaded | gdialog_get_barter_mod | get_game_mode | get_inven_ap_cost | get_kill_counter | get_light_level | get_npc_level | get_proto_data | get_unspent_ap_bonus | get_unspent_ap_perk_bonus | get_uptime | get_viewport_x | get_viewport_y | get_year | hero_select_win | inc_npc_level | input_funcs_available | mark_movie_played | message_str_game | mod_kill_counter | nb_create_char | resume_game | set_base_hit_chance_mod | set_base_pickpocket_mod | set_critter_hit_chance_mod | set_critter_pickpocket_mod | set_df_model | set_dm_model | set_hit_chance_max | set_hp_per_level_mod | set_inven_ap_cost | set_movie_path | set_pickpocket_max | set_pipboy_available | set_proto_data | set_unspent_ap_bonus | set_unspent_ap_perk_bonus | set_viewport_x | set_viewport_y | set_xp_mod | signal_close_game | sneak_success | stop_game | toggle_active_hand | unwield_slot | . active_hand . int active_hand . add_g_timer_event . sfall.h . void add_g_timer_event(int time, int fixedParam) . Adds a timer event that calls the timed_event_p_proc procedure in the current global script time: the number of ticks after which the event timer is triggered fixedParam: the value that is passed to the timed_event_p_proc procedure for the fixed_param function . create_message_window . void create_message_window(string message) . create_spatial . ObjectPtr create_spatial(int scriptID, int tile, int elevation, int radius) . Creates new spatial script with given SID, at given tile, and radius. game_loaded . int game_loaded() . Returns 1 the first time it is called after a new game or game load, and 0 any time after. It works on an individual basis for each script, so one script wont interfere with others. Its primary use is for global scripts, so that they know when to call set_global_script_repeat, but it can be called from normal scripts too. gdialog_get_barter_mod . int gdialog_get_barter_mod . get_game_mode . int get_game_mode() . A more flexible version of in_world_map. It will return a set of flags indicating which mode the game is currently in. These flags are the same as those used in the set_shader_mode function. get_inven_ap_cost . int get_inven_ap_cost . Returns the current AP cost to access the inventory in combat . get_kill_counter . int get_kill_counter(int critterType) . get_light_level . int get_light_level() . Returns ambient light level in range 0..65536. The value returned by get_light_level may not exactly match that set by set_light_level, as set_light_level applies modifiers from the Night Vision perk. get_npc_level . int get_npc_level(string npc) . get_proto_data . int get_proto_data(int pid, int offset) . Used to read the in-memory copies of the .pro files Fallout makes when they are loaded. The offset refers to the offset in memory from the start of the proto to the element you are reading. get_unspent_ap_bonus . int get_unspent_ap_bonus() . Gets the AC bonus you receive per unused action point at the end of your turn in combat. To allow for fractional values, the value given if divided by 4. (Hence the default value is 4 and not 1.) . get_unspent_ap_perk_bonus . int get_unspent_ap_perk_bonus() . Similar to get_unspent_ap_bonus, but accounts for the extra AC granted by the H2H Evade perk. (The default value of this is also 4, equivalent to doubling the original bonus. get_uptime . int get_uptime() . Just a wrapper around the windows GetTickCount() function. It’s useful for making time fade effects in shaders, since they already have access to the current tick count. get_viewport_x . int get_viewport_x() . get_viewport_y . int get_viewport_y() . get_year . int get_year . hero_select_win . void hero_select_win(int) . inc_npc_level . void inc_npc_level(int party_member_pid) . Takes a party member PID or an NPC name (deprecated, for compatibility with sfall 4.1.5/3.8.15 or earlier) as an argument. The NPC must be in your party. This function ignores player level requirements and the minimum 3 player level delay between NPC level gains. It also ignores the random element, regardless of sfall’s NPCAutoLevel setting. input_funcs_available . int input_funcs_available() . The input functions are only available if the user has the input hook turned on in ddraw.ini. Use input_funcs_available to check. mark_movie_played . void mark_movie_played(int id) . message_str_game . string message_str_game(int fileId, int messageId) . Works exactly the same as message_str, except you get messages from files in text/english/game folder. Use GAME_MSG_* defines or mstr_* macros from sfall.h to use specific msg file . | Additional game msg files added by ExtraGameMsgFileList setting will have consecutive fileIds assigned beginning from 0x2000 to 0x2FFF. (e.g. if you set ExtraGameMsgFileList=foo,bar in ddraw.ini, foo.msg will be associated with 0x2000 and bar.msg with 0x2001.). | If a file has a specific number assigned in ExtraGameMsgFileList, its fileId will be (0x2000 + assigned number). (e.g. with ExtraGameMsgFileList=foo,bar:2,foobar in ddraw.ini, bar.msg will be associated with 0x2002 and foobar.msg with 0x2003.) | . mod_kill_counter . void mod_kill_counter(int critterType, int amount) . nb_create_char . int nb_create_char() . nb_* functions are reserved for the brotherhood tactical training mod, and should be avoided. Not implemented, always returns 0. resume_game . void resume_game() . set_base_hit_chance_mod . void set_base_hit_chance_mod(int max, int mod) . set_base_pickpocket_mod . void set_base_pickpocket_mod(int max, int mod) . Changes maximum chance of success and chance mod for each steal attempt. max will replace 95% success chance cap (so you can set 100% maximum chance, for instance). mod will add this much percent to each success chance. for example if your chance is 50% and mod is 20, you will get 70% actual success rate . set_critter_hit_chance_mod . void set_critter_hit_chance_mod(CritterPtr, int max, int mod) . set_critter_pickpocket_mod . void set_critter_pickpocket_mod(CritterPtr, int max, int mod) . The same as set_base_pickpocket, but applies only to specific critter. set_df_model . void set_df_model(string name) . set_dm_model . void set_dm_model(string name) . set_hit_chance_max . void set_hit_chance_max(int percentage) . Effects all critters rather than just the player and can set the maximum in range from 0 to 999. set_hp_per_level_mod . void set_hp_per_level_mod(int mod) . set_inven_ap_cost . void set_inven_ap_cost(int cost) . set_movie_path . void set_movie_path(string filename, int movieid) . set_pickpocket_max . void set_pickpocket_max(int percentage) . Effects all critters rather than just the player and can set the maximum in range from 0 to 999. set_pipboy_available . void set_pipboy_available(int available) . Sets the availability of the pipboy in the game. Use 0 to disable the pipboy, and 1 or 2 to enable it (value 2 does not mark the VSUIT_MOVIE movie as “played”). set_proto_data . void set_proto_data(int pid, int offset, int value) . Used to alter the in-memory copies of the .pro files Fallout makes when they are loaded. The offset refers to the offset in memory from the start of the proto to the element you are reading. Changes are not stored on disc, and are not permanent. If you modify the protos, and then Fallout subsequently reloads the file your changes will be lost. set_unspent_ap_bonus . void set_unspent_ap_bonus(int multiplier) . Alters the AC bonus you receive per unused action point at the end of your turn in combat. To allow for fractional values, the value given if divided by 4. (Hence the default value is 4 and not 1.) . set_unspent_ap_perk_bonus . void set_unspent_ap_perk_bonus(int multiplier) . Similar to set_unspent_ap_bonus, but effects the extra AC granted by the H2H Evade perk. (The default value of this is also 4, equivalent to doubling the original bonus. set_viewport_x . void set_viewport_x(int view_x) . set_viewport_y . void set_viewport_y(int view_y) . set_xp_mod . void set_xp_mod(int percentage) . signal_close_game . sfall.h . void signal_close_game . Works in a similar way to vanilla function: metarule(METARULE_SIGNAL_END_GAME, 0), but it will then close the game instead of only returning the player to the main menu . sneak_success . int sneak_success . Returns 1 if last sneak attempt (roll against skill) was successful, 0 otherwise. This calls an internal engine function which is used to determine the perception range of critters (which you can override using HOOK_WITHINPERCEPTION). stop_game . void stop_game() . toggle_active_hand . void toggle_active_hand . unwield_slot . void sfall_func2(\"unwield_slot\", object critter, int slot) . unequips an item from the specified slot for a critter or the player can take off player’s equipped item when the inventory is opened, or the player is in the barter screen slot: 0 - armor slot, 1 - right slot, 2 - left slot (see INVEN_TYPE_* in define.h) . ", "url": "/sfall/other/#functions", "relUrl": "/other/#functions" - },"92": { + },"129": { "doc": "Outline", "title": "Outline", "content": " ", "url": "/sfall/outline/", "relUrl": "/outline/" - },"93": { + },"130": { "doc": "Outline", "title": "Functions", "content": ". | get_outline | outlined_object | set_outline | . get_outline . sfall.h . int get_outline(ObjectPtr obj) . Gets the current outline color for an object. outlined_object . sfall.h . ObjectPtr outlined_object() . Returns an object that is currently highlighted by hovering the mouse above it. set_outline . sfall.h . void set_outline(ObjectPtr obj, int color) . | sets the outline color of an object (see OUTLINE_* constants in sfall.h) | can also set a custom color from the game palette by shifting the color index value left by 8 bits: 0xCC00 where CC is the palette index (available since sfall 4.2.7/3.8.27) | passing 0 will disable the outline | . ", "url": "/sfall/outline/#functions", "relUrl": "/outline/#functions" - },"94": { + },"131": { "doc": "Perks and traits", "title": "Perks and traits", "content": " ", "url": "/sfall/perks-and-traits/", "relUrl": "/perks-and-traits/" - },"95": { + },"132": { "doc": "Perks and traits", "title": "Subcategories", "content": ". | NPC perks | . ", "url": "/sfall/perks-and-traits/#subcategories", "relUrl": "/perks-and-traits/#subcategories" - },"96": { + },"133": { "doc": "Perks and traits", "title": "Functions", "content": ". | add_trait | apply_heaveho_fix | clear_selectable_perks | get_perk_available | get_perk_owed | has_fake_perk | has_fake_trait | hide_real_perks | perk_add_mode | remove_trait | seq_perk_freq | set_fake_perk | set_fake_trait | set_perk_agl | set_perk_chr | set_perk_desc | set_perk_end | set_perk_freq | set_perk_image | set_perk_int | set_perk_lck | set_perk_level | set_perk_level_mod | set_perk_name | set_perk_owed | set_perk_per | set_perk_ranks | set_perk_skill1 | set_perk_skill1_mag | set_perk_skill2 | set_perk_skill2_mag | set_perk_stat | set_perk_stat_mag | set_perk_str | set_perk_type | set_perkbox_title | set_pyromaniac_mod | set_selectable_perk | set_swiftlearner_mod | show_real_perks | . add_trait . sfall.h . void add_trait(int traitID) . adds the specified trait to the player . apply_heaveho_fix . void apply_heaveho_fix . clear_selectable_perks . void clear_selectable_perks() . Restores the “select a perk” box to its default state. get_perk_available . int get_perk_available(int perk) . get_perk_owed . int get_perk_owed . has_fake_perk . int has_fake_perk(string name) . Returns the number of levels the player has of the perks with the given name or ID of extra perk. has_fake_trait . int has_fake_trait(string name) . Returns the number of levels the player has of the traits with the given name or ID of extra trait. hide_real_perks . void hide_real_perks() . Prevent the “select a perk” box from displaying any of the original 119 perks. perk_add_mode . void perk_add_mode(int type) . Modifies what happens when a fake perk is selected from the perks dialog. It is treated as a set of flags - if bit 1 is set then it is added to the player’s traits, if bit 2 is set it is added to the player’s perks, and if bit 3 is set it is removed from the list of selectable perks. The default is 0x2. remove_trait . void remove_trait(int traitID) . seq_perk_freq . void seq_perk_freq(int value) . Sets the number of levels between each perk. set_fake_perk . void set_fake_perk(string name, int level, int image, string desc) . Used to add additional traits and perks to the character screen. They will be saved correctly when the player saves and reloads games, but by themselves they will have no further effect on the character. For perks, the allowed range for levels is between 0 and 100; setting the level to 0 removes that perk. For traits, the level must be 0 or 1. The image is a numeric ID that corresponds to an entry in skilldex.lst. The name is limited to 63 characters and the description to 255 characters by sfall, but internal Fallout limits may be lower. set_fake_trait . void set_fake_trait(string name, int active, int image, string desc) . Used to add additional traits and perks to the character screen. They will be saved correctly when the player saves and reloads games, but by themselves they will have no further effect on the character. For perks, the allowed range for levels is between 0 and 100; setting the level to 0 removes that perk. For traits, the level must be 0 or 1. The image is a numeric ID that corresponds to an entry in skilldex.lst. The name is limited to 63 characters and the description to 255 characters by sfall, but internal Fallout limits may be lower. set_perk_agl . void set_perk_agl(int perkID, int value) . set_perk_chr . void set_perk_chr(int perkID, int value) . set_perk_desc . void set_perk_desc(int perkID, string value) . set_perk_end . void set_perk_end(int perkID, int value) . set_perk_freq . void set_perk_freq(int value) . Sets the number of levels between each perk. Setting to 0 will reset it back to the default. This overrides the effects of the skilled trait. Not saved into the save game, so needs to be called once per reload. Be careful not to let the player obtain a perk when no perks are available to pick, or the game may crash. set_perk_image . void set_perk_image(int perkID, int value) . set_perk_int . void set_perk_int(int perkID, int value) . set_perk_lck . void set_perk_lck(int perkID, int value) . set_perk_level . void set_perk_level(int perkID, int value) . set_perk_level_mod . void set_perk_level_mod(int levels) . Sets a modifier between +25 and -25 that is added/subtracted from the player’s level for the purposes of deciding which perks can be chosen. set_perk_name . void set_perk_name(int perkID, string value) . set_perk_owed . void set_perk_owed(int value) . set_perk_per . void set_perk_per(int perkID, int value) . set_perk_ranks . void set_perk_ranks(int perkID, int value) . set_perk_skill1 . void set_perk_skill1(int perkID, int value) . set_perk_skill1_mag . void set_perk_skill1_mag(int perkID, int value) . set_perk_skill2 . void set_perk_skill2(int perkID, int value) . set_perk_skill2_mag . void set_perk_skill2_mag(int perkID, int value) . set_perk_stat . void set_perk_stat(int perkID, int value) . set_perk_stat_mag . void set_perk_stat_mag(int perkID, int value) . set_perk_str . void set_perk_str(int perkID, int value) . set_perk_type . void set_perk_type(int perkID, int value) . set_perkbox_title . void set_perkbox_title(string title) . Used to change the title of the “select a perk” box, or by using “” it will be set back to the default. set_pyromaniac_mod . void set_pyromaniac_mod(int bonus) . set_selectable_perk . void set_selectable_perk(string name, int active, int image, string desc) . Used to add additional items to “select a perk” box by setting the ‘active’ parameter to 1, and to remove them again by setting it to 0. set_swiftlearner_mod . void set_swiftlearner_mod(int bonus) . show_real_perks . void show_real_perks() . Reverts the effect os hide_real_perks. ", "url": "/sfall/perks-and-traits/#functions", "relUrl": "/perks-and-traits/#functions" - },"97": { + },"134": { "doc": "Pip-Boy", "title": "Pip-Boy", "content": " ", "url": "/sfall/pip-boy/", "relUrl": "/pip-boy/" - },"98": { + },"135": { "doc": "Pip-Boy", "title": "Functions", "content": ". | set_quest_failure_value | . set_quest_failure_value . void sfall_func2(\"set_quest_failure_value\", int gvarNumber, int thresholdValue) . | sets the threshold value (failure_threshold) for the quest at which the quest will be considered failed (its description in the pipboy will be crossed out and colored red) | gvarNumber: the number of the global variable controlling the quest | thresholdValue: the value of the global variable at which the quest is counted as a failure | . ", "url": "/sfall/pip-boy/#functions", "relUrl": "/pip-boy/#functions" - },"99": { + },"136": { "doc": "read_xxx", "title": "read_xxx", "content": "These functions take a memory address as the parameter and can read arbitrary pieces of Fallout’s address space. ", "url": "/sfall/read_xxx/", "relUrl": "/read_xxx/" - },"100": { + },"137": { "doc": "read_xxx", "title": "Functions", "content": ". | read_byte | read_int | read_short | read_string | . read_byte . int read_byte(int address) . read_int . int read_int(int address) . read_short . int read_short(int address) . read_string . int read_string(int address) . ", "url": "/sfall/read_xxx/#functions", "relUrl": "/read_xxx/#functions" - },"101": { + },"138": { "doc": "Rest", "title": "Rest", "content": " ", "url": "/sfall/rest/", "relUrl": "/rest/" - },"102": { + },"139": { "doc": "Rest", "title": "Functions", "content": ". | get_can_rest_on_map | set_can_rest_on_map | . get_can_rest_on_map . sfall.h . get_can_rest_on_map(int mapNum, int elev) . | returns the set rest value of the map after using the set_can_rest_on_map function | Returns -1 if the rest value of the map was not previously set (i.e. no data for the map in sfalldb.sav) | the can_rest_here values from maps.txt are ignored. | . set_can_rest_on_map . sfall.h . void set_can_rest_on_map(int mapNum, int elev, bool value) . Allows/disallows to rest on the map for the specified level, overrides the can_rest_here values in maps.txt. | mapNum is the map index from maps.txt | passing -1 to the elev argument will set the rest value for all map elevations | the set rest value will be stored in sfalldb.sav file (in savegame) | . ", "url": "/sfall/rest/#functions", "relUrl": "/rest/#functions" - },"103": { + },"140": { "doc": "Sfall funcX macros", "title": "Sfall funcX macros", "content": " ", "url": "/sfall/sfall-funcx-macros/", "relUrl": "/sfall-funcx-macros/" - },"104": { + },"141": { "doc": "Sfall funcX macros", "title": "Functions", "content": ". | add_extra_msg_file | critter_inven_obj2 | dialog_message | get_current_inven_size | get_metarule_table | get_object_ai_data | get_text_width | item_weight | metarule_exist | npc_engine_level_up | objects_in_radius | set_drugs_data | set_rest_heal_time | set_rest_mode | set_worldmap_heal_time | sfall_func0(“hide_window”) | sfall_func0(“show_window”) | sfall_func1(“hide_window”, string winName) | sfall_func1(“remove_timer_event”, int fixedParam) | sfall_func1(“show_window”, string winName) | sfall_func2(“string_compare”, string str1, string str2) | sfall_func3(“string_compare”, string str1, string str2, int codePage) | spatial_radius | void sfall_func0(“remove_timer_event”) | . add_extra_msg_file . sfall.h . int add_extra_msg_file(string fileName) . Loads the custom message file, and returns the file ID number assigned to it in range from 0x3000 to 0x3FFF for the message_str_game function to get messages from the file. | fileName: the name of the custom message file (including the .msg extension) in text\\<language>\\game\\ directory. | . Alternative form: int add_extra_msg_file(string fileName, int fileNumber) . | fileNumber: the file ID number for the message_str_game function. The available range is from 0x2000 to 0x2FFF (see ExtraGameMsgFileList setting in ddraw.ini) Use fileNumber only if you want to add a message file without editing ddraw.ini or existing scripts to support the old way. | . critter_inven_obj2 . sfall.h . ObjectPtr critter_inven_obj2(ObjectPtr obj, int type) . Works just like vanilla critter_inven_obj, but correctly reports item in player’s inactive hand slot. dialog_message . sfall.h . void dialog_message(string text) . Displays a message in the NPC response window in dialog or barter screen. get_current_inven_size . sfall.h . get_current_inven_size(ObjectPtr object) . Returns the current inventory size of the container or the critter. get_metarule_table . sfall.h . array get_metarule_table . Returns names of all currently available script functions. get_object_ai_data . sfall.h . int get_object_ai_data(ObjectPtr object, int aiParam) . Returns the setting value from the AI packet of an object (critter). Use AI_CAP_* constants from define_extra.h for the aiParam argument to get AI value. get_text_width . sfall.h . int get_text_width(string text) . Returns the text width in pixels for the currently set font. item_weight . sfall.h . int item_weight(ObjectPtr obj) . Gets the current weight of an object. metarule_exist . sfall.h . bool metarule_exist(string metaruleName) . Returns True if the specified name of metarule (sfall_funcX) function exists in the current version of sfall. npc_engine_level_up . sfall.h . void npc_engine_level_up(bool toggle) . Enables/disables the engine function that increases the level of party members in the player leveling process. If the engine function is disabled, the process of leveling up party members should be performed by script functions. objects_in_radius . sfall.h . array objects_in_radius(int tile, int radius, int elevation, int type) . | returns an array of objects of a type (see OBJ_TYPE_* constants in define_extra.h) within the specified radius from the given tile | passing -1 to the type argument or not specifying it will return all objects within the radius | the radius is limited to 50 hexes | . set_drugs_data . sfall.h . void set_drugs_data(int type, int pid, int value) . Overrides the parameters of drugs set in the configuration file (DrugsFile setting in ddraw.ini). Type: 0 - changes the value of NumEffects for the drug (see Drugs.ini for the description of NumEffects), 1 - changes the duration of the addiction effect for the drug (a value of 1 = one game minute). set_rest_heal_time . sfall.h . void set_rest_heal_time(int time) . Sets the time interval in minutes for healing during resting. The default is 180 . | the time interval will be reset each time the player reloads the game | . set_rest_mode . sfall.h . void set_rest_mode(int flags) . Sets the bit flags for the rest mode (see RESTMODE_* constants in sfall.h). Passing 0 will reset the rest mode. It will also be reset each time the player reloads the game. set_worldmap_heal_time . sfall.h . void set_worldmap_heal_time(int time) . Sets the time interval in minutes for healing during world map travel. The default is 180 . | passing 0 will revert to 1 second of real time (vanilla engine behavior) | passing -1 will disable healing during travel | the time interval will be reset each time the player reloads the game | . sfall_func0(“hide_window”) . sfall.h . void sfall_func0(\"hide_window\") . Hides currently active (selected) script window. sfall_func0(“show_window”) . sfall.h . void sfall_func0(\"show_window\") . Displays the script window previously hidden with the sfall_func0(\"hide_window\") function. sfall_func1(“hide_window”, string winName) . sfall.h . void sfall_func0(\"hide_window\") . Hides the specified script window. | winName: the window name, assigned to the window by the CreateWin/create_win function | . sfall_func1(“remove_timer_event”, int fixedParam) . sfall.h . void sfall_func1(\"remove_timer_event\", int fixedParam) . Removes all timer events with the specified fixedParam value for the current global script. sfall_func1(“show_window”, string winName) . sfall.h . void sfall_func1(\"show_window\", string winName) . Displays the specified hidden script window. winName: the window name, assigned to the window by the CreateWin/create_win function . sfall_func2(“string_compare”, string str1, string str2) . sfall.h . bool sfall_func2(\"string_compare\", string str1, string str2) . Compares two strings case-insensitive, and returns True if the two strings are matched. sfall_func3(“string_compare”, string str1, string str2, int codePage) . sfall.h . bool sfall_func3(\"string_compare\", string str1, string str2, int codePage) . Compares two strings case-insensitive, and returns True if the two strings are matched . | codePage: code page number to properly compare national characters in the range 128-255 of the ASCII code table available encodings: 1250-1252, 866 | . spatial_radius . sfall.h . int spatial_radius(ObjectPtr obj) . Returns radius of spatial script, associated with given dummy-object (returned by create_spatial). void sfall_func0(“remove_timer_event”) . sfall.h . void sfall_func0(\"remove_timer_event\") . Clears all set timer events for the current global script. ", "url": "/sfall/sfall-funcx-macros/#functions", "relUrl": "/sfall-funcx-macros/#functions" - },"105": { + },"142": { "doc": "Sfall", "title": "Sfall", "content": " ", "url": "/sfall/sfall/", "relUrl": "/sfall/" - },"106": { + },"143": { "doc": "Sfall", "title": "Subcategories", "content": ". | Version | funcX | . ", "url": "/sfall/sfall/#subcategories", "relUrl": "/sfall/#subcategories" - },"107": { + },"144": { "doc": "Skills", "title": "Skills", "content": " ", "url": "/sfall/skills/", "relUrl": "/skills/" - },"108": { + },"145": { "doc": "Skills", "title": "Functions", "content": ". | get_available_skill_points | get_critter_skill_points | mod_skill_points_per_level | set_available_skill_points | set_base_skill_mod | set_critter_skill_mod | set_critter_skill_points | set_skill_max | . get_available_skill_points . int get_available_skill_points() . get_critter_skill_points . int get_critter_skill_points(int critter, int skill) . Will get the number of additional points a critter has in a skill, on top of whatever they have from their stats and other bonuses . mod_skill_points_per_level . void mod_skill_points_per_level(int value) . Accepts a value of between -100 and 100, and modifies the number of skill points the player recieves when they level up. This is a modification of what would otherwise happen, rather than a replacement. The value is not saved into the save game, so should be reset in the game_loaded section of a script. set_available_skill_points . void set_available_skill_points(int value) . set_base_skill_mod . void set_base_skill_mod(int max) . set_critter_skill_mod . void set_critter_skill_mod(CritterPtr, int max) . set_critter_skill_points . void set_critter_skill_points(int critter, int skill, int value) . Will set the number of additional points a critter has in a skill, on top of whatever they have from their stats and other bonuses. Note that skill points are part of the proto, so calling it on a critter will affect all critters that share the same proto. set_skill_max . void set_skill_max(int value) . Can’t be used to increase the skill cap above 300. ", "url": "/sfall/skills/#functions", "relUrl": "/skills/#functions" - },"109": { + },"146": { "doc": "SSLC", "title": "SSLC", "content": ". | Command line options | Additional supported syntax | Fixes | Backward compatibility | int2ssl note | . This is a modified copy of sslc, that has a few bugfixes from the original, that will recognise and compile the additional script functions provided by sfall, that can also understand some additional syntax, and that has an integrated preprocessor and optimizer. Unlike the original script compiler, this has not been compiled as a DOS program. When using this in place of the original compile.exe but still using p.bat, you need to get rid of the dos4gw.exe reference from p.bat. When compiling global or hook scripts for sfall 3.4 or below, you must include the line procedure start; before any #include files that define procedures to avoid a few weird problems. This is no longer required starting from 3.5. This version of compiler was designed primarily for new sfall functions, but it can be safely used (and is recommended) with non-sfall scripts as well. The original unmodified sslc source is over here: https://teamx.ru/site_arc/utils/index.html . ", "url": "/sfall/sslc/", "relUrl": "/sslc/" - },"110": { + },"147": { "doc": "SSLC", "title": "Command line options", "content": "-q don't wait for input on error -n no warnings -b use backward compatibility mode -l no logo -p preprocess source -P preprocess only (don't generate .int) -F write full file paths in \"#line\" directives -O optimize code (full optimization, see \"Optimization\" page) -O<N> set specific level of optimization (0 - none, 1 - basic, 2 - full, 3 - experimental) -d print debug messages -D output an abstract syntax tree of the program -o set output path (follows the input file name) -s enable short-circuit evaluation for all AND, OR operators -m<macro>[=<val>] define a macro named \"macro\" for conditional compilation -I<path> specify an additional directory to search for include files . The original command line option -w to turn on warnings no longer has an effect, since warnings are now on by default . ", "url": "/sfall/sslc/#command-line-options", "relUrl": "/sslc/#command-line-options" - },"111": { + },"148": { "doc": "SSLC", "title": "Additional supported syntax", "content": "Syntax which requires sfall for compiled scripts to be interpreted is marked by asterisk (*). | Optional arguments in user-defined procedures. You can only use constants for default values. It basically puts those constants in place of omitted arguments. | new: procedure test(variable x, variable y := 0, variable z := -1) begin ... end ... call test(\"value\"); . | old: procedure test(variable x, variable y, variable z) begin ... end ... call test(\"value\", 0, -1); . | . | New logical operators AndAlso, OrElse for short-circuit evaluation of logical expressions. Using these operators allow the right part of logical expressions not to be evaluated (executed, computed) if the result is already known. This can improve the performance of running scripts. Example: if (obj andAlso obj_pid(obj) == PID_STIMPAK) then ... If obj is null, the second condition will not be checked and your script won’t fail with “obj is null” error in debug.log . This also has an effect that a value of last computed argument is returned as a result of whole expressions, instead of always false (0) or true (1): . obj := false; display_msg(obj orElse \"something\"); // will print \"something\" . You can also use the -s option to enable short-circuit evaluation for all the AND, OR operators in the script. NOTE: Be aware that it may break some old scripts because operators behavior is changed slightly. | Conditional expressions (Python-inspired), also known as ternary operator: . | new: X := value1 if (condition) else value2 . | old: if (condition) then X := value1; else X := value2; . | . | To assign values, you can use the alternative assignment operator from C/Java instead of Pascal syntax. | new: x = 5; . | old: x := 5; . | . | Multiple variable declaration: Multiple variables can be declared on one line, separated by commas. This is an alternative to the ugly begin/end block, or the bulky single variable per line style. | new: variable a, b, c; . | old: variable begin a; b; c; end . | . | Variable initialization with expressions: You can now initialize local variables with complex expressions instead of constants. | new: variable tile := tile_num(dude_obj); . | old: variable tile; tile := tile_num(dude_obj); . NOTE: If your expression starts with a constant (eg. 2 + 2), enclose it in parentheses, otherwise compiler will be confused and give you errors. | . | Hexadecimal numerical constants: Simply prefix a number with 0x to create a hexadecimal. The numbers 0 to 9 and letters A to F are allowed in the number. The number may not have a decimal point. | new: a := 0x1000; . | old: a := 4096; . | . | Increment/decrement operators: ++ and -- can be used as shorthand for += 1 and -= 1 respectively. They are merely a syntactic shorthand to improve readability, and so their use is only allowed where += 1 would normally be allowed. | new: a++; . | old: a += 1; . | . | break & continue statements: They work just like in most high-level languages. break jumps out of the loop. continue jumps right to the beginning of the next iteration (see for and foreach sections for additional details). | new: while (i < N) begin // ... if (/* some condition */) then break; // ... end . | old: while (i < N and not(breakFlag)) begin // ... if (/* condition */) then breakFlag := true; // ... end . | new: for (i := 0; i < N; i++) begin // ... if (/* condition */) then begin // action continue; end // else actions end . | old: for (i := 0; i < N; i++) begin // ... if (/* condition */) then begin // action end else begin // else actions end end . | . | for loops: Another piece of syntactic shorthand, to shorten while loops in many cases. Parentheses around the loop statements are recommended but not required (when not using parentheses, a semicolon is required after the 3rd loop statement). | new: for (i := 0; i < 5; i++) begin display_msg(\"i = \" + i); end . | old: i := 0; while (i < 5) do begin display_msg(\"i = \" + i); i++; end . NOTE: continue statement in a for loop will recognize increment statement (third statement in parentheses) and will execute it before jumping back to the beginning of loop. This way you will not get an endless loop. | . | switch statements: A shorthand way of writing big if then else if... blocks . | new: switch get_attack_type begin case ATKTYPE_PUNCH: display_msg(\"punch\"); case ATKTYPE_KICK: display_msg(\"kick\"); default: display_msg(\"something else\"); end . | old: variable tmp; tmp := get_attack_type; if tmp == ATKTYPE_PUNCH then begin display_msg(\"punch\"); end else if tmp == ATKTYPE_KICK then begin display_msg(\"kick\"); end else begin display_msg(\"something else\"); end . | . | Procedure stringify operator @: Designed to make callback-procedures a better option and allow for basic functional programming. Basically it replaces procedure names preceded by @ by a string constant. | old: callbackVar := \"Node000\"; call callbackVar; . | new: callbackVar := @Node000; call callbackVar; . Not many people know that since vanilla Fallout you can call procedures by “calling a variable” containing it’s name as a string value. There was a couple of problems using this: . | optimizer wasn’t aware that you are referencing a procedure, and could remove it, if you don’t call it explicitly (can be solved by adding making procedure critical) | you couldn’t see all references of a procedure from a Script Editor | it was completely not obvious that you could do such a thing, it was a confusing syntax | . | (*) Arrays: In vanilla Fallout, arrays had to be constructed by reserving a block of global/map variables. Since sfall 2.7, specific array targeted functions have been available, but they are fairly messy and long winded to use. The compiler provides additional syntactic shorthand for accessing and setting array variables, as well as for array creation. When declaring an array variable, put a constant integer in []` to give the number of elements in the array. (before sfall 3.4 you had to specify size in bytes for array elements, now it’s not required, see “Arrays” page for more information) . | new: procedure bingle begin variable a[2]; a[0] := 5; a[a[0] - 4] := a[0] + 4; display_msg(\"a[0]=\" + a[0] + \", a[1]=\" + a[1]); end . | old: procedure bingle begin variable a; a := temp_array(2, 4); set_array(a, 0, 5); set_array(a, get_array(a, 0) - 4, get_array(a, 0) + 4); display_msg(\"a[0]=\" + get_array(a, 0) + \", a[1]=\" + get_array(a, 1)); end . | . | (*) Array expressions: Sometimes you need to construct an array of elements and you will probably want to do it in just one expression. This is now possible: . | new: list := [\"A\", \"B\", \"C\", \"D\"]; . | old: list := temp_array(4, 2); list[0] := \"A\"; list[1] := \"B\"; list[2] := \"C\"; list[3] := \"D\"; . Syntax specific for associative arrays is also available. (see “Arrays” page for full introduction to this type of arrays). | . | (*) Map array expressions: map := {5: \"five\", 10: \"ten\", 15: \"fifteen\", 20: \"twelve\"}; . | (*) The dot . syntax to access elements of associative arrays and allow to work with arrays like objects: trap.radius := 3; trap.tile := tile_num(dude_obj); . You can chain dot and bracket syntax to access elements of multi-dimensional arrays: . collectionList[5].objectList[5].name += \" foo\"; . NOTE: When using incremental operators like +=, *=, ++, -- compiler will use additional temp variable to get an array at penultimate level in order to avoid making the same chain of get_array calls twice. | (*) foreach loops: A shorthand method of looping over all elements in an array. Syntax is foreach (<symbol> in <expression>). You can declare variables in place by adding the variable keyword before the symbol name. | new: procedure bingle begin variable critter; foreach (critter in list_as_array(LIST_CRITTERS)) begin display_msg(\"\" + critter); end end . | old: procedure bingle begin variable begin critter; array; len; count; end array := list_as_array(LIST_CRITTERS); len := len_array(array); count := 0; while count < len do begin critter := array[count]; display_msg(\"\" + critter); end end . | . If you want an index array element (or key for “maps”) at each iteration, use syntax: foreach (<symbol>: <symbol> in <expression>) . foreach (pid: price in itemPriceMap) begin if (itemPid == pid) then itemPrice := price; end . If you want to add additional condition for continuing the loop, use syntax: foreach (<symbol> in <expression> while <expression>). In this case loop will iterate over elements of an array until last element or until “while” expression is true (whatever comes first). NOTE: Just like for loop, continue statement will respect increments of a hidden counter variable, so you can safely use it inside foreach. | . ", "url": "/sfall/sslc/#additional-supported-syntax", "relUrl": "/sslc/#additional-supported-syntax" - },"112": { + },"149": { "doc": "SSLC", "title": "Fixes", "content": ". | playmoviealpharect was using the token for playmoviealpha, breaking both functions in the process. | addbuttonflag had an entry in the token table, and could be parsed, but was missing an entry in the emit list. This resulted in the compiler accepting it as a valid function, but not outputting any code for it into the compiled script. | The function tokenize was missing an entry in the token table, and so would not be recognised by the compiler. | Fixed the check for the call \"foo\" syntax so that non-string constants will no longer be accepted. | . ", "url": "/sfall/sslc/#fixes", "relUrl": "/sslc/#fixes" - },"113": { + },"150": { "doc": "SSLC", "title": "Backward compatibility", "content": "There are several changes in this version of sslc which may result in problems for previously working scripts. A new command line option -b is available, which will turn off all new fixes and features which have the possibility of causing a previously compiling script to change its behaviour. (And only those features; anything which would not compile under the old sslc is not affected.) This includes the following: . | Since for, foreach, break, continue, in and tokenize are now hardcoded names, existing scripts that use any of them as a variable or procedure name will no longer compile. | Missing a semicolon after a variable declaration is now a hard error. (Originally sslc would check for the semicolon, but would not complain if it was missing.) | The function addbuttonflag used to be recognised by the compiler, but would not emit any code into the int file. | The function playmoviealpharect compiled as playmoviealpha. | . ", "url": "/sfall/sslc/#backward-compatibility", "relUrl": "/sslc/#backward-compatibility" - },"114": { + },"151": { "doc": "SSLC", "title": "int2ssl note", "content": "int2ssl by Anchorite (TeamX) is included in sfall modderspack package. It was updated to support all additional opcodes of sfall, along with some syntax features. You can use it to decompile any sfall or non-sfall script. ", "url": "/sfall/sslc/#int2ssl-note", "relUrl": "/sslc/#int2ssl-note" - },"115": { + },"152": { "doc": "Stats", "title": "Stats", "content": "The get/set_pc_base/extra_stat functions are equivalent to calling get/set_critter_base/extra_stat with dude_obj as the critter pointer. None of these stat functions take perks into account, and neither do they do range clamping to make sure the stats are valid. Use the normal get_critter_stat function to get a correctly perk adjusted and range clamped value for a stat. ", "url": "/sfall/stats/", "relUrl": "/stats/" - },"116": { + },"153": { "doc": "Stats", "title": "Subcategories", "content": ". | Alter min/max | . ", "url": "/sfall/stats/#subcategories", "relUrl": "/stats/#subcategories" - },"117": { + },"154": { "doc": "Stats", "title": "Functions", "content": ". | get_critter_base_stat | get_critter_extra_stat | get_pc_base_stat | get_pc_extra_stat | get_stat_max | get_stat_min | set_critter_base_stat | set_critter_extra_stat | set_pc_base_stat | set_pc_extra_stat | . get_critter_base_stat . int get_critter_base_stat(CritterPtr, int StatID) . get_critter_extra_stat . int get_critter_extra_stat(CritterPtr, int StatID) . get_pc_base_stat . int get_pc_base_stat(int StatID) . get_pc_extra_stat . int get_pc_extra_stat(int StatID) . get_stat_max . get_stat_max(int stat, bool who = False) . | Returns the maximum set value of the specified stat (see set_stat_max functions) | who: 0 (False) or omitting the argument - returns the value of the player, 1 (True) - returns the value set for other critters | . get_stat_min . get_stat_min(int stat, bool who = False) . | Returns the minimum set value of the specified stat (see set_stat_min functions) | who: 0 (False) or omitting the argument - returns the value of the player, 1 (True) - returns the value set for other critters | . set_critter_base_stat . void set_critter_base_stat(CritterPtr, int StatID, int value) . set_critter_extra_stat . void set_critter_extra_stat(CritterPtr, int StatID, int value) . set_pc_base_stat . void set_pc_base_stat(int StatID, int value) . set_pc_extra_stat . void set_pc_extra_stat(int StatID, int value) . ", "url": "/sfall/stats/#functions", "relUrl": "/stats/#functions" - },"118": { + },"155": { "doc": "Strings", "title": "Strings", "content": " ", "url": "/sfall/strings/", "relUrl": "/strings/" - },"119": { + },"156": { "doc": "Strings", "title": "Functions", "content": ". | charcode | get_string_pointer | string_find | string_find_from | string_format | string_format_array | string_replace | string_split | string_to_case | strlen | substr | . charcode . int charcode(string text) . Returns ASCII code for the first character in given string. get_string_pointer . sfall.h . int get_string_pointer(string text) . (DEPRECATED) Returns a pointer to a string variable or to a text . | NOTE: this function is intended for use only in HOOK_DESCRIPTIONOBJ. Starting from sfall 4.4/3.8.40, you can return normal strings directly in the hook without calling the function | . string_find . sfall.h . int string_find(string haystack, string needle) . Returns the position of the first occurrence of a needle string in a haystack string, or -1 if not found. The first character position is 0 (zero). string_find_from . sfall.h . int string_find_from(string haystack, string needle, int pos) . Works the same as string_find, except you can specify the position to start the search. | If pos is negative - it indicates a position starting from the end of the string, similar to substr(). | . string_format . sfall.h . string string_format(string format, any val1, any val2, ...) . Formats given values using standard syntax of C printf function (google “printf” for format details). However, it is limited to formatting up to 7 values. | The format string is limited to 1024 characters | . string_format_array . lib.strings.h . string string_format_array(string format, int array) . The same as string_format, but accepts an array of parameters. string_replace . lib.strings.h . string string_replace(string str, string search, string replace) . Replaces all occurances of a given search string in a string with a given replacement string. string_split . array string_split(string text, split) . Takes a string and a seperator, searches the string for all instances of the seperator, and returns a temp array filled with the pieces of the string split at each instance. If you give an empty string as the seperator, the string is split into individual characters. You can use this to search for a substring in a string like this: strlen(get_array(string_split(haystack, needle), 0)) . string_to_case . string sfall_func2(\"string_to_case\", string text, int toCase) . Converts all letters in the given string to the specified case. toCase: 0 - lowercase, 1 - uppercase . NOTE: this function works only for English letters of A-Z/a-z. strlen . int strlen(string text) . Returns string length. substr . string substr(string text, int start, int length) . Cuts a substring from a string starting at “start” up to “length” characters. The first character position is 0 (zero). | If start is negative - it indicates a position starting from the end of the string (for example substr(\"test\", -2, 2) will return last 2 charactes: “st”). | If length is negative - it means so many characters will be omitted from the end of string (example: substr(\"test\", 0, -2) will return string without last 2 characters: “te”). | If length is zero - it will return a string from the starting position to the end of the string. New behavior for sfall 4.2.2/3.8.22 | . ", "url": "/sfall/strings/#functions", "relUrl": "/strings/#functions" - },"120": { + },"157": { "doc": "Tags", "title": "Tags", "content": "show_iface_tag, hide_iface_tag and is_iface_tag_active relate to the boxes that appear above the interface such as SNEAK and LEVEL. You can use 0 for SNEAK (starting from sfall 4.4.4/3.8.44), 3 for LEVEL, 4 for ADDICT, and 5 to (4 + the value of BoxBarCount in ddraw.ini) for custom boxes. Remember to add your messages to intrface.msg and set up the font colours in ddraw.ini if you’re going to use custom boxes. Starting from sfall 4.1/3.8.12, is_iface_tag_active can also be used to check 0 for SNEAK, 1 for POISONED, and 2 for RADIATED. ", "url": "/sfall/tags/", "relUrl": "/tags/" - },"121": { + },"158": { "doc": "Tags", "title": "Functions", "content": ". | add_iface_tag | hide_iface_tag | is_iface_tag_active | set_iface_tag_text | show_iface_tag | . add_iface_tag . sfall.h . void add_iface_tag() . Adds one custom box to the current boxes, and returns the number of the added tag (-1 if the tags limit is exceeded. The maximum number of boxes is limited to 126 tags. hide_iface_tag . void hide_iface_tag(int tag) . is_iface_tag_active . int is_iface_tag_active(int tag) . set_iface_tag_text . sfall.h . void set_iface_tag_text(int tag, string text, int color) . Sets the text messages and colors for custom notification boxes to the interface without the need to add messages to intrface.msg and set up the font colors in ddraw.ini. Tag value is the same as used in show_iface_tag, hide_iface_tag, and is_iface_tag_active. The valid range is from 5 to (4 + the value of BoxBarCount in ddraw.ini) or the number of the last custom box added using the add_iface_tag function. The text is limited to 19 characters. show_iface_tag . void show_iface_tag(int tag) . ", "url": "/sfall/tags/#functions", "relUrl": "/tags/#functions" - },"122": { + },"159": { "doc": "Tiles and paths", "title": "Tiles and paths", "content": " ", "url": "/sfall/tiles-and-paths/", "relUrl": "/tiles-and-paths/" - },"123": { + },"160": { "doc": "Tiles and paths", "title": "Functions", "content": ". | get_tile_fid | get_tile_ground_fid | get_tile_roof_fid | obj_blocking_line | obj_blocking_tile | path_find_to | tile_by_position | tile_get_objs | tile_light | tile_refresh_display | tile_under_cursor | . get_tile_fid . int get_tile_fid(int tileData) . | Returns FID information about the square under the given tile at elevation 0 | Pass elevation as 4-bit number in bits 25-28 to access other elevations | Pass result mode in bits 29-32: 0 - ground FID, 1 - roof FID, 2 - raw data. | . get_tile_ground_fid . sfall.h . int get_tile_ground_fid(int tileNum, int elevation) . Returns FID of a ground tile at given tile number and elevation. get_tile_roof_fid . sfall.h . int get_tile_roof_fid(int tileNum, int elevation) . Returns FID of a roof tile at given tile number and elevation. Note that FID of 1 is used when there is no actual roof. obj_blocking_line . ObjectPtr obj_blocking_line(ObjectPtr objFrom, int tileTo, int blockingType) . Returns first object which blocks direct linear path from objFrom to tileTo using selected blocking function (see BLOCKING_TYPE_* constants in sfall.h). If path is clear (no blocker was encountered by selected function) - returns 0. objFrom is always excluded from calculations, but is required to be a valid object. obj_blocking_tile . ObjectPtr obj_blocking_tile(int tileNum, int elevation, int blockingType) . Returns first object blocking given tile using given blocking function or 0 if tile is clear. path_find_to . array path_find_to(ObjectPtr objFrom, int tileTo, int blockingType) . Returns the shortest path to a given tile using given blocking function as an array of tile directions (0..5) to move on each step. Array length equals to a number of steps. Empty array means that specified target cannot be reached. tile_by_position . sfall.h . int tile_by_position(int x, int y) . | returns the tile number at the x, y position relative to the top-left corner of the screen | if the position is outside of the range of tiles, it will return -1 | . tile_get_objs . array tile_get_objs(int tileNum, int elevation) . Returns an array of all objects at given tile. It will include any hidden, dead or system objects (like cursor), so make sure to check properly when iterating. tile_light . int tile_light(int elevation, int tileNum) . Returns light intensity at the given tile in range from 0 to 65535. tile_refresh_display . void tile_refresh_display() . Redraws the game scene (tiles, walls, objects, etc.). tile_under_cursor . int tile_under_cursor . ", "url": "/sfall/tiles-and-paths/#functions", "relUrl": "/tiles-and-paths/#functions" - },"124": { + },"161": { "doc": "Utility", "title": "Utility", "content": " ", "url": "/sfall/utility/", "relUrl": "/utility/" - },"125": { + },"162": { "doc": "Utility", "title": "Subcategories", "content": ". | Math | Strings | . ", "url": "/sfall/utility/#subcategories", "relUrl": "/utility/#subcategories" - },"126": { + },"163": { "doc": "Utility", "title": "Functions", "content": ". | atof | atoi | sprintf | typeof | . atof . float atof(string text) . atoi . int atoi(string text) . sprintf . string sprintf(string format, any value) . Formats given value using standart syntax of C printf function (google “printf” for format details). However, it is limited to formatting only 1 value. | Can be used to get character by ASCII code (“%c”). | . typeof . int typeof(any value) . Returns type of the given value: VALTYPE_INT, VALTYPE_FLOAT or VALTYPE_STR. ", "url": "/sfall/utility/#functions", "relUrl": "/utility/#functions" - },"127": { + },"164": { "doc": "Version", "title": "Version", "content": " ", "url": "/sfall/version/", "relUrl": "/version/" - },"128": { + },"165": { "doc": "Version", "title": "Functions", "content": ". | sfall_ver_build | sfall_ver_major | sfall_ver_minor | . sfall_ver_build . int sfall_ver_build() . sfall_ver_major . int sfall_ver_major() . sfall_ver_minor . int sfall_ver_minor() . ", "url": "/sfall/version/#functions", "relUrl": "/version/#functions" - },"129": { + },"166": { "doc": "Virtual file system", "title": "Virtual file system", "content": "The fs_* functions are used to manipulate a virtual file system. Files saved here should have paths relative to the data folder, and use backslashes as the directory separator. They will take precedence over files stored in the normal data folder. They will also be saved into save games if you set a flag for them using fs_resize(fileId, -1), so be avoid creating large files. Using fs_copy followed by fs_read_xxx, you can read the contents of existing files. ", "url": "/sfall/virtual-file-system/", "relUrl": "/virtual-file-system/" - },"130": { + },"167": { "doc": "Virtual file system", "title": "Functions", "content": ". | fs_copy | fs_create | fs_delete | fs_find | fs_pos | fs_read_byte | fs_read_float | fs_read_int | fs_read_short | fs_resize | fs_seek | fs_size | fs_write_bstring | fs_write_byte | fs_write_float | fs_write_int | fs_write_short | fs_write_string | . fs_copy . int fs_copy(string path, string source) . fs_create . int fs_create(string path, int size) . fs_delete . void fs_delete(int id) . fs_find . int fs_find(string path) . fs_pos . int fs_pos(int id) . fs_read_byte . int fs_read_byte(int id) . fs_read_float . float fs_read_float(int id) . fs_read_int . int fs_read_int(int id) . fs_read_short . int fs_read_short(int id) . fs_resize . void fs_resize(int id, int size) . fs_seek . void fs_seek(int id, int pos) . fs_size . int fs_size(int id) . fs_write_bstring . void fs_write_bstring(int id, string data) . fs_write_byte . void fs_write_byte(int id, int data) . fs_write_float . void fs_write_float(int id, int data) . fs_write_int . void fs_write_int(int id, int data) . fs_write_short . void fs_write_short(int id, int data) . fs_write_string . void fs_write_string(int id, string data) . ", "url": "/sfall/virtual-file-system/#functions", "relUrl": "/virtual-file-system/#functions" - },"131": { + },"168": { "doc": "Weapons and ammo", "title": "Weapons and ammo", "content": " ", "url": "/sfall/weapons-and-ammo/", "relUrl": "/weapons-and-ammo/" - },"132": { + },"169": { "doc": "Weapons and ammo", "title": "Functions", "content": ". | get_weapon_ammo_count | get_weapon_ammo_pid | set_weapon_ammo_count | set_weapon_ammo_pid | . get_weapon_ammo_count . int get_weapon_ammo_count(ObjectPtr weapon) . This also allows to get current charges of a misc item (Geiger counter, etc). get_weapon_ammo_pid . int get_weapon_ammo_pid(ObjectPtr weapon) . set_weapon_ammo_count . void set_weapon_ammo_count(ObjectPtr weapon, int count) . This also allows to set current charges of a misc item (Geiger counter, etc). set_weapon_ammo_pid . void set_weapon_ammo_pid(ObjectPtr weapon, int pid) . ", "url": "/sfall/weapons-and-ammo/#functions", "relUrl": "/weapons-and-ammo/#functions" - },"133": { + },"170": { "doc": "Windows and images", "title": "Windows and images", "content": " ", "url": "/sfall/windows-and-images/", "relUrl": "/windows-and-images/" - },"134": { + },"171": { "doc": "Windows and images", "title": "Functions", "content": ". | art_frame_data | create_win | draw_image | draw_image_scaled | get_window_attribute | get_window_under_mouse | interface_art_draw | interface_overlay | interface_print | message_box | set_window_flag | win_fill_color | . art_frame_data . sfall.h . array art_frame_data(string/int artFile/artId, int frame, int rotation) . | returns the dimensions of a given PCX or FRM frame as a temp array in the form [width, height] | artFile/artId: path to the PCX/FRM file (e.g. art\\\\inven\\\\5mmap.frm), or its FRM ID number (e.g. 0x7000026, see specification of the FID format) optional arguments: | frame: frame number, the first frame starts from zero | rotation: rotation to get the frame for, useful when reading FRM files by path | . create_win . sfall.h . void create_win(string winName, int x, int y, int width, int height, int flags) . flags argument is optional. Works just like vanilla CreateWin function, but creates a window with MoveOnTop flag if the flags argument is not specified, and allows to set additional flags for the created window. MoveOnTop flag allows the created window to be placed on top of the game interface. draw_image . sfall.h . void draw_image(string/int artFile/artId, int frame, int x, int y, bool noTransparent) . | displays the specified PCX or FRM image in the active window created by vanilla CreateWin or sfall’s create_win script function | artFile/artId: path to the PCX/FRM file (e.g. art\\\\inven\\\\5mmap.frm), or its FRM ID number (e.g. 0x7000026, see specification of the FID format) optional arguments: | frame: frame number, the first frame starts from zero | x/y: offset relative to the top-left corner of the window | noTransparent: pass True to display an image without transparent background | NOTE: to omit optional arguments starting from the right, call the functions with different sfall_funcX (e.g. sfall_func4(\"draw_image\", pathFile, frame, x, y)) | . draw_image_scaled . sfall.h . void draw_image_scaled(string/int artFile/artId, int frame, int x, int y, int width, int height) . | displays the specified PCX or FRM image in the active window created by vanilla CreateWin or sfall’s create_win script function | artFile/artId: path to the PCX/FRM file (e.g. art\\\\inven\\\\5mmap.frm), or its FRM ID number (e.g. 0x7000026, see specification of the FID format) optional arguments: | frame: frame number, the first frame starts from zero | x/y: offset relative to the top-left corner of the window | width/height: the new width/height to scale the image to. Pass -1 to either width or height to keep the aspect ratio when scaling | NOTE: to omit optional arguments starting from the right, call the functions with different sfall_funcX (e.g. sfall_func4(\"draw_image\", pathFile, frame, x, y)) | if called without x/y/width/height arguments, the image will be scaled to fit the window without transparent background | . get_window_attribute . int sfall_func1(\"get_window_attribute\", int winType) . Alternative form: int sfall_func2(\"get_window_attribute\", int winType, int attrType) Returns the attribute of the specified interface window by the attrType argument. | winType: the type number of the interface window (see WINTYPE_* constants in sfall.h) | attrType: 0 - checks and returns a value of 1 if the specified interface window is created by the game (same as without the argument) 1 - X position, 2 - Y position (relative to the top-left corner of the game screen) 3 - interface width size, 4 - interface height size 5 - window ID (to compare with the get_window_under_mouse function) -1 - returns an associative array of keys (left, top, right, bottom) and values that define the position of the window rectangle (use standard syntax to access array values, e.g. winRect.top, winRect.bottom) | returns -1 if the specified attribute cannot be obtained | . get_window_under_mouse . int get_window_under_mouse() . Returns the internal ID of the top-most window under mouse cursor. interface_art_draw . int sfall_func4(\"interface_art_draw\", int winType, string artFile/int artID, int x, int y) . int sfall_func4(\"interface_art_draw\", int winType, string artFile/int artID, int x, int y) int sfall_func5(\"interface_art_draw\", int winType, string artFile/int artID, int x, int y, int frame) int sfall_func6(\"interface_art_draw\", int winType, string artFile/int artID, int x, int y, int frame, array param) . | draws the specified PCX or FRM image in the game interface window, returns -1 on any error | winType: the type number of the interface window (see WINTYPE_* constants in sfall.h) this also takes the value of the flag (0x1000000) to prevent immediate redrawing of the interface window | artFile/artId: path to the PCX/FRM file (e.g. art\\\\inven\\\\5mmap.frm), or its FRM ID number (e.g. 0x7000026, see specification of the FID format) | x/y: offset relative to the top-left corner of the window | . optional arguments: . | frame: frame number, the first frame starts from zero | param: an array which specifies additional parameters, where: index 0 - sprite direction for multi-directional FRM index 1/index 2 - the new width/height to scale the image to. Pass -1 to use the original width/height | . interface_overlay . sfall_func2(\"interface_overlay\", int winType, int mode) . Alternative form: int sfall_func6(\"interface_overlay\", int winType, 2, int x, int y, int width, int height). Creates an additional drawing surface above the graphic layer of the specified interface window. All subsequent calls of interface_art_draw and interface_print functions will draw on it. | winType: the type number of the interface window (see WINTYPE_* constants in sfall.h) | mode: 1 - creates a new overlay surface 2 - clears the overlay area or the specified rectangle defined by the x, y, width, height arguments 0 - destroys the created overlay surface (frees up the memory allocated to the surface) | . interface_print . int sfall_func5(\"interface_print\", string text, int winType, int x, int y, int color) . int sfall_func5(\"interface_print\", string text, int winType, int x, int y, int color) int sfall_func6(\"interface_print\", string text, int winType, int x, int y, int color, int width) . | displays the text in the specified interface window with the current font. Use vanilla SetFont function to set the font | returns the count of lines printed, or -1 on any error | text: the text to be printed. Use the \\n control character to move text to a new line (example: “Hello\\nWorld!”) | winType: the type number of the interface window (see WINTYPE_* constants in sfall.h) | x/y: offset relative to the top-left corner of the window | color: the color index in the game palette. Pass 0 if the text color was previously set by vanilla SetTextColor function It can also take additional flags (via bwor) for displaying text: . | 0x0010000 - adds a shadow to the text, the ‘textshadow’ compiler constant | 0x1000000 - prevents immediate redrawing of the interface window, the textdirect compiler constant (works the other way around) | 0x2000000 - fills the background of the text with black color, the textnofill compiler constant (works the other way around) | . | width (optional): the maximum width of the text. The text will be wrapped to fit within the specified width | . message_box . int sfall_func4(\"message_box\", string message, int flags, int color1, int color2) . Creates a dialog box with text and returns the result of pressing the button: 0 - No (Escape), 1 - Yes/Done (Enter). Returns -1 if for some reason the dialog box cannot be created. - message: the text in the dialog box. Use the `\\n` control character to move text to a new line (example: \"Hello\\nWorld!\") optional arguments: - flags: mode flags (see `MSGBOX_*` constants in define_extra.h). Pass -1 to skip setting the flags (default flags are NORMAL and YESNO) - color1/color2: the color index in the game palette. `color1` sets the text color for the first line, and `color2` for all subsequent lines of text (default color is 145) . set_window_flag . sfall.h . void set_window_flag(string winName/int winID, int flag, bool value) . Changes the specified flag for the created script or game interface window. | winName: the window name, assigned to the window by the CreateWin/create_win function | winID: the ID number of the interface or script window obtained with the get_window_under_mouse function, or 0 for the current game interface | flag: the flag to change (see WIN_FLAG_* constants in define_extra.h) | value: True - set the flag, False - unset the flag | . win_fill_color . int win_fill_color(int x, int y, int width, int height, int color) . Fills the rectangle area of the currently selected script window with the specified color, or clears the window with transparent (index 0) color (call the function without arguments). | color: the color index in the game palette (from 0 to 255) | . ", "url": "/sfall/windows-and-images/#functions", "relUrl": "/windows-and-images/#functions" - },"135": { + },"172": { "doc": "Worldmap", "title": "Worldmap", "content": "The mapper manual lists the functions world_map_x_pos and world_map_y_pos, which supposedly return the player’s x and y positions on the world map. get_world_map_x/y_pos are included here anyway, because I was unable to get those original functions to work, or even to find any evidence that they existed in game. ", "url": "/sfall/worldmap/", "relUrl": "/worldmap/" - },"136": { + },"173": { "doc": "Worldmap", "title": "Functions", "content": ". | get_world_map_x_pos | get_world_map_y_pos | set_world_map_pos | . get_world_map_x_pos . int get_world_map_x_pos() . get_world_map_y_pos . int get_world_map_y_pos() . set_world_map_pos . void set_world_map_pos(int x, int y) . ", "url": "/sfall/worldmap/#functions", "relUrl": "/worldmap/#functions" - },"137": { + },"174": { "doc": "write_xxx", "title": "write_xxx", "content": "These functions take a memory address as the parameter and can write to arbitrary pieces of Fallout’s address None of these functions will work unless AllowUnsafeScripting is enabled in ddraw.ini. ", "url": "/sfall/write_xxx/", "relUrl": "/write_xxx/" - },"138": { + },"175": { "doc": "write_xxx", "title": "Functions", "content": ". | write_byte | write_int | write_short | write_string | . write_byte . UNSAFE . void write_byte(int address, int value) . write_int . UNSAFE . void write_int(int address, int value) . write_short . UNSAFE . void write_short(int address, int value) . write_string . UNSAFE . void write_string(int address, string value) . ", diff --git a/feed.xml b/feed.xml index 2006f30a..7cafcd99 100644 --- a/feed.xml +++ b/feed.xml @@ -1 +1 @@ -Jekyll2024-07-19T11:36:49+00:00/sfall/feed.xmlsfallSfall documentation \ No newline at end of file +Jekyll2024-07-19T11:47:02+00:00/sfall/feed.xmlsfallSfall documentation \ No newline at end of file diff --git a/hook-types/index.html b/hook-types/index.html index 61ad427a..b86b66e6 100644 --- a/hook-types/index.html +++ b/hook-types/index.html @@ -1,4 +1,4 @@ - Hook types | sfall Skip to main content Link Menu Expand (external link) Document Search Copy Copied

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 - object type, BB - animation code (always 0 in this case), C - weapon code, DDD - FRM index in LST file.

int     arg0 - the vanilla FID calculated by the engine according to critter base FID and armor/weapon being used
+             Hook types | sfall                        Skip to main content   Link      Menu      Expand       (external link)    Document      Search       Copy       Copied       
   
 This site uses Just the Docs, a documentation theme for Jekyll. 
 
 
  
  
 
 
  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 - object type, BB - animation code (always 0 in this case), C - weapon code, DDD - FRM index in LST file.
 
int     arg0 - the vanilla FID calculated by the engine according to critter base FID and armor/weapon being used
 int     arg1 - the modified FID calculated by the internal sfall code (like Hero Appearance Mod)
 
 int     ret0 - overrides the calculated FID with provided value
@@ -53,12 +53,17 @@ Item    arg3 - the second choice of weapon
 Critter arg4 - the target of the critter (can be 0)
 
 Item    ret0 - overrides the chosen best weapon
-
 
  BuildSfxWeapon 
 
HOOK_BUILDSFXWEAPON (hs_buildsfxweapon.int)
 
Runs before each weapon sound effect is played or put in the animation queue to determine the name of sound effect file based on the weapon, target and action being performed.
 
int     arg0 - weapon sound effect type: 0 - ready/reload, 1 - attack, 2 - out of ammo, 3 - flying (for projectile weapons), 4 - hit
+
 
  BuildSfxWeapon 
 
HOOK_BUILDSFXWEAPON (hs_buildsfxweapon.int)
 
Runs before each weapon sound effect is played or added to the animation queue to determine the name of the sound effect file based on the weapon, target, and action being performed.
 
int     arg0 - weapon sound effect type:
+        0 - ready/reload
+        1 - attack
+        2 - out of ammo
+        3 - flying (for projectiles from weapons)
+        4 - hit
 Item    arg1 - the weapon being used
 int     arg2 - attack type (see ATKTYPE_* constants)
-Obj     arg3 - target of the attack (can be 0)
+Obj     arg3 - the target of the attack (can be 0)
 
-String  ret0 - the new sound file name to use, without extension (relative to "sound\sfx" path)
+String  ret0 - the filename of the new sound effect to use, without extension (relative to the sound\sfx\ directory)
 
 
  CalcAPCost 
 
HOOK_CALCAPCOST (hs_calcapcost.int)
 
Runs whenever Fallout calculates the AP cost of using an active item in hand (or unarmed attack). Doesn’t run for 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 arg0 - The critter performing the action
 int     arg1 - Attack Type (see ATKTYPE_* constants)
 int     arg2 - Is aimed attack (1 or 0)
@@ -72,357 +77,271 @@ int     arg2 - attack type (see ATKTYPE_* constants)
 int     arg3 - original result of engine function: 1 - can use, 0 - cannot use
 
 int     ret0 - overrides the result of engine function. Any non-zero value allows using the weapon
-
-## CarTravel
-
-`HOOK_CARTRAVEL` (hs_cartravel.int)
-
-Runs continuously during world map travel by car.
-
-
 
int arg0 - vanilla car speed (between 3 and 8 “steps”) int arg1 - vanilla fuel consumption (100 and below)
 
int ret0 - car speed override (pass -1 if you just want to override fuel consumption) int ret1 - 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 arg0 - The target Critter arg1 - The attacker int arg2 - The amount of damage to the target int arg3 - The amount of damage to the attacker int arg4 - The special effect flags for the target (use bwand DAM_* to check specific flags) int arg5 - The special effect flags for the attacker (use bwand DAM_* to check specific flags) Item arg6 - The weapon used in the attack int arg7 - The bodypart that was struck int arg8 - 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 arg9 - Number of bullets actually hit the target (1 for melee attacks) int arg10 - The amount of knockback to the target int arg11 - Attack Type (see ATKTYPE_* constants) mixed arg12 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)
 
int ret0 - The damage to the target int ret1 - The damage to the attacker int ret2 - The special effect flags for the target int ret3 - The special effect flags for the attacker int ret4 - The amount of knockback to the target
 

-## CombatTurn
-
-`HOOK_COMBATURN` (hs_combatturn.int)
-
-Runs before and after each turn in combat (for both PC and NPC).
-
-
 
int arg0 - 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) Critter arg1 - critter doing the turn int arg2 - 1 at the start/end of the player’s turn after loading a game saved in combat mode, 0 otherwise
 
int ret0 - 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.
-
-Does not run for critters in the knockdown/out state.
-
-
 
int arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed) Critter arg1 - The attacker Critter arg2 - The target int arg3 - The amount of damage int arg4 - Unused, always -1. Use this if you are using the same procedure for HOOK_DEATHANIM1 and HOOK_DEATHANIM2 (since sfall 4.1/3.8.24)
 
int ret0 - 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 `HOOK_DEATHANIM1`, but performs no validation.<br>
-When using `critter_dmg` function, this script will also run. In that case weapon pid will be -1 and attacker will point to an object with `obj_art_fid == 0x20001F5`.
-
-Does not run for critters in the knockdown/out state.
-
-
 
int arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed) Critter arg1 - The attacker Critter arg2 - The target int arg3 - The amount of damage int arg4 - The death anim id calculated by Fallout
 
int ret0 - 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, these hooks are not thoroughly supported in sfall, and may be removed in future versions.<br>
-If you want to check if some tile or path is blocked, use functions: `obj_blocking_tile`, `obj_blocking_line`, `path_find_to`.<br>
-If you want script to be called every time NPC moves by hex in combat, use `HOOK_MOVECOST` hook.
-
-
 
Critter arg0 - the critter doing the moving int arg1 - the tile number being checked int arg2 - the elevation being checked int arg3 - 1 if the hex would normally be blocking
 
Obj ret0 - 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 the description of an object. You can override the description text.
-An example usage would be to add an additional description to the item based on player's stats/skills.
-
-Does not run if the script of the object overrides the description.
-
-__NOTE:__ Returning a pointer to the new text received from the `get_string_pointer` function is still valid, but the method is DEPRECATED and is left for backward compatibility only.
-
-
 
Obj arg0 - the object
 
String ret0 - the new description text to use
 

-## Encounter
-
-`HOOK_ENCOUNTER` (hs_encounter.int)
-
-Runs whenever a random encounter occurs (except the Horrigan meeting and scripted encounters), or when the player enters a local map from the world map.
-You can override the map for loading or the encounter.
-
-
 
int arg0 - event type: 0 - when a random encounter occurs, 1 - when the player enters from the world map int arg1 - the map ID that the encounter will load (see MAPS.h or Maps.txt) int arg2 - 1 when the encounter occurs is a special encounter, 0 otherwise int arg3 - encounter table number, or -1 if not an encounter int arg4 - encounter index in the table, or -1 if not an encounter
 
int ret0 - overrides the map ID, or pass -1 for event type 0 to cancel the encounter and continue traveling int ret1 - pass 1 to cancel the encounter and load the specified map from the ret0 (only for event type 0)
 

-## ExplosiveTimer
-
-`HOOK_EXPLOSIVETIMER` (hs_explosivetimer.int)
-
-Runs after setting the explosive timer. You can override the result.
-
-
 
int arg0 - the time in ticks set in the timer Obj arg1 - the explosive object int arg2 - the result of engine calculation of whether the timer was set successfully: 1 - failure, 2 - success (similar to ROLL_* in Condtion.h)
 
int ret0 - overrides the time of the timer (maximum 18000 ticks) int ret1 - 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.<br>
-This hook replaces that sorting function, allowing you to sort the targets in some arbitrary way.
-
-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, but this is fixed in sfall 4.2.3/3.8.23.
-Use `set_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 or pass -1 to skip the return value.
-
-__NOTE:__ The engine can choose targets by the following criteria:
-1) The nearest enemy to the attacker.
-2) The enemy that attacked the attacker.
-3) The enemy that attacked an NPC from the same team as the attacker.
-4) The enemy that is attacked by an NPC from the same team as the attacker.
-
-
 
Critter arg0 - The attacker Critter arg1 - A possible target Critter arg2 - A possible target Critter arg3 - A possible target Critter arg4 - A possible target
 
Critter ret0 - The first choice of target Critter ret1 - The second choice of target Critter ret2 - The third choice of target Critter ret3 - 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 arg0 - event type: 1 - when the player exits the game, 0 - otherwise int arg1 - the previous game mode
 

-## InvenWield
-
-`HOOK_INVENWIELD` (hs_invenwield.int)
-
-Runs before causing a critter or the player to wield/unwield an armor or a weapon (except when using the 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 arg0 - critter Item arg1 - item being wielded or unwielded (weapon/armor) int arg2 - slot (INVEN_TYPE_*) int arg3 - 1 when wielding, 0 when unwielding int arg4 - 1 when removing an equipped item from inventory, 0 otherwise
 
int ret0 - 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 arg0 - 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 arg1 - Item being moved Item arg2 - Item being replaced, weapon being reloaded, or container being filled (can be 0)
 
int ret0 - Override setting (-1 - use engine handler, any other value - prevent relocation of item/reloading weapon/picking up item)
 

-Notes for the event of dropping items on the ground:
-- the event is called for each item when dropping multiple items from the stack
-- for ammo type items, the number of dropped ammo in a pack can be found by using the `get_weapon_ammo_count` function
-- for the `PID_BOTTLE_CAPS` item, the event is called only once, and the number of dropped units can be found from the value of the `OBJ_DATA_CUR_CHARGES` object field (or with the `get_weapon_ammo_count` function)
-
-## ItemDamage
-
-`HOOK_ITEMDAMAGE` (hs_itemdamage.int)
-
-Runs when retrieving the damage rating of the player's used weapon. (Which may be their fists.)
-
-
 
int arg0 - The default min damage int arg1 - The default max damage Item arg2 - The weapon used (0 if unarmed) Critter arg3 - The critter doing the attacking int arg4 - The type of attack int arg5 - non-zero if this is an attack using a melee weapon
 
int ret0 - Either the damage to be used, if ret1 isn’t given, or the new minimum damage if it is int ret1 - The new maximum damage
 

-## KeyPress
-
-`HOOK_KEYPRESS` (hs_keypress.int)
-
-Runs once every time when any key was pressed or released.
-* DX codes: see **dik.h** header or https://kippykip.com/b3ddocs/commands/scancodes.htm
-* [VK codes](http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)
-
-__NOTE:__ If you want to override a key, the new key DX scancode should be the same for both pressed and released events.
-
-
 
int arg0 - event type: 1 - pressed, 0 - released int arg1 - key DX scancode int arg2 - key VK code (very similar to ASCII codes)
 
int ret0 - 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 released.
-
-
 
int arg0 - event type: 1 - pressed, 0 - released int arg1 - button number (0 - left, 1 - right, up to 7)
 

-## MoveCost
-
-`HOOK_MOVECOST` (hs_movecost.int)
-
-Runs when calculating the AP cost of movement.
-
-
 
Critter arg0 - the critter doing the moving int arg1 - the number of hexes being moved int arg2 - the original AP cost
 
int ret0 - 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 arg0 - 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 arg0 - event type: 1 - when checking objects within the explosion radius without causing damage (e.g. the player drops an active explosive), 0 - otherwise Critter arg1 - the attacker int arg2 - the tile on which the explosion occurs int arg3 - checked tile within the explosion radius Obj arg4 - first found object on the checked tile as an additional target Critter arg5 - the target critter, may be 0 or equal to the attacker int arg6 - 1 when using throwing weapons (e.g. grenades), 0 otherwise
 
int ret0 - 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 arg0 - the owner that the object is being removed from Item arg1 - the item that is being removed int arg2 - the number of items to remove int arg3 - The reason the object is being removed (see RMOBJ_* constants) Obj arg4 - The destination object when the item is moved to another object, 0 otherwise
 

-## RestTimer
-
-`HOOK_RESTTIMER` (hs_resttimer.int)
-
-Runs continuously while the player is resting (using pipboy alarm clock).
-
-
 
int arg0 - the game time in ticks int arg1 - event type: 1 - when the resting ends normally, -1 - when pressing ESC to cancel the timer, 0 - otherwise int arg2 - the hour part of the length of resting time int arg3 - the minute part of the length of resting time
 
int ret0 - pass 1 to interrupt the resting, pass 0 to continue the rest if it was interrupted by pressing ESC key
 

-## RollCheck
-
-`HOOK_ROLLCHECK` (hs_rollcheck.int)
-
-Runs when a game event performs a random roll to check the chance of success or failure.
-
-
 
int arg0 - event type: 1 - checks the chance of an attack hitting the target 2 - checks the chance of a bullet from a burst hitting the target (for burst attacks) 3 - checks the chance when using skills (not listed below) 4 - check the chance of using Repair skill 5 - check the chance of using Doctor skill 6 - check the chance of using Steal skill for the thief (usually the player) 7 - the second Steal skill chance check for the target to catch the thief, in which the target’s failure is the thief’s success result int arg1 - the value of roll result (see ROLL_* constants), which is calculated as: for ROLL_CRITICAL_SUCCESS: random(1, 100) <= (random_chance / 10) + bonus for ROLL_CRITICAL_FAILURE: random(1, 100) <= -random_chance / 10 int arg2 - the chance value int arg3 - the bonus value, used when checking critical success int arg4 - random chance (calculated as: chance - random(1, 100)), where a negative value is a failure check (ROLL_FAILURE)
 
int ret0 - overrides the roll result
 

-## SetGlobalVar
-
-`HOOK_SETGLOBALVAR` (hs_setglobalvar.int)
-
-Runs when setting the value of a global variable.
-
-
 
int arg0 - the index number of the global variable being set int arg1 - the set value of the global variable
 
int ret0 - 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 arg0 - the object being set, or -1 when setting the light level for a map int arg1 - the light intensity int arg2 - the light radius, or -1 when setting the light level for a map
 
int ret0 - overrides the light intensity. Intensity range is from 0 to 65536 int ret1 - 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 arg0 - Sneak check result: 1 - success, 0 - failure int arg1 - the duration in ticks for the current Sneak check (time depends on Sneak skill level) Critter arg2 - the critter (usually dude_obj)
 
int ret0 - overrides the result of the Sneak check int ret1 - overrides the duration time for the current result
 

-## StdProcedure
-
-`HOOK_STDPROCEDURE` (hs_stdprocedure.int)
-
-Runs before Fallout executes a standard procedure (handler) in any script of any object.
-NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures.
-
-
 
int arg0 - the number of the standard script handler (see *_proc in define.h) Obj arg1 - the object that owns this handler (self_obj) Obj arg2 - the object that called this handler (source_obj, can be 0) int arg3 - always 0 (1 for _END version) Obj arg4 - the object that is acted upon by this handler (target_obj, can be 0) int arg5 - the parameter of this call (fixed_param), useful for combat_proc
 
int ret0 - pass -1 to cancel the execution of the handler
 

-## StdProcedureEnd
-
-`HOOK_STDPROCEDURE_END` (hs_stdprocedure.int)
-
-Runs after Fallout executes a standard procedure (handler) in any script of any object.
-NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures.
-
-
 
int arg0 - the number of the standard script handler (see *_proc in define.h) Obj arg1 - the object that owns this handler (self_obj) Obj arg2 - the object that called this handler (source_obj, can be 0) int arg3 - always 1 (procedure end) Obj arg4 - the object that is acted upon by this handler (target_obj, can be 0) int arg5 - the parameter of this call (fixed_param), useful for combat_proc
 

-## 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):<br>
-`display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg3 * 2), obj_name(arg2)));`
-
-
 
Critter arg0 - Thief Obj arg1 - The target Item arg2 - The item being stolen/planted int arg3 - 0 when stealing, 1 when planting int arg4 - quantity of the item being stolen/planted
 
int ret0 - overrides hard-coded handler (2 - force fail without closing window, 1 - force success, 0 - force fail, -1 - use engine handler) int ret1 - overrides experience points gained for stealing this item (must be greater than or equal to 0)
 

-## 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 arg0 - the attacker Critter arg1 - the target Item arg2 - the weapon used in the attack int arg3 - attack type (see ATKTYPE_* constants) int arg4 - number of bullets actually hit the target (1 for melee attacks) int arg5 - target’s Damage Resistance (DR) value (affected by critical hit effects, perks, traits, and special unarmed attacks) int arg6 - target’s Damage Threshold (DT) value (affected by critical hit effects, perks, traits, and special unarmed attacks) int arg7 - bonus ranged damage from the perk int arg8 - 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 arg9 - combat difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it’s always 100) int arg10 - the calculated amount of damage (usually 0, required when using multiple hook scripts to calculate damage and using the set_sfall_arg function) mixed arg11 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)
 
int ret0 - the returned amount of damage
 

-## TargetObject
-
-`HOOK_TARGETOBJECT` (hs_targetobject.int)
-
-Runs when the targeting cursor hovers over an object, or when the player tries to attack the target object.
-You can override the target object or prevent the player from attacking the chosen target.
-
-
 
int arg0 - event type: 0 - when the targeting cursor hovers over the object, 1 - when trying to attack the target object int arg1 - 1 when the target object is valid to attack, 0 otherwise Obj arg2 - the target object
 
mixed ret0 - overrides the target object, or pass -1 to prevent the player from attacking the object
 

-## ToHit
-
-`HOOK_TOHIT` (hs_tohit.int)
-
-Runs when Fallout is calculating the chances of an attack striking a target.<br>
-Runs after the hit chance is fully calculated normally, including applying the 95% cap.
-
-
 
int arg0 - The hit chance (capped) Critter arg1 - The attacker Critter arg2 - The target of the attack int arg3 - The targeted bodypart int arg4 - Source tile (may differ from attacker’s tile, when AI is considering potential fire position) int arg5 - Attack Type (see ATKTYPE_* constants) int arg6 - Ranged flag. 1 if the hit chance calculation takes into account the distance to the target. This does not mean the attack is a ranged attack int arg7 - The raw hit chance before applying the cap
 
int ret0 - The new hit chance. The value is limited to the range of -99 to 999
 

-## 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 arg0 - the critter that uses an object (usually dude_obj) Obj arg1 - the object being used int arg2 - the animation code being used (see ANIM_* in Animcomd.h)
 
int ret0 - 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 arg0 - The user Obj arg1 - The object used
 
int ret0 - 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)
-1. 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.
-1. 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 arg0 - The target Critter arg1 - The user int arg2 - The object used
 
int ret0 - 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.
-
-Does not run if the script of the object calls `script_overrides` for using the skill.
-
-
 
Critter arg0 - The user critter Obj arg1 - The target object int arg2 - skill being used int arg3 - skill bonus from items such as first aid kits
 
int ret0 - overrides hard-coded handler (-1 - use engine handler, any other value - override; if it is 0, there will be a 10% chance of removing the used medical item)
 

-## 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 arg0 - the user critter (usually dude_obj) Obj arg1 - the target object/critter int arg2 - skill being used
 
int ret0 - a new critter to override the user critter. Pass -1 to cancel the skill use, pass 0 to skip this return value int ret1 - pass 1 to allow the skill to be used in combat (only for dude_obj or critter being controlled by the player)
 

-## WithinPerception
-
-`HOOK_WITHINPRECEPTION` (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.<br>
-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.<br>
-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 arg0 - Watcher object Obj arg1 - Target object int arg2 - Result of vanilla function: 1 - within perception range, 0 - otherwise int arg3 - 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) 3 - when AI determines whether it sees a potential target when selecting attack targets 0 - all other cases
 
int ret0 - 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 script function which is called by every critter in the game) ```
 
 
 
 
 
  
+

CarTravel

HOOK_CARTRAVEL (hs_cartravel.int)

Runs continuously during world map travel by car.

int     arg0 - vanilla car speed (between 3 and 8 "steps")
+int     arg1 - vanilla fuel consumption (100 and below)
+
+int     ret0 - car speed override (pass -1 if you just want to override fuel consumption)
+int     ret1 - 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 arg0  - The target
+Critter arg1  - The attacker
+int     arg2  - The amount of damage to the target
+int     arg3  - The amount of damage to the attacker
+int     arg4  - The special effect flags for the target (use bwand DAM_* to check specific flags)
+int     arg5  - The special effect flags for the attacker (use bwand DAM_* to check specific flags)
+Item    arg6  - The weapon used in the attack
+int     arg7  - The bodypart that was struck
+int     arg8  - 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     arg9 - Number of bullets actually hit the target (1 for melee attacks)
+int     arg10 - The amount of knockback to the target
+int     arg11 - Attack Type (see ATKTYPE_* constants)
+mixed   arg12 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)
+
+int     ret0 - The damage to the target
+int     ret1 - The damage to the attacker
+int     ret2 - The special effect flags for the target
+int     ret3 - The special effect flags for the attacker
+int     ret4 - The amount of knockback to the target
+

CombatTurn

HOOK_COMBATURN (hs_combatturn.int)

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

int     arg0 - 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)
+Critter arg1 - critter doing the turn
+int     arg2 - 1 at the start/end of the player's turn after loading a game saved in combat mode, 0 otherwise
+
+int     ret0 - 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.

Does not run for critters in the knockdown/out state.

int     arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
+Critter arg1 - The attacker
+Critter arg2 - The target
+int     arg3 - The amount of damage
+int     arg4 - Unused, always -1. Use this if you are using the same procedure for HOOK_DEATHANIM1 and HOOK_DEATHANIM2 (since sfall 4.1/3.8.24)
+
+int     ret0 - 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 HOOK_DEATHANIM1, but performs no validation.
When using critter_dmg function, this script will also run. In that case weapon pid will be -1 and attacker will point to an object with obj_art_fid == 0x20001F5.

Does not run for critters in the knockdown/out state.

int     arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
+Critter arg1 - The attacker
+Critter arg2 - The target
+int     arg3 - The amount of damage
+int     arg4 - The death anim id calculated by Fallout
+
+int     ret0 - 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, these hooks are not thoroughly supported in sfall, and 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 HOOK_MOVECOST hook.

Critter arg0 - the critter doing the moving
+int     arg1 - the tile number being checked
+int     arg2 - the elevation being checked
+int     arg3 - 1 if the hex would normally be blocking
+
+Obj     ret0 - 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 the description of an object. You can override the description text. An example usage would be to add an additional description to the item based on player’s stats/skills.

Does not run if the script of the object overrides the description.

NOTE: Returning a pointer to the new text received from the get_string_pointer function is still valid, but the method is DEPRECATED and is left for backward compatibility only.

Obj     arg0 - the object
+
+String  ret0 - the new description text to use
+

Encounter

HOOK_ENCOUNTER (hs_encounter.int)

Runs whenever a random encounter occurs (except the Horrigan meeting and scripted encounters), or when the player enters a local map from the world map. You can override the map for loading or the encounter.

int     arg0 - event type: 0 - when a random encounter occurs, 1 - when the player enters from the world map
+int     arg1 - the map ID that the encounter will load (see MAPS.h or Maps.txt)
+int     arg2 - 1 when the encounter occurs is a special encounter, 0 otherwise
+int     arg3 - encounter table number, or -1 if not an encounter
+int     arg4 - encounter index in the table, or -1 if not an encounter
+
+int     ret0 - overrides the map ID, or pass -1 for event type 0 to cancel the encounter and continue traveling
+int     ret1 - pass 1 to cancel the encounter and load the specified map from the ret0 (only for event type 0)
+

ExplosiveTimer

HOOK_EXPLOSIVETIMER (hs_explosivetimer.int)

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

int     arg0 - the time in ticks set in the timer
+Obj     arg1 - the explosive object
+int     arg2 - the result of engine calculation of whether the timer was set successfully: 1 - failure, 2 - success (similar to ROLL_* in Condtion.h)
+
+int     ret0 - overrides the time of the timer (maximum 18000 ticks)
+int     ret1 - 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.

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, but this is fixed in sfall 4.2.3/3.8.23. Use set_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 or pass -1 to skip the return value.

NOTE: The engine can choose targets by the following criteria: 1) The nearest enemy to the attacker. 2) The enemy that attacked the attacker. 3) The enemy that attacked an NPC from the same team as the attacker. 4) The enemy that is attacked by an NPC from the same team as the attacker.

Critter arg0 - The attacker
+Critter arg1 - A possible target
+Critter arg2 - A possible target
+Critter arg3 - A possible target
+Critter arg4 - A possible target
+
+Critter ret0 - The first choice of target
+Critter ret1 - The second choice of target
+Critter ret2 - The third choice of target
+Critter ret3 - 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     arg0 - event type: 1 - when the player exits the game, 0 - otherwise
+int     arg1 - the previous game mode
+

InvenWield

HOOK_INVENWIELD (hs_invenwield.int)

Runs before causing a critter or the player to wield/unwield an armor or a weapon (except when using the 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 arg0 - critter
+Item    arg1 - item being wielded or unwielded (weapon/armor)
+int     arg2 - slot (INVEN_TYPE_*)
+int     arg3 - 1 when wielding, 0 when unwielding
+int     arg4 - 1 when removing an equipped item from inventory, 0 otherwise
+
+int     ret0 - 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     arg0 - 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    arg1 - Item being moved
+Item    arg2 - Item being replaced, weapon being reloaded, or container being filled (can be 0)
+
+int     ret0 - Override setting (-1 - use engine handler, any other value - prevent relocation of item/reloading weapon/picking up item)
+

Notes for the event of dropping items on the ground:

  • the event is called for each item when dropping multiple items from the stack
  • for ammo type items, the number of dropped ammo in a pack can be found by using the get_weapon_ammo_count function
  • for the PID_BOTTLE_CAPS item, the event is called only once, and the number of dropped units can be found from the value of the OBJ_DATA_CUR_CHARGES object field (or with the get_weapon_ammo_count function)

ItemDamage

HOOK_ITEMDAMAGE (hs_itemdamage.int)

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

int     arg0 - The default min damage
+int     arg1 - The default max damage
+Item    arg2 - The weapon used (0 if unarmed)
+Critter arg3 - The critter doing the attacking
+int     arg4 - The type of attack
+int     arg5 - non-zero if this is an attack using a melee weapon
+
+int     ret0 - Either the damage to be used, if ret1 isn't given, or the new minimum damage if it is
+int     ret1 - The new maximum damage
+

KeyPress

HOOK_KEYPRESS (hs_keypress.int)

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

  • DX codes: see dik.h header or https://kippykip.com/b3ddocs/commands/scancodes.htm
  • VK codes

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

int     arg0 - event type: 1 - pressed, 0 - released
+int     arg1 - key DX scancode
+int     arg2 - key VK code (very similar to ASCII codes)
+
+int     ret0 - 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 released.

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

MoveCost

HOOK_MOVECOST (hs_movecost.int)

Runs when calculating the AP cost of movement.

Critter arg0 - the critter doing the moving
+int     arg1 - the number of hexes being moved
+int     arg2 - the original AP cost
+
+int     ret0 - 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 arg0 - 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     arg0 - event type: 1 - when checking objects within the explosion radius without causing damage (e.g. the player drops an active explosive), 0 - otherwise
+Critter arg1 - the attacker
+int     arg2 - the tile on which the explosion occurs
+int     arg3 - checked tile within the explosion radius
+Obj     arg4 - first found object on the checked tile as an additional target
+Critter arg5 - the target critter, may be 0 or equal to the attacker
+int     arg6 - 1 when using throwing weapons (e.g. grenades), 0 otherwise
+
+int     ret0 - 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     arg0 - the owner that the object is being removed from
+Item    arg1 - the item that is being removed
+int     arg2 - the number of items to remove
+int     arg3 - The reason the object is being removed (see RMOBJ_* constants)
+Obj     arg4 - The destination object when the item is moved to another object, 0 otherwise
+

RestTimer

HOOK_RESTTIMER (hs_resttimer.int)

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

int     arg0 - the game time in ticks
+int     arg1 - event type: 1 - when the resting ends normally, -1 - when pressing ESC to cancel the timer, 0 - otherwise
+int     arg2 - the hour part of the length of resting time
+int     arg3 - the minute part of the length of resting time
+
+int     ret0 - pass 1 to interrupt the resting, pass 0 to continue the rest if it was interrupted by pressing ESC key
+

RollCheck

HOOK_ROLLCHECK (hs_rollcheck.int)

Runs when a game event performs a random roll to check the chance of success or failure.

int     arg0 - event type:
+               1 - checks the chance of an attack hitting the target
+               2 - checks the chance of a bullet from a burst hitting the target (for burst attacks)
+               3 - checks the chance when using skills (not listed below)
+               4 - check the chance of using Repair skill
+               5 - check the chance of using Doctor skill
+               6 - check the chance of using Steal skill for the thief (usually the player)
+               7 - the second Steal skill chance check for the target to catch the thief, in which the target's failure is the thief's success result
+int     arg1 - the value of roll result (see ROLL_* constants), which is calculated as:
+               for ROLL_CRITICAL_SUCCESS: random(1, 100) <= (random_chance / 10) + bonus
+               for ROLL_CRITICAL_FAILURE: random(1, 100) <= -random_chance / 10
+int     arg2 - the chance value
+int     arg3 - the bonus value, used when checking critical success
+int     arg4 - random chance (calculated as: chance - random(1, 100)), where a negative value is a failure check (ROLL_FAILURE)
+
+int     ret0 - overrides the roll result
+

SetGlobalVar

HOOK_SETGLOBALVAR (hs_setglobalvar.int)

Runs when setting the value of a global variable.

int     arg0 - the index number of the global variable being set
+int     arg1 - the set value of the global variable
+
+int     ret0 - 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     arg0 - the object being set, or -1 when setting the light level for a map
+int     arg1 - the light intensity
+int     arg2 - the light radius, or -1 when setting the light level for a map
+
+int     ret0 - overrides the light intensity. Intensity range is from 0 to 65536
+int     ret1 - 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     arg0 - Sneak check result: 1 - success, 0 - failure
+int     arg1 - the duration in ticks for the current Sneak check (time depends on Sneak skill level)
+Critter arg2 - the critter (usually dude_obj)
+
+int     ret0 - overrides the result of the Sneak check
+int     ret1 - overrides the duration time for the current result
+

StdProcedure

HOOK_STDPROCEDURE (hs_stdprocedure.int)

Runs before Fallout executes a standard procedure (handler) in any script of any object. NOTE: this hook will not be executed for start, critter_p_proc, timed_event_p_proc, and map_update_p_proc procedures.

int     arg0 - the number of the standard script handler (see *_proc in define.h)
+Obj     arg1 - the object that owns this handler (self_obj)
+Obj     arg2 - the object that called this handler (source_obj, can be 0)
+int     arg3 - always 0 (1 for _END version)
+Obj     arg4 - the object that is acted upon by this handler (target_obj, can be 0)
+int     arg5 - the parameter of this call (fixed_param), useful for combat_proc
+
+int     ret0 - pass -1 to cancel the execution of the handler
+

StdProcedureEnd

HOOK_STDPROCEDURE_END (hs_stdprocedure.int)

Runs after Fallout executes a standard procedure (handler) in any script of any object. NOTE: this hook will not be executed for start, critter_p_proc, timed_event_p_proc, and map_update_p_proc procedures.

int     arg0 - the number of the standard script handler (see *_proc in define.h)
+Obj     arg1 - the object that owns this handler (self_obj)
+Obj     arg2 - the object that called this handler (source_obj, can be 0)
+int     arg3 - always 1 (procedure end)
+Obj     arg4 - the object that is acted upon by this handler (target_obj, can be 0)
+int     arg5 - the parameter of this call (fixed_param), useful for combat_proc
+

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) + arg3 * 2), obj_name(arg2)));

Critter arg0 - Thief
+Obj     arg1 - The target
+Item    arg2 - The item being stolen/planted
+int     arg3 - 0 when stealing, 1 when planting
+int     arg4 - quantity of the item being stolen/planted
+
+int     ret0 - overrides hard-coded handler (2 - force fail without closing window, 1 - force success, 0 - force fail, -1 - use engine handler)
+int     ret1 - overrides experience points gained for stealing this item (must be greater than or equal to 0)
+

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 arg0 - the attacker
+Critter arg1 - the target
+Item    arg2 - the weapon used in the attack
+int     arg3 - attack type (see ATKTYPE_* constants)
+int     arg4 - number of bullets actually hit the target (1 for melee attacks)
+int     arg5 - target's Damage Resistance (DR) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
+int     arg6 - target's Damage Threshold (DT) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
+int     arg7 - bonus ranged damage from the perk
+int     arg8 - 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     arg9 - combat difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it's always 100)
+int     arg10 - the calculated amount of damage (usually 0, required when using multiple hook scripts to calculate damage and using the set_sfall_arg function)
+mixed   arg11 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)
+
+int     ret0 - the returned amount of damage
+

TargetObject

HOOK_TARGETOBJECT (hs_targetobject.int)

Runs when the targeting cursor hovers over an object, or when the player tries to attack the target object. You can override the target object or prevent the player from attacking the chosen target.

int     arg0 - event type: 0 - when the targeting cursor hovers over the object, 1 - when trying to attack the target object
+int     arg1 - 1 when the target object is valid to attack, 0 otherwise
+Obj     arg2 - the target object
+
+mixed   ret0 - overrides the target object, or pass -1 to prevent the player from attacking the object
+

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     arg0 - The hit chance (capped)
+Critter arg1 - The attacker
+Critter arg2 - The target of the attack
+int     arg3 - The targeted bodypart
+int     arg4 - Source tile (may differ from attacker's tile, when AI is considering potential fire position)
+int     arg5 - Attack Type (see ATKTYPE_* constants)
+int     arg6 - Ranged flag. 1 if the hit chance calculation takes into account the distance to the target. This does not mean the attack is a ranged attack
+int     arg7 - The raw hit chance before applying the cap
+
+int     ret0 - The new hit chance. The value is limited to the range of -99 to 999
+

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 arg0 - the critter that uses an object (usually dude_obj)
+Obj     arg1 - the object being used
+int     arg2 - the animation code being used (see ANIM_* in Animcomd.h)
+
+int     ret0 - 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 arg0 - The user
+Obj     arg1 - The object used
+
+int     ret0 - 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 arg0 - The target
+Critter arg1 - The user
+int     arg2 - The object used
+
+int     ret0 - 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.

Does not run if the script of the object calls script_overrides for using the skill.

Critter arg0 - The user critter
+Obj     arg1 - The target object
+int     arg2 - skill being used
+int     arg3 - skill bonus from items such as first aid kits
+
+int     ret0 - overrides hard-coded handler (-1 - use engine handler, any other value - override; if it is 0, there will be a 10% chance of removing the used medical item)
+

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 arg0 - the user critter (usually dude_obj)
+Obj     arg1 - the target object/critter
+int     arg2 - skill being used
+
+int     ret0 - a new critter to override the user critter. Pass -1 to cancel the skill use, pass 0 to skip this return value
+int     ret1 - pass 1 to allow the skill to be used in combat (only for dude_obj or critter being controlled by the player)
+

WithinPerception

HOOK_WITHINPRECEPTION (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 arg0 - Watcher object
+Obj     arg1 - Target object
+int     arg2 - Result of vanilla function: 1 - within perception range, 0 - otherwise
+int     arg3 - 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)
+    3 - when AI determines whether it sees a potential target when selecting attack targets
+    0 - all other cases
+
+int     ret0 - 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 script function which is called by every critter in the game)
+