sfall

Sfall scripting extensions for Fallout 2 Converted from headers/sfall/sfall.h

Functions

create_array_list

function create_array_list<T>(size: number): SfallList<T>

Create a persistent list

temp_array_list

function temp_array_list<T>(size: number): SfallList<T>

Create a temporary list

create_array_map

function create_array_map<K extends string | number, V>(): SfallMap<K, V>

Create a persistent map

temp_array_map

function temp_array_map<K extends string | number, V>(): SfallMap<K, V>

Create a temporary map

create_lookup_map

function create_lookup_map<K extends string | number, V>(): SfallMap<K, V>

Create a persistent lookup map (see arrays.txt for details)

temp_lookup_map

function temp_lookup_map<K extends string | number, V>(): SfallMap<K, V>

Create a temporary lookup map

is_in_array

function is_in_array<T>(item: T, array: SfallList<T>): boolean

Check if item exists in array

array_exists

function array_exists(array: SfallArray): boolean

Check if array exists

clear_array

function clear_array(array: SfallArray): void

Remove all elements from array

sort_array

function sort_array(array: SfallArray): void

Sort array or map by key in ascending order

sort_array_reverse

function sort_array_reverse(array: SfallArray): void

Sort array or map by key in descending order

reverse_array

function reverse_array(array: SfallArray): void

Reverse elements in list/map

shuffle_array

function shuffle_array(array: SfallArray): void

Randomly shuffle elements in list/map

sort_map_value

function sort_map_value<K extends string | number, V>(array: SfallMap<K, V>): void

Sort map in ascending order by value

sort_map_reverse

function sort_map_reverse<K extends string | number, V>(array: SfallMap<K, V>): void

Sort map in descending order by value

set_attack_explosion_pattern

function set_attack_explosion_pattern(x: number, y: number): void

Set attack explosion pattern

set_attack_explosion_art

function set_attack_explosion_art(x: number, y: number): void

Set attack explosion art

set_attack_explosion_radius

function set_attack_explosion_radius(radius: number): void

Set attack explosion radius

set_attack_is_explosion

function set_attack_is_explosion(damageType: number): void

Set attack is explosion

set_attack_is_explosion_fire

function set_attack_is_explosion_fire(): void

Set attack is fire explosion

set_explosion_radius

function set_explosion_radius(grenade: number, rocket: number): void

Set explosion radius for grenades and rockets

get_explosion_damage

function get_explosion_damage(itemPid: number): number

Get explosion damage for item

set_dynamite_damage

function set_dynamite_damage(minDmg: number, maxDmg: number): void

Set dynamite damage range

set_plastic_damage

function set_plastic_damage(minDmg: number, maxDmg: number): void

Set plastic explosive damage range

set_explosion_max_targets

function set_explosion_max_targets(maxTargets: number): void

Set maximum explosion targets

critter_inven_obj2

function critter_inven_obj2(critter: CritterPtr, slot: InvenSlot): ItemPtr

Get critter inventory object in extended slot

get_sfall_arg_at

function get_sfall_arg_at(index: number): number

Get sfall hook argument at index

set_iface_tag_text

function set_iface_tag_text(tag: IfaceTag, text: string, color: number): void

Set interface tag text

get_flags

function get_flags(obj: ObjectPtr): number

Get object flags

set_flags

function set_flags(obj: ObjectPtr, flags: number): void

Set object flags

get_outline

function get_outline(obj: ObjectPtr): number

Get object outline color

set_outline

function set_outline(obj: ObjectPtr, color: number): void

Set object outline color

get_object_data

function get_object_data(obj: ObjectPtr, offset: number): number

Get object data at offset

set_object_data

function set_object_data(obj: ObjectPtr, offset: number, value: number): void

Set object data at offset

get_cursor_mode

function get_cursor_mode(): number

Get current cursor mode

set_cursor_mode

function set_cursor_mode(mode: number): void

Set cursor mode

tile_refresh_display

function tile_refresh_display(): void

Refresh tile display

obj_under_cursor

function obj_under_cursor(onlyCritter: boolean, includeDude: boolean): ObjectPtr

Get object under cursor

real_dude_obj

function real_dude_obj(): number

Get the real dude object (useful when controlling other critters)

set_dude_obj

function set_dude_obj(critter: CritterPtr): void

Set the controlled critter (dude object)

dialog_obj

function dialog_obj(): ObjectPtr

Get the current dialog object

loot_obj

function loot_obj(): number

Get the current loot target object

combat_data

function combat_data(): number

Get combat data structure

get_combat_free_move

function get_combat_free_move(): number

Get combat free move value

set_combat_free_move

