As well as the new functions, sfall also adds global scripts. These run independent of any loaded maps, but do not have an attached object (i.e. using `self_obj` without using `set_self` first will crash the script).
To use a global script, the script must have a name which begins with `gl` and contains a procedure called `start`, `map_enter_p_proc`, `map_exit_p_proc`, or `map_update_p_proc`. The `start` procedure will be executed once when the player loads a saved game or starts a new game. The `map_*_p_proc` procedures will be executed once when a map is being entered/left/updated. If you wish the script to be executed repeatedly, call `set_global_script_repeat` on the first run of the `start` procedure using the number of frames between each run as the argument (0 disables the script, 1 runs it every frame, 2 runs it every other frame, etc.).
Global scripts have multiple modes, which can be set using the `set_global_script_type` function. In the default mode (i.e. mode 0) their execution is linked to the local map game loop, so the script will not run in dialogs or on the world map. In mode 1 their execution is linked to the player input, and so they will run whenever the mouse cursor is visible on screen, including the world map, character dialogs, etc. In mode 2, execution is linked to the world map loop, so the script will only be executed on the world map and not on the local map or in any dialog windows. Mode 3 is a combination of modes 0 and 2, so scripts will be executed on both local maps and the world map, but not in dialog windows.\
_Using mode 1 requires the input wrapper to be enabled. Use available_global_script_types to check what is available._ - **Obsolete**.
Both `set_global_script_repeat` and `set_global_script_type` only have an effect on the script they were called from. Every global script needs its own `game_loaded` block to correctly set up the script type and repeat rate. `set_global_script_repeat` will have no effect if called on a non-global script.
The `read_xxx` functions take a memory address as the parameter and can read arbitrary pieces of Fallout's address space. The `write_xxx` functions are equivalent except that they write to arbitrary memory addresses.
The `call_offset_xx` functions can be used to call arbitrary functions inside Fallout. Different versions are used to call functions with different numbers of arguments.
The `get_pc_base_stat`, `set_pc_base_stat`, `get_pc_extra_stat` and `set_pc_extra_stat` functions are equivalent to calling `get_critter_base_stat`, `set_critter_base_stat`, `get_critter_extra_stat` and `set_critter_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.
The `set_stat_min` and `set_stat_max` functions can be used to set the valid ranges on stats. Values returned by `get_current_stat` will be clamped to this range. The `set_pc_stat_*` functions only affect the player, the `set_npc_stat_*` functions only affect other critters, and the `set_stat_*` functions affect both.
The graphics functions are only available if the user is using graphics mode 4 or 5. Use `graphics_funcs_available` to check; it returns 1 if you can use them or 0 if you can't. Calling graphics functions when `graphics_funcs_available` returns 0 will do nothing.
The `load_shader` takes a path relative to the `<GameRoot>\<master_patches>\shaders\` directory as an argument and returns a shader ID. That ID should be passed as the first argument to all other shader functions, and is valid until `free_shader` is called on the ID, the player loads a saved game or the player quits to the main menu.
The `get_shader_version` gives you the highest shader version supported by the player's graphics cards. Possible return values are 11, 12, 13, 14, 20, 21 and 30.
The `set_shader_mode` tells sfall when to use a shader. The parameter is a set of 32 flags which specify the screens on which the shader will be disabled, unless bit 32 is set, in which case the shader will only be active on those screens. Remember that screens are displayed on top of each other; if the player opens the character menu which in combat, the game still considers the player to be in combat. See **sfall.h** for a list of defines.
The `force_graphics_refresh` forces the screen to redraw at times when it normally wouldn't. If you're using animated shader, turning this option on is recommended.
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. The `get_world_map_x_pos` and `get_world_map_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.
The `get_critter_current_ap` and `set_critter_current_ap` functions should only be used during the target critters turn while in combat. Calling them outside of combat typically returns the critters max AP, but don't rely on that behaviour. (Specifically, if the critter has never before entered combat, it will probably return the critters base AP ignoring any extra bonuses from perks etc.)
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.
The `get_sfall_global` and `set_sfall_global` functions require an 8 characters long case sensitive string for the variable name. The variables behave the same as normal Fallout globals, except that they don't have to be declared beforehand in **vault13.gam**. Trying to get a variable which hasn't been set will always return 0. These functions are intended for use when a patch to a mod requires the addition of a new global variable, a case which would otherwise require the player to start a new game.
The `set_pickpocket_max` and `set_hit_chance_max` affect all critters rather than just the player and can set the maximum in range from 0 to 999.
The `set_skill_max` can't be used to increase the skill cap above 300. The `set_perk_level_mod` 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.
The `set_fake_trait` and `set_fake_perk` can be 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.
The `has_fake_trait` and `has_fake_perk` return the number of levels the player has of the perks/traits with the given name or ID of extra perk.
The `perk_add_mode`, `set_selectable_perk`, `set_perkbox_title`, `hide_real_perks`, `show_real_perks` and `clear_selectable_perks` control the behaviour of the select a perk box. The `set_selectable_perk` can be used to add additional items by setting the **active** parameter to 1, and to remove them again by setting it to 0. The `set_perkbox_title` can be used to change the title of the box, or by using `""` it will be set back to the default. The `hide_real_perks` and `show_real_perks` can be used to prevent the dialog from displaying any of the original 119 perks. The `perk_add_mode` 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. The `clear_selectable_perks` restores the dialog to its default state.
The `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 3 for **LEVEL** and 4 for **ADDICT**, or the range from 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**.
The `get_bodypart_hit_modifier` and `set_bodypart_hit_modifier` alter the hit percentage modifiers for aiming at specific bodyparts. Valid bodypart id's are from 0 to 8. Changes are not saved, and will reset to the defaults (or to the values specified in **ddraw.ini** if they exist) at each reload.
The `get_critical_table`, `set_critical_table` and `reset_critical_table` are used for modifying the critical table (for details, see http://falloutmods.wikia.com/wiki/Critical_hit_tables). Changes are not saved, and will reset to the defaults (or to the contents of **CriticalOverrides.ini**, if it exists) at each game reload. These function also require **OverrideCriticalTable** to be enabled in **ddraw.ini**.
The `get_unspent_ap_bonus` and `set_unspent_ap_bonus` alter 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.) The `get_unspent_ap_perk_bonus` and `set_unspent_ap_perk_bonus` are similar, but affect the extra AC granted by the HtH Evade perk. (The default value of this is also 4, equivalent to doubling the original bonus.)
The `nb_*` functions are reserved for the brotherhood tactical training mod, and should be avoided.
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.
The `get_proto_data` and `set_proto_data` are used to manipulate 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.
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.
The `play_sfall_sound` and `stop_sfall_sound` are used to play **mp3/wav/wma** files. The path given is relative to the Fallout folder. Specify mode as 1 to loop the file continuously, 2 to replace the current background game music with playing the specified file in loop mode, or 0 to play the file once. If you don't wish to loop, `play_sfall_sound` returns 0. If you do loop, it returns an id which can be passed back to `stop_sfall_sound` when you want to stop the effect. All sounds effects will be stopped on game reload, looping or not. These functions do not require **AllowDShowSound** to be set to 1 in **ddraw.ini**.
Starting from sfall 4.2.8/3.8.28, you can pass a value in the **mode** argument for a reduced sound volume. To set the volume, You need to convert the number to hexadecimal and use the argument format `0xZZZZ000Y`, where `ZZZZ` is the volume reduction value in range from 0 to 32767 (the value 32767 is muted), and `Y` is the playback mode.
Arrays are created and manipulated with the `xxx_array` functions. An array must first be created with `create_array` or `temp_array`, specifying how many data elements the array can hold. You can store any of ints, floats and strings in an array, and can mix all 3 in a single array. The ID returned by `create_array` or `temp_array` can then be used with the other array functions. Arrays are shared between all scripts. (i.e. you can call `create_array` from one script, and then use the returned ID from another script.) They are also saved across savegames. Arrays created with `temp_array` will be automatically freed at the end of the frame. These functions are safe, in that supplying a bad id or trying to access out of range elements will not crash the script. `create_array` is the only function that returns a permanent array, all other functions which return arrays (`string_split`, `list_as_array`, etc,) all return temp arrays. You can use `fix_array` to make a temp array permanent.\
The `force_aimed_shots` and `disable_aimed_shots` allow overriding the normal rules regarding which weapons are allowed to make aimed attacks. (e.g. weapons that cause explosive damage normally cannot normally make aimed shots.) `force_aimed_shots` will allow a weapon to make aimed shots even if it normally couldn't, and `disable_aimed_shots` stops a weapon from making aimed shots even if it normally could. Both of these functions affect player and NPCs alike. `force_aimed_shots` does not override the effects of the fast shot trait. The list of edited weapons is not saved over game loads, so you need to call the functions once at each reload. Use a pid of 0 to represent unarmed.
The `get_critter_skill_points` and `set_critter_skill_points` will get or 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 `set_skill_points` on a critter will affect all critters that share the same proto.
---------------
TYPES REFERENCE
---------------
Data types mentioned in this document:
*`void` - means opcode does not return any value
*`any` - any type
*`int` - integer number
*`float` - floating point number
*`string` - string (text) value
*`object` - pointer to game object (actually an integer)
*`array` - array ID to be used with array-related functions (actually an integer)
*`bool` - boolean values: `True` or `False` (actually an integer 1 or 0)
------------------
FUNCTION REFERENCE
------------------
##### `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.
- 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").
- 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.
-----
##### `int get_npc_level(int pid/string name)`
- Also takes the party member PID or NPC name (deprecated, for compatibility with sfall 4.1.5/3.8.15 or earlier) as an argument, and returns the NPC's current level. Again, the NPC needs to be in your party.
-----
##### `void set_car_current_town(int town)`
- Changes the current town index for the player's car.
-----
##### `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")`.
- Is 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.
-----
##### `int get_uptime()`
- Is 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.
-----
##### `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.
-----
##### `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.
-----
##### `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.
-----
##### `int get_light_level()`
- 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.
-----
##### `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.
- Accepts a pointer to an object and **scriptID**, and applies the given script to an object (scriptID accepts the same values as `create_object_sid`)
- 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.
- 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.
- __NOTE:__ for `use_obj` and `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.
- Will return the last critter to deliberately launch an attack against the argument critter.
- If a critter has not launched/received an attack, it will return 0. This is only stored for the duration of combat, and outside of combat both functions will always return 0.
-----
##### `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).
- Allows enabling all `reg_anim_*` functions in combat (including vanilla functions) if set to 0. It is automatically reset at the end of each frame, so you need to call it before `reg_anim_begin() ... reg_anim_end()` code block.
**Some additional `reg_anim_*` functions were introduced. They all work in the same convention as vanilla functions and use the same underlying code.**
##### `void reg_anim_destroy(object)`
- Given object is destroyed at the end of current animation set.
- Exactly like `reg_anim_animate` but the object will automatically disappear after the last animation frame (but not destroyed).
-----
##### `void reg_anim_light(object, light, delay)`
- Change light of any object. light argument is a light radius (0-8), but you can use highest 2 bytes to pass light intensity as well (example: `0xFFFF0008` - intensity 65535 and radius 8). If highest 2 bytes are 0, intensity will not be changed. Intensity range is from 0 to 65535 (0xFFFF).
- Was made as a quick-and-dirty hack to enable dynamic changes to some explosion parameters for ranged attacks. All changed parameters are automatically reset to vanilla state after each attack action. Following macros are available in **sfall.h**:
- Currently `y` is not used and `x` means: 1 - reduced explosion pattern (3 effects are spawned instead of 7), 0 - full pattern.
-----
##### `void set_attack_explosion_art(x, y)`
-`y` is not used and `x` is a misc frame ID (last 3 bytes, without object type) to use for the next explosion.
-----
##### `void set_attack_explosion_radius(x)`
- Changes radius at which explosion will hit secondary targets for the next attack (from the experiments it is limited to something around 8 by the engine)
-----
##### `void set_attack_is_explosion_fire`
- If you call this right before using a weapon with fire damage type (e.g. in `HOOK_AFTERHITROLL`), it will produce explosion effects (and radius damage) just like "explosion" type, but all targets will still receive fire damage.
- Takes a string and a separator, searches the string for all instances of the separator, and returns a temp array filled with the pieces of the string split at each instance. If you give an empty string as the separator, 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))`
- 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").
- Formats given value using standard syntax of C `printf` function (google "printf" for format details). However, it is limited to formatting only 1 value.
- Works just like `register_hook_proc`, but allows to register a script at the end of the hook script execution chain (i.e. the script will be executed after all previously registered scripts for the same hook, including the `hs_*.int` script).
- To unregister hook script from current global script, use the `register_hook_proc` function.
-----
##### `string message_str_game(int fileId, int messageId)`
- Works exactly the same as `message_str`, except you get messages from files in the `text\<language>\game\` directory.
- 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.)
- Returns 1 if the player is currently sneaking, and 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`).
-----
##### `int tile_light(int elevation, int tileNum)`
- Returns light intensity at the given tile in range from 0 to 65536.
-----
##### `object obj_blocking_line(object 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.
-----
##### `object 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.
-----
##### `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.
- 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, e.g. `set_ini_setting("myini.ini|mysec|var1", 42)`
- The file name is limited to 63 chars, including the extension
- The section name is limited to 32 characters
----
#### floor2
`int sfall_func1("floor2", int/float value)`
- Works just like vanilla `floor` function, but returns correct integers for negative values
- __NOTE:__ vanilla `floor` function works exactly the same as ceil for negative values, much like trunc in C/C++
----
#### item_weight
`int sfall_func1("item_weight", object)`
- Gets the current weight of an object
----
#### get_outline
`int sfall_func1("get_outline", object)`
- Gets the current outline color for an object
----
#### set_outline
`void sfall_func2("set_outline", object, 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
- call `tile_refresh_display` after changing outline of objects to properly redraw the scene
----
#### get_flags
`int sfall_func1("get_flags", object)`
- Gets the current value of object flags (see **define_extra.h** for available flags)
-----
##### set_flags
`void sfall_func2("set_flags", object, 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
----
#### tile_refresh_display
`void sfall_func0("tile_refresh_display")`
- Redraws the game scene (tiles, walls, objects, etc.)
----
#### outlined_object
`object sfall_func0("outlined_object")`
- Returns an object that is currently highlighted by hovering the mouse above it
- 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_ifaca_tag` function
`void sfall_func1("inventory_redraw", int invSide)`
- Redraws inventory list in the inventory/use inventory item on/loot/barter screens
-`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)
- __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
`void sfall_func6("create_win", string winName, int x, int y, int width, int height, int flags)`
- 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
----
#### set_can_rest_on_map
`void sfall_func3("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)
----
#### get_can_rest_on_map
`int sfall_func2("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
----
#### dialog_obj
`object sfall_func0("dialog_obj")`
- Returns a pointer to the object (critter) the player is having a conversation or bartering with
`int sfall_func2("set_unique_id", 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
- 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 `sfall_func2("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
`void sfall_func6("draw_image_scaled", string/int pathFile/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
-`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)`)
- If `draw_image_scaled` is called without x/y/width/height arguments, the image will be scaled to fit the window without transparent background
- These functions are similar to `has_fake_perk`, `has_fake_trait`, `set_fake_perk`, `set_fake_trait`, `set_selectable_perk`, and `set_selectable_trait` functions, but apply to the specified party member NPC (including `dude_obj`)
`int sfall_func2("add_extra_msg_file", string fileName, int fileNumber)`
- 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 the `text\<language>\game\` directory
- __NOTE:__ if the msg file does not exist in the current language directory, the function will try to load it from the `text\English\game\` directory
-`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
`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
`string sfall_funcX("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
`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
-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. `win.top`, `win.bottom`)
- Returns -1 if the specified attribute cannot be obtained
----
#### 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**
----
#### 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)
`int sfall_func6("interface_art_draw", int winType, string/int artFile/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
-`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)\
`int sfall_func5("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 color (use index 0 or call the function without arguments)
-`color`: the color index in the game palette (from 0 to 255)
`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**)
0 - destroys the created overlay surface (frees up the memory allocated to the surface)
----
#### 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
- Allows changing the multipliers and divisors for the bullet distribution of burst attacks dynamically. All settings are automatically reset to default values (**ComputeSpray_\*** settings in **ddraw.ini**) after each attack action
- 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
-`searchDB`:\
False - searches the file in the regular file system, like with all other ini-related functions\
True - searches the file in database (DAT) files. If not found, then it will try the regular file system
- Subsequent calls for the same file will return the same array, unless it was disposed using `free_array`
`int sfall_func3("string_pos", string haystack, string needle, int pos)`
- 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)
**Optional argument:**
-`pos`: the position at which to start the search. If negative, it indicates a position starting from the end of the string