function set_combat_free_move(value: number): void

Set combat free move value

attack_is_aimed

function attack_is_aimed(): boolean

Check if current attack is aimed

get_current_inven_size

function get_current_inven_size(obj: ObjectPtr): number

Get current inventory size

item_weight

function item_weight(obj: ItemPtr): number

Get item weight

obj_is_openable

function obj_is_openable(obj: ObjectPtr): boolean

Check if object is openable

lock_is_jammed

function lock_is_jammed(obj: ObjectPtr): boolean

Check if lock is jammed

unjam_lock

function unjam_lock(obj: ObjectPtr): void

Unjam a lock

spatial_radius

function spatial_radius(obj: ObjectPtr): number

Get spatial script radius

get_text_width

function get_text_width(text: string): number

Get text width in pixels

string_compare

function string_compare(str1: string, str2: string): number

Compare two strings

string_find

function string_find(haystack: string, needle: string): number

Find substring in string

string_tolower

function string_tolower(text: string): string

Convert string to lowercase

string_toupper

function string_toupper(text: string): string

Convert string to uppercase

floor2

function floor2(value: number): number

Floor function that handles negative numbers correctly

car_gas_amount

function car_gas_amount(): number

Get car gas amount

add_iface_tag

function add_iface_tag(): IfaceTag

Add a new interface tag

intface_hide

function intface_hide(): void

Hide the main interface bar

intface_show

function intface_show(): void

Show the main interface bar

intface_redraw

function intface_redraw(): void

Redraw the main interface bar

intface_is_hidden

function intface_is_hidden(): boolean

Check if interface bar is hidden

display_stats

function display_stats(): void

Redraw the stats display

remove_timer_event

function remove_timer_event(fixedParam: number): void

Remove a timer event

remove_all_timer_events

function remove_all_timer_events(): void

Remove all timer events

add_global_timer_event

function add_global_timer_event(time: number, fixedParam: number): void

Add a global timer event

objects_in_radius

function objects_in_radius(tile: number, radius: number, elev: number, type: typeof OBJ_TYPE_CRITTER): SfallList<CritterPtr>

Returns all critters within radius of tile. Returns all items within radius of tile. Returns all scenery within radius of tile. Returns all walls within radius of tile. Returns all misc objects within radius of tile. Returns all spatial scripts within radius of tile. Get all objects within radius

tile_by_position

function tile_by_position(x: number, y: number): number

Get tile number from screen position

outlined_object

function outlined_object(): number

Get currently outlined object

art_cache_clear

function art_cache_clear(): void

Clear the art cache

exec_map_update_scripts

function exec_map_update_scripts(): void

Execute map update scripts

set_rest_mode

function set_rest_mode(mode: number): void

Set rest mode flags

set_rest_heal_time

function set_rest_heal_time(time: number): void

Set rest heal time

signal_close_game

function signal_close_game(): void

Signal the game to close

npc_engine_level_up

function npc_engine_level_up(toggle: boolean): void

Toggle NPC engine level up

get_object_ai_data

function get_object_ai_data(obj: CritterPtr, aiParam: number): number

Get object AI data

unwield_slot

function unwield_slot(critter: CritterPtr, slot: InvenSlot): void

Unwield item from slot

get_ini_section

function get_ini_section(file: string, sect: string): SfallMap<string, string>

Get INI file section as map of key-value pairs

get_ini_sections

function get_ini_sections(file: string): SfallList<string>

Get list of INI file sections

set_ini_setting

function set_ini_setting(setting: string, value: string | number): void

Set INI setting value

add_trait

function add_trait(traitID: number): void

Add a trait to the player

has_fake_perk_npc

function has_fake_perk_npc(npc: CritterPtr, perk: PerkID): boolean

Check if NPC has fake perk

has_fake_trait_npc

function has_fake_trait_npc(npc: CritterPtr, trait: TraitID): boolean

Check if NPC has fake trait

set_fake_perk_npc

function set_fake_perk_npc(npc: CritterPtr, perk: PerkID, level: number, image: number, desc: string): void

Set fake perk for NPC

set_fake_trait_npc

function set_fake_trait_npc(npc: CritterPtr, trait: TraitID, active: boolean, image: number, desc: string): void

Set fake trait for NPC

add_extra_msg_file

function add_extra_msg_file(fileName: string): number

Loads a custom message file and returns the file ID number for message_str_game

art_frame_data

function art_frame_data(art: string | number, frame: number, rot: number): SfallList<number>

Returns the dimensions of a given PCX or FRM frame as a temp array in the form [width, height].

draw_image

function draw_image(artFile: string, frame: number, x: number, y: number, noTrans: boolean): void

Displays the specified PCX or FRM image in the active window created by CreateWin or sfall’s create_win.

draw_image_scaled

function draw_image_scaled(artFile: string, frame: number, x: number, y: number, w: number, h: number): void

Displays the specified PCX or FRM image scaled to the given dimensions.

create_win

function create_win(winName: string, x: number, y: number, w: number, h: number): number

Creates a window with MoveOnTop flag. Works like vanilla CreateWin but allows the window to be placed on top of the game interface.

create_win_flag

function create_win_flag(winName: string, x: number, y: number, w: number, h: number, flag: number): number

Creates a window with specified flags. Works like vanilla CreateWin but allows setting additional flags.

win_fill_color

function win_fill_color(x: number, y: number, width: number, height: number, color: number): void

Fills the rectangle area of the currently selected script window with the specified color, or clears with transparent color if called without arguments.

interface_art_draw

function interface_art_draw(winID: number, artFile: string, x: number, y: number): void

Draws the specified PCX or FRM art in the specified interface window.

interface_print

function interface_print(text: string, winType: number, x: number, y: number, color: number): void

Displays text in the specified interface window with the current font.

inventory_redraw

function inventory_redraw(invSide: number): void

Redraws inventory items list in the inventory/loot/barter screens.

set_window_flag

function set_window_flag(winID: number, flag: number, value: number): void

Changes the specified flag for a script or game interface window.

dialog_message

function dialog_message(text: string): void

Displays a message in the NPC response window in dialog or barter screen.

message_box1

function message_box1(text: string): number

Creates a dialog box with text. Returns 0 (No/Escape), 1 (Yes/Enter), or -1 on error.

message_box2

function message_box2(text: string, flags: number): number

Creates a dialog box with text and flags. Returns 0 (No/Escape), 1 (Yes/Enter), or -1 on error.

message_box3

function message_box3(text: string, flags: number, color1: number): number

Creates a dialog box with text, flags, and first line color. Returns 0 (No/Escape), 1 (Yes/Enter), or -1 on error.

message_box4

function message_box4(text: string, flags: number, color1: number, color2: number): number

Creates a dialog box with text, flags, and colors. Returns 0 (No/Escape), 1 (Yes/Enter), or -1 on error.

string_format1

function string_format1(fmt: string, a1: any): string

Formats values using C printf syntax. Format string limited to 1024 characters.

string_format2

function string_format2(fmt: string, a1: any, a2: any): string

Formats values using C printf syntax.

string_format3

function string_format3(fmt: string, a1: any, a2: any, a3: any): string

Formats values using C printf syntax.

string_format4

function string_format4(fmt: string, a1: any, a2: any, a3: any, a4: any): string

Formats values using C printf syntax.

string_format5

function string_format5(fmt: string, a1: any, a2: any, a3: any, a4: any, a5: any): string

Formats values using C printf syntax.

string_format6

function string_format6(fmt: string, a1: any, a2: any, a3: any, a4: any, a5: any, a6: any): string

Formats values using C printf syntax.

string_format7

function string_format7(fmt: string, a1: any, a2: any, a3: any, a4: any, a5: any, a6: any, a7: any): string

Formats values using C printf syntax (max 7 values).

string_find_from

function string_find_from(haystack: string, needle: string, pos: number): number

Like string_find but starts search from the specified position.

get_can_rest_on_map

function get_can_rest_on_map(map: number, elev: number): number

Returns the set rest value of the map. Returns -1 if not previously set.

set_can_rest_on_map

function set_can_rest_on_map(map: number, elev: number, value: number): void

Allows/disallows resting on the map, overrides can_rest_here from maps.txt.

get_terrain_name

function get_terrain_name(x: number, y: number): string

Returns the terrain type name for the sub-tile on the world map by coordinates.

set_terrain_name

function set_terrain_name(x: number, y: number, name: string): void

Overrides the terrain type name for the sub-tile on the world map.

set_map_enter_position

function set_map_enter_position(tile: number, elev: number, rot: number): void

Overrides the player’s entry position when entering via exit grids. Works only in map_enter_p_proc.

set_worldmap_heal_time

function set_worldmap_heal_time(time: number): void

Sets the time interval in minutes for healing during world map travel. Default is 180.

get_tile_fid_ext

function get_tile_fid_ext(tile: number, elev: number, mode: number): number

Returns FID information about the square under the given tile.

get_tile_ground_fid

function get_tile_ground_fid(tile: number, elev: number): number

Returns FID of a ground tile at given tile number and elevation.

get_tile_roof_fid

function get_tile_roof_fid(tile: number, elev: number): number

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.

get_ini_config

function get_ini_config(file: string): SfallMap<string, SfallMap<string, string>>

Loads an INI file and returns a permanent array (map) where keys are section names and values are sub-arrays. Subsequent calls for the same file return the same array unless disposed with free_array.

get_ini_config_db

function get_ini_config_db(file: string): SfallMap<string, SfallMap<string, string>>

Like get_ini_config but searches in DAT files first, then regular file system.

get_pc_stat_max

function get_pc_stat_max(stat: number): number

Get PC stat maximum.

get_pc_stat_min

function get_pc_stat_min(stat: number): number

Get PC stat minimum.

item_make_explosive

function item_make_explosive(pid: number, activePid: number, min: number, max: number): void

Makes the specified item (pid) an explosive item like Dynamite or Plastic Explosives.

set_unique_id

function set_unique_id(obj: ObjectPtr): number

Assigns a unique ID number to the object and returns it. Items with unique IDs won’t stack. If already assigned, returns existing ID. Use get_object_data(obj, OBJ_DATA_ID) to just get the ID.

set_scr_name

function set_scr_name(name: string): void

Overrides the name of the script object from scrname.msg. Resets when leaving map or reloading. Pass empty string to use name from pro_*.msg files instead.

reg_anim_animate_and_move

function reg_anim_animate_and_move(obj: ObjectPtr, tile: number, animID: number, delay: number): void

Plays the specified animation while simultaneously moving the object to the given tile.

set_spray_settings

function set_spray_settings(ctrMult: number, ctrDiv: number, tgtMult: number, tgtDiv: number): void

Changes burst attack bullet distribution. Resets to defaults after each attack. Should be called before bullet distribution calc (e.g. in HOOK_TOHIT or HOOK_AMMOCOST).

set_quest_failure_value

function set_quest_failure_value(gvar: number, threshold: number): void

Sets the threshold value at which a quest is considered failed (crossed out red in pipboy).

set_car_intface_art

function set_car_intface_art(artIndex: number): void

Changes the interface art (index in intrface.lst) for the car image on the world map interface. Should be called before going to the world map. Vanilla art index is 433.

set_drugs_data

function set_drugs_data(type: number, pid: number, value: number): void

Overrides drug parameters from DrugsFile config.

set_town_title

function set_town_title(areaID: number, title: string): void

Sets floating text for a town on the world map when hovering over player’s marker.

set_unjam_locks_time

function set_unjam_locks_time(time: number): void

Sets hours until jammed locks auto-unjam when player leaves map (up to 127). Also disables midnight auto-unjam. Pass 0 to disable completely. Resets on reload.

metarule_exist

function metarule_exist(metaruleName: string): boolean

Returns true if the specified sfall_funcX metarule exists in the current sfall version.

set_selectable_perk_npc

function set_selectable_perk_npc(npc: CritterPtr, perk: PerkID, active: boolean, image: number, desc: string): void

Like set_selectable_perk but applies to specified party member NPC (including dude_obj).

set_horrigan_days

function set_horrigan_days(day: number): void

Set Horrigan encounter days (1-127) or disable (0)

clear_keyboard_buffer

function clear_keyboard_buffer(): void

Clear keyboard input buffer Use in HOOK_KEYPRESS to clear events before calling functions waiting for keyboard input

get_current_save_slot

function get_current_save_slot(): number

Get current save slot (page + slot) Note: slot value is 0-indexed instead of 1-indexed displayed in game

set_current_save_slot

function set_current_save_slot(page: number, slot: number): void

Set current save slot Note: slot value is 0-indexed instead of 1-indexed displayed in game

array_is_map

function array_is_map(array: SfallArray): boolean

Check if array is a map (associative array)

unset_array

function unset_array(array: SfallArray, key: any): void

Remove key from array (sets value to 0)

party_member_list_critters

function party_member_list_critters(): SfallList<CritterPtr>

Get list of party member critters (returns array for iteration). Includes dude_obj.

party_member_list_all

function party_member_list_all(): SfallList<ObjectPtr>

Get list of all party members

mstr_skill

function mstr_skill(msgNum: number): string

Get skill name from game messages

mstr_skilldex

function mstr_skilldex(msgNum: number): string

Get skilldex message from game messages

Constants

Name	Value	Description
IFACE_TAG_SNEAK	0	Sneak interface tag - shows when sneaking is active
IFACE_TAG_POISONED	1	Poisoned status tag - only for is_iface_tag_active check
IFACE_TAG_RADIATED	2	Radiated status tag - only for is_iface_tag_active check
IFACE_TAG_LEVEL	3	Level up available interface tag
IFACE_TAG_ADDICT	4	Addict status interface tag
WORLDMAP	0x1	World map mode
LOCALMAP	0x2	Local map mode (always 1 when scripts run)
DIALOG	0x4	Dialog mode
ESCMENU	0x8	Escape menu mode
SAVEGAME	0x10	Save game mode
LOADGAME	0x20	Load game mode
COMBAT	0x40	Combat mode
OPTIONS	0x80	Options menu mode
HELP	0x100	Help screen mode
CHARSCREEN	0x200	Character screen mode
PIPBOY	0x400	Pipboy mode
PCOMBAT	0x800	Player combat mode
INVENTORY	0x1000	Inventory mode
AUTOMAP	0x2000	Automap mode
SKILLDEX	0x4000	Skilldex mode
INTFACEUSE	0x8000	Interface use mode
INTFACELOOT	0x10000	Interface loot mode
BARTER	0x20000	Barter mode
HEROWIN	0x40000	Hero window mode
DIALOGVIEW	0x80000	Dialog view mode
COUNTERWIN	0x100000	Counter window for moving multiple items or setting a timer
PAUSEWIN	0x200000	Ctrl+P pause window
SPECIAL	0x80000000	Special mode
HOOK_HEXMOVEBLOCKING	12
HOOK_HEXAIBLOCKING	13
HOOK_HEXSHOOTBLOCKING	14
HOOK_HEXSIGHTBLOCKING	15
LIST_CRITTERS	0
LIST_GROUNDITEMS	1
LIST_SCENERY	2
LIST_WALLS	3
LIST_MISC	5
LIST_SPATIAL	6
LIST_ALL	9
WINTYPE_INVENTORY	0	Any inventory window (player/loot/use/barter)
WINTYPE_DIALOG	1
WINTYPE_PIPBOY	2
WINTYPE_WORLDMAP	3
WINTYPE_IFACEBAR	4	The interface bar
WINTYPE_CHARACTER	5
WINTYPE_SKILLDEX	6
WINTYPE_ESCMENU	7	Escape menu
WINTYPE_AUTOMAP	8
ENCOUNTER_FLAG_NO_CAR	0x1
ENCOUNTER_FLAG_LOCK	0x2	Block new forced encounter until current one occurs
ENCOUNTER_FLAG_NO_ICON	0x4	Disable displaying the flashing icon
ENCOUNTER_FLAG_ICON_SP	0x8	Use special encounter icon
ENCOUNTER_FLAG_FADEOUT	0x10	Fade out screen on encounter (you must restore fade when entering)
VALTYPE_NONE	0	Not used yet
VALTYPE_INT	1
VALTYPE_FLOAT	2
VALTYPE_STR	3
GAME_MSG_COMBAT	0
GAME_MSG_AI	1
GAME_MSG_SCRNAME	2
GAME_MSG_MISC	3
GAME_MSG_CUSTOM	4
GAME_MSG_INVENTRY	5
GAME_MSG_ITEM	6
GAME_MSG_LSGAME	7
GAME_MSG_MAP	8
GAME_MSG_OPTIONS	9
GAME_MSG_PERK	10
GAME_MSG_PIPBOY	11
GAME_MSG_QUESTS	12
GAME_MSG_PROTO	13
GAME_MSG_SCRIPT	14
GAME_MSG_SKILL	15
GAME_MSG_SKILLDEX	16
GAME_MSG_STAT	17
GAME_MSG_TRAIT	18
GAME_MSG_WORLDMAP	19
GAME_MSG_EDITOR	20
GAME_MSG_PRO_ITEM	0x1000
GAME_MSG_PRO_CRIT	0x1001
GAME_MSG_PRO_SCEN	0x1002
GAME_MSG_PRO_WALL	0x1003
GAME_MSG_PRO_TILE	0x1004
GAME_MSG_PRO_MISC	0x1005
OUTLINE_NONE	0
OUTLINE_RED_GLOW	0x01
OUTLINE_RED	0x02
OUTLINE_GREY	0x04
OUTLINE_GREEN_GLOW	0x08
OUTLINE_YELLOW	0x10
OUTLINE_DARK_YELLOW	0x20
OUTLINE_PURPLE	0x40
CURSOR_MOVEMENT	0
CURSOR_COMMAND	1
CURSOR_TARGETING	2
RESTMODE_DISABLED	1	Disable resting on all maps
RESTMODE_STRICT	2	Disable resting on maps with “can_rest_here=No” in Maps.txt, even if there are no other critters
RESTMODE_NO_HEALING	4	Disable healing during resting
BLOCKING_TYPE_BLOCK	0
BLOCKING_TYPE_SHOOT	1	Use this for more realistic line-of-sight checks
BLOCKING_TYPE_AI	2
BLOCKING_TYPE_SIGHT	3	Not really useful (works not as expected), game uses this only when checking if you can talk to a person
ADD_PERK_MODE_TRAIT	1	Add to the player’s traits list
ADD_PERK_MODE_PERK	2	Add to the player’s perks list
ADD_PERK_MODE_REMOVE	4	Remove from the list of selectable perks (after added to the player)

HOOK_TOHIT

Value: 0

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
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

HOOK_AFTERHITROLL

Value: 1

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

int     arg0 - If the attack will hit: 0 - critical miss, 1 - miss, 2 - hit, 3 - critical hit
Critter arg1 - The attacker
Critter arg2 - The target of the attack
int     arg3 - The bodypart
int     arg4 - The hit chance

int     ret0 - Override the hit/miss
int     ret1 - Override the targeted bodypart
Critter ret2 - Override the target of the attack

HOOK_CALCAPCOST

Value: 2

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, 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)
int     arg3 - The default AP cost
Item    arg4 - The weapon for which the cost is calculated (0 if can be obtained by other method)

int     ret0 - The new AP cost

HOOK_DEATHANIM1

Value: 3

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 (-1 if unarmed)
Critter arg1 - The attacker
Critter arg2 - The target
int     arg3 - The amount of damage
int     arg4 - Unused, always -1

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

HOOK_DEATHANIM2

Value: 4

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. Does not run for critters in the knockdown/out state.

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.

int     arg0 - The pid of the weapon performing the attack (-1 if 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

HOOK_COMBATDAMAGE

Value: 5

Runs when:

1. Game calculates how much damage each target will get (primary target and extras from explosions/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)
int     arg5  - The special effect flags for the attacker
Item    arg6  - The weapon used in the attack
int     arg7  - The bodypart that was struck
int     arg8  - Damage Multiplier (divided by 2, so 3 = 1.5x, 8 = 4x)
int     arg9  - Number of bullets actually hit the target (1 for melee)
int     arg10 - The amount of knockback to the target
int     arg11 - Attack Type (see ATKTYPE_* constants)
mixed   arg12 - computed attack data (use C_ATTACK_* offsets with get/set_object_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

HOOK_ONDEATH

Value: 6

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 one.

Critter arg0 - The critter that just died

HOOK_FINDTARGET

Value: 7

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 they may still be discarded later if out of perception or chance of hit is too low.

Use set_sfall_return to give the 4 targets, in order of preference. Pass 0 or -1 to skip return values for less than 4 targets.

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

HOOK_USEOBJON

Value: 8

Runs when:

1. a critter uses an object on another critter (or themselves)
2. a critter uses an object from inventory without “Use” action flag and it’s not active flare/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/destroy this object during the hookscript (game will crash). To remove it, return 1.

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

int     ret0 - overrides handler (0 - place back, 1 - remove, -1 - use engine handler)

HOOK_REMOVEINVENOBJ

Value: 9

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 moved to another object, 0 otherwise

HOOK_BARTERPRICE

Value: 10

Runs whenever the value of goods being purchased is calculated.

NOTE: the hook is executed twice when entering the barter screen or after transaction: the first time is for the player and the second time is for NPC.

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

int     ret0 - the modified value of all goods (pass -1 to just modify offered goods)
int     ret1 - the modified value of all offered goods

HOOK_MOVECOST

Value: 11

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

HOOK_ITEMDAMAGE

Value: 16

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
int     ret1 - The new maximum damage

HOOK_AMMOCOST

Value: 17

Runs when calculating ammo cost for a weapon. Doesn’t affect damage, only how much ammo is spent. By default, a weapon can perform an attack with at least one ammo, regardless of ammo cost calculation. To add proper checks for ammo before attacking (hook type 1), set CheckWeaponAmmoCost=1 in ddraw.ini.

NOTE: The return value must be >= 0 to be valid.

Item    arg0 - The weapon
int     arg1 - Number of bullets in burst or 1 for single shots
int     arg2 - The amount of ammo that will be consumed (for hook type 2, this is ammo cost per round)
int     arg3 - Type of hook:
               0 - when subtracting ammo after single shot attack
               1 - when checking for "out of ammo" before attack
               2 - when calculating number of burst rounds
               3 - when subtracting ammo after burst attack

int     ret0 - The new ammo to consume, or ammo cost per round for hook type 2 (0 = unlimited ammo)

HOOK_USEOBJ

Value: 18

Runs when:

1. a critter uses an object from inventory which has “Use” action flag set or it’s an active flare/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/destroy this object during the hookscript (game will crash). To remove it, return 1.

Critter arg0 - The user
Obj     arg1 - The object used

int     ret0 - overrides handler (0 - place back, 1 - remove, -1 - use engine handler)

HOOK_KEYPRESS

Value: 19

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

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)

HOOK_MOUSECLICK

Value: 20

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)

HOOK_USESKILL

Value: 21

Runs when using any skill on any object. This is fired before the default handlers are called, which you can override.

If you override, you should write your own skill use handler entirely (including fade in/out, time lapsing and messages - use message_str_game with sprintf for vanilla text).

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 handler (-1 = use engine, other = override; 0 = 10% chance to remove medical item)

HOOK_STEAL

Value: 22

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.

If you override, you MUST provide message of the result to player. Example: 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 handler (2 - force fail without closing window, 1 - force success, 0 - force fail, -1 - use engine)
int     ret1 - overrides experience points gained for stealing this item (must be >= 0)

HOOK_WITHINPERCEPTION

Value: 23

Runs when checking if one critter sees another critter (used in combat AI, etc). This is fired after the default calculation is made.

NOTE: obj_can_see_obj calls this first when deciding if critter can see another critter with regard to perception, lighting, sneak factors. If check fails, result is false. If check succeeds, another check is made for blocking tiles (windows, bushes, barrels, etc).

You can override “within perception” check by returning 0 or 1, OR override blocking check by returning 2 (but then you should add line of sight check in your hook script).

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 - from obj_can_see_obj script function
               2 - from obj_can_hear_obj (need ObjCanHearObjFix=1 in ddraw.ini)
               3 - when AI determines whether it sees a potential target
               0 - all other cases

int     ret0 - overrides result: 0 - not in range, 1 - in range (will see if not blocked), 2 - forced detection

HOOK_INVENTORYMOVE

Value: 24

Runs before moving items between inventory slots in dude interface. You can override the action.

What you can NOT do: force moving items to inappropriate slots (gun in armor slot). What you can do: restrict weapons/armors, add AP costs for inventory movement, apply scripted effects.

int     arg0 - Target slot:
               0 - main backpack, 1 - left hand, 2 - right hand, 3 - armor slot
               4 - weapon (when reloading by dropping ammo), 5 - container (bag/backpack)
               6 - dropping on ground, 7 - picking up item, 8 - dropping on 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, other = prevent relocation/reload/pickup)

HOOK_INVENWIELD

Value: 25

Runs before causing a critter or the player to wield/unwield an armor or weapon (except when using the inventory by PC).

NOTE: When replacing a previously wielded armor or weapon, the unwielding hook will not be executed. If you need to rely on this, check 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 handler (-1 = use engine, other = override) - NOT RECOMMENDED

HOOK_ADJUSTFID

Value: 26

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 format: 0x0ABBCDDD where A = object type, BB = animation code (always 0 here), C = weapon code, DDD = FRM index in LST file.

int     arg0 - the vanilla FID calculated by the engine
int     arg1 - the modified FID calculated by internal sfall code (like Hero Appearance Mod)

int     ret0 - overrides the calculated FID with provided value

HOOK_COMBATTURN

Value: 27

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 start/end of player's turn after loading a game saved in combat mode, 0 otherwise

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

HOOK_CARTRAVEL

Value: 28

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

HOOK_SETGLOBALVAR

Value: 29

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

HOOK_RESTTIMER

Value: 30

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

int     arg0 - the game time in ticks
int     arg1 - event type: 1 - resting ends normally, -1 - pressing ESC to cancel, 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 ESC

HOOK_GAMEMODECHANGE

Value: 31

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

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

HOOK_USEANIMOBJ

Value: 32

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)

HOOK_EXPLOSIVETIMER

Value: 33

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: 1 - failure, 2 - success (similar to ROLL_*)

int     ret0 - overrides the time of the timer (maximum 18000 ticks)
int     ret1 - overrides the result: 0/1 - failure, 2/3 - success, other = use engine handler

HOOK_DESCRIPTIONOBJ

Value: 34

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.

Obj     arg0 - the object

String  ret0 - the new description text to use

HOOK_USESKILLON

Value: 35

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. Pass -1 to cancel skill use, 0 to skip this return
int     ret1 - pass 1 to allow the skill to be used in combat (only for dude_obj or controlled critter)

HOOK_ONEXPLOSION

Value: 36

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 are received.

int     arg0 - event type: 1 - checking objects without causing damage (e.g. player drops 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

HOOK_SUBCOMBATDAMAGE

Value: 37

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

1. Before the game calculates how much damage each target will get (primary and extras from explosions/bursts).
2. AI decides whether it is safe to use area attack if he might hit friendlies.

Does not run for misses, non-combat damage, 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)
int     arg5 - target's Damage Resistance (DR) value
int     arg6 - target's Damage Threshold (DT) value
int     arg7 - bonus ranged damage from the perk
int     arg8 - damage multiplier (divided by 2, so 3 = 1.5x, 8 = 4x)
int     arg9 - combat difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy)
int     arg10 - the calculated amount of damage (usually 0)
mixed   arg11 - computed attack data (use C_ATTACK_* offsets with get/set_object_data)

int     ret0 - the returned amount of damage

HOOK_SETLIGHTING

Value: 38

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)

HOOK_SNEAK

Value: 39

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.

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

HOOK_STDPROCEDURE

Value: 40

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.

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

HOOK_STDPROCEDURE_END

Value: 41

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.

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

HOOK_TARGETOBJECT

Value: 42

Runs when the targeting cursor hovers over an object, or when the player tries to attack the target. 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
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

HOOK_ENCOUNTER

Value: 43

Runs whenever a random encounter occurs on the world map.

int     arg0 - event type: 0 - encounter happens, 1 - player enters a special encounter map
int     arg1 - map ID for special encounters; for random encounters, 0 unless an ID was manually set
int     arg2 - 1 if this is a special encounter, 0 otherwise
int     arg3 - the encounter table number (from Encounter table in worldmap.txt)
int     arg4 - the encounter index in the table (number of the line in Encounter table section)

int     ret0 - overrides the map ID for special encounter maps
int     ret1 - pass 1 to cancel the encounter and continue traveling

HOOK_ADJUSTPOISON

Value: 44

Runs when the player’s poison level is changed. NOTE: the hook is not executed for the critter_adjust_poison function.

Critter arg0 - the critter (always dude_obj)
int     arg1 - the amount of poison being added (negative = reducing poison)
int     arg2 - the calculated damage value that will be applied to hit points at the end of each day

int     ret0 - the new amount of poison
int     ret1 - the damage value to apply

HOOK_ADJUSTRADS

Value: 45

Runs when the player’s radiation level is changed. NOTE: the hook is not executed for the critter_adjust_rads function.

Critter arg0 - the critter (always dude_obj)
int     arg1 - the amount of radiation being added

int     ret0 - the new amount of radiation

HOOK_ROLLCHECK

Value: 46

Runs when Fallout makes a random roll check for the skills or attacker’s weapon in combat.

int     arg0 - event type:
               1 - aass/fail critical skill check (determine_to_hit_func)
               2 - check (determine_crit_ranged_attack_to_hit_func)
               3 - weapon critical failure check (attack_crit_failure)
               4 - weapon critical hit check (attack_crit_success)
               5 - skill critical hit check (skill_result)
               6 - skill critical miss check (skill_result)
               7 - skill check (skill_result)
int     arg1 - the roll result (0-100)
int     arg2 - the chance of critical hit/miss (0-100)
int     arg3 - the bonus value to add to/subtract from the hit chance
int     arg4 - the random chance value (1-100)

int     ret0 - the new roll result

HOOK_BESTWEAPON

Value: 47

Runs when AI is choosing the best weapon for an attack.

Critter arg0 - the critter
Item    arg1 - the best weapon chosen by the AI (can be 0 if nothing was chosen)
Item    arg2 - the first available weapon (can be 0)
Item    arg3 - the second available weapon (can be 0)
Critter arg4 - the target of the attack

Item    ret0 - overrides the weapon choice (pass 0 to allow no weapon, -1 to skip this return)

HOOK_CANUSEWEAPON

Value: 48

Runs when AI checks if a weapon is usable (has enough ammo, in range, etc).

Critter arg0 - the critter
Item    arg1 - the weapon being checked
int     arg2 - attack type (see ATKTYPE_* constants)
int     arg3 - 1 if the weapon can be used, 0 if it can't

int     ret0 - overrides the result: 0 - cannot use, 1 - can use

HOOK_BUILDSFXWEAPON

Value: 61

Runs before the weapon sound effect is played for an attack.

int     arg0 - the sound effect type:
               0 - generic attack
               1 - fire attack
               2 - contact/swing/throw attack
               3 - reload
               4 - out of ammo
Item    arg1 - the weapon (can be 0 for unarmed)
int     arg2 - attack type (see ATKTYPE_* constants)
Critter arg3 - the target (can be 0)

String  ret0 - the path to a custom sfx sound file (relative to sound/sfx/)