mirror of
https://github.com/sfall-team/sfall.git
synced 2026-07-27 16:52:34 -07:00
Some edits to documents
Removed txt version of arrays, hookscripts, and function notes.
This commit is contained in:
NovaRain
@@ -9,9 +9,7 @@ Arrays can be extremely useful for some more advanced scripting, in conjunction
|
||||
***
|
||||
### ARRAYS CONCEPT
|
||||
|
||||
Arrays are created and manipulated with the 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 `int`, `float` and `string` 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.
|
||||
|
||||
*You must remember to free any arrays you create with `create_array` when you are done with them, or you will leak memory.*
|
||||
Arrays are created and manipulated with the 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 temporary arrays. You can use `fix_array` to make a temporary array permanent.
|
||||
|
||||
@@ -195,7 +193,7 @@ _*mixed means any type_
|
||||
#### `void resize_array(int arrayID, int size)`
|
||||
- changes array size
|
||||
- applicable to maps too, but only to reduce elements
|
||||
- there are number of special negative values of "size" which perform various operations on the array, use macros `sort_array`, `sort_array_reverse`, `reverse_array`, `shuffle_array` from *sfall.h* header
|
||||
- there are number of special negative values of "size" which perform various operations on the array, use macros `sort_array`, `sort_array_reverse`, `reverse_array`, `shuffle_array` from **sfall.h** header
|
||||
|
||||
#### `void free_array(int arrayID)`
|
||||
- deletes any array
|
||||
@@ -222,7 +220,7 @@ _*mixed means any type_
|
||||
- always returns 0
|
||||
|
||||
#### `void save_array(mixed key, int arrayID)`
|
||||
- makes the array saveable; it will be saved in *sfallgv.sav* file when saving the game
|
||||
- makes the array saveable; it will be saved in **sfallgv.sav** file when saving the game
|
||||
- array ID is associated with given "key"
|
||||
- array becomes permanent (if it was temporary) and "saved"
|
||||
- key can be of any type (int, float or string)
|
||||
@@ -240,7 +238,7 @@ For those who used arrays in their mods before sfall 3.4:
|
||||
|
||||
* There is an INI parameter **arraysBehavior** in **Misc** section of ddraw.ini. If set to 0, all scripts which used sfall arrays before should work. This basically changes that `create_array` will create permanent arrays which are "saved" by default and their ID is also permanent. It is 1 by default.
|
||||
|
||||
* How savegame compatibility is handled?
|
||||
Saved arrays are stored in *sfallgv.sav* file (in savegame) in new (more flexible) format, just after the old arrays. So basically, when you load older savegame, sfall will load arrays from old format and save them to new format on next game save. If you load savegame made with sfall 3.4 using sfall 3.3 (for example), game shouldn't crash, but all arrays will be lost.
|
||||
* How savegame compatibility is handled?<br>
|
||||
Saved arrays are stored in **sfallgv.sav** file (in savegame) in new (more flexible) format, just after the old arrays. So basically, when you load older savegame, sfall will load arrays from old format and save them to new format on next game save. If you load savegame made with sfall 3.4 using sfall 3.3 (for example), game shouldn't crash, but all arrays will be lost.
|
||||
|
||||
* Previously you had to specify size in bytes for array elements. This parameter is now ignored and you can store strings of arbitrary length in arrays.
|
||||
|
||||
@@ -1,234 +0,0 @@
|
||||
>>> ARRAYS CONCEPT <<<
|
||||
|
||||
Sfall introduces new method of storing variables - arrays.
|
||||
|
||||
Array is basically a container which can store variable number of values (elements). Each element in array can be of any type.
|
||||
Arrays can be extremely useful for some more advanced scripting, in conjunction with loops.
|
||||
|
||||
Array elements are accessed by index or key. For example:
|
||||
|
||||
// this code puts some string in array "list" at index 5:
|
||||
list[5] := "Value";
|
||||
|
||||
|
||||
There are 2 different types of arrays currently available:
|
||||
1) Lists - a set of values with specific size (number of elements), where all elements have numeric indexes starting from zero (0) up to array length minus one.
|
||||
For example:
|
||||
|
||||
// this creates list with 3 elements. Element "A" has index 0, element "B" has index 1, element "C" - 2
|
||||
list := ["A", "B", "C"];
|
||||
|
||||
Limitations:
|
||||
- all indexes are numeric, starting from 0;
|
||||
- to assign value to a specific index, you must first resize array to contain this index
|
||||
(for example, if list is of size 3 (indexes from 0 to 2), you can't assign value to index 4 unless you change list size to 5 first).
|
||||
|
||||
|
||||
2) Maps (or associative arrays) - a set of key=>value pairs, where all elements (values) are accessed by corresponding keys.
|
||||
Differences from list:
|
||||
- maps don't have specific size (to assign values, you don't need to resize array first);
|
||||
- keys, just like values, can be of any type (but avoid using -1 as array keys or you won't be able to use some functions reliably).
|
||||
|
||||
Both array types have their pros and cons and are suited for different tasks.
|
||||
|
||||
|
||||
>>> ARRAYS SYNTAX <<<
|
||||
|
||||
Basically arrays are implemented using number of new operators (scripting functions). But for ease of use, there are some new syntax elements:
|
||||
|
||||
1) Accessing elements. Use square brackets:
|
||||
|
||||
display_msg(arr[5]);
|
||||
mymap["price"] := 515.23;
|
||||
|
||||
2) Alternative accessing for maps. Use dot:
|
||||
|
||||
display_msg(mymap.name);
|
||||
mymap.price := 232.23;
|
||||
|
||||
3) Array expressions. Create and fill arrays with just one expression:
|
||||
|
||||
// create list with 5 values
|
||||
[5, 777, 0, 3.14, "Cool Value"]
|
||||
|
||||
// create map:
|
||||
{5: "Five", "health": 50, "speed": 0.252}
|
||||
|
||||
NOTES:
|
||||
- make sure to call "fix_array" if you want new array to be available in the next frame or "save_array" if you want to use it for a longer period
|
||||
(see next section for details)
|
||||
|
||||
|
||||
4) Iterating in loop. Use "foreach" key word like this:
|
||||
|
||||
foreach (item in myarray) begin
|
||||
// this block is executed for each array element, where "item" contains current value on each step
|
||||
end
|
||||
|
||||
// alternative syntax:
|
||||
foreach (key: item in myarray) begin
|
||||
// "key" will contain current key (or numeric index, for lists)
|
||||
end
|
||||
|
||||
See "Script editor\docs\sslc readme.txt" file for full information on new SSL syntax features.
|
||||
|
||||
>>> STORING ARRAYS <<<
|
||||
|
||||
Apart from lists/maps arrays are divided by how they are stored.
|
||||
There a 3 types of arrays:
|
||||
|
||||
1) Temporary. They are created using temp_array function or when using array expressions.
|
||||
Arrays of this type are auto-deleted at the end of the frame. So, for example, if you have a global script which runs at regular intervals,
|
||||
where you create temp_array, it will not be available next time your global script is executed.
|
||||
|
||||
2) Permanent. They are created using "create_array" function or "fix_array" (from pre-existing temporary array).
|
||||
This type of arrays are always available (by their ID) until you start a new game or load a saved game (at which point they are deleted).
|
||||
|
||||
3) Saved. If you want your array to really stay for a while, use function "save_array" to make any array "saved". However, they are, like permanent arrays,
|
||||
"deleted" from memory when loading game. In order to use them properly, you must load them from the savegame using "load_array" whenever you want to use them.
|
||||
Example:
|
||||
|
||||
variable savedArray;
|
||||
procedure start begin
|
||||
if game_loaded then begin
|
||||
savedArray := load_array("traps");
|
||||
end else begin
|
||||
foreach trap in traps begin
|
||||
....
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
|
||||
>>> PRACTICAL EXAMPLES <<<
|
||||
|
||||
> Use arrays to implement variable-argument procedures:
|
||||
|
||||
// define it
|
||||
procedure give_item(variable critter, variable pidList) begin
|
||||
foreach (pid: qty in pidList) begin
|
||||
give_pid_qty(critter, pid, qty);
|
||||
end
|
||||
end
|
||||
|
||||
// call it:
|
||||
call give_item(dude_obj, {PID_SHOTGUN: 1, PID_SHOTGUN_SHELLS: 4, PID_STIMPAK: 3});
|
||||
|
||||
|
||||
> Create arrays of objects (maps) for advanced scripting:
|
||||
|
||||
variable traps;
|
||||
procedure init_traps begin
|
||||
// just a quick example, there is a better way of doing it...
|
||||
traps := load_array("traps");
|
||||
if (traps == 0) then begin
|
||||
traps := [];
|
||||
save_array("traps", traps);
|
||||
end
|
||||
foreach k: v in traps begin
|
||||
traps[k] := load_array("trap_"+k); // each object is stored separately
|
||||
end
|
||||
end
|
||||
|
||||
procedure add_trap(variable trapArray) begin
|
||||
variable index;
|
||||
index := len_array(traps);
|
||||
save_array("trap_"+k, trapArray);
|
||||
array_push(traps, trapArray);
|
||||
end
|
||||
|
||||
// use them:
|
||||
foreach trap in traps begin
|
||||
if (self_elevation == trap["elev"] and tile_distance(self_tile, trap["tile"]) < trap["radius"]) then
|
||||
// kaboom!!!
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
|
||||
>>> ARRAY OPERATORS REFERENCE <<<
|
||||
|
||||
*mixed means any type
|
||||
|
||||
> int create_array(int size, int flags):
|
||||
- creates permanent array (but not "saved")
|
||||
- if size is >= 0, creates list with given size
|
||||
- if size == -1, creates map (associative array)
|
||||
- if size == -1 and flags == 2, creates a "lookup" map (associative array) in which the values of existing keys are read-only and can't be updated.
|
||||
This type of array allows you to store a zero (0) key value
|
||||
- NOTE: in earlier versions (up to 4.1.3/3.8.13) the second argument is not used, just use 0
|
||||
- returns arrayID (valid until array is deleted)
|
||||
|
||||
> int temp_array(int size, int flags):
|
||||
- works exactly like "create_array", only created array becomes "temporary"
|
||||
|
||||
> void fix_array(int arrayID):
|
||||
- changes "temporary" array into "permanent" ("permanent" arrays are not automatically saved into savegames)
|
||||
|
||||
> void set_array(int arrayID, mixed key, mixed value):
|
||||
- sets array value
|
||||
- if used on list, "key" must be numeric and within valid index range (0..size-1)
|
||||
- if used on map, key can be of any type
|
||||
- to "unset" a value from map, just set it to zero (0)
|
||||
- NOTE: to add a value of 0 for the key, use the float value of 0.0
|
||||
- this works exactly like statement:
|
||||
arrayID[key] := value;
|
||||
|
||||
> mixed get_array(int arrayID, mixed key):
|
||||
- returns array value by key or index
|
||||
- if key doesn't exist or index is not in valid range, returns 0
|
||||
- works exactly like expression:
|
||||
(arrayID[key])
|
||||
|
||||
> void resize_array(int arrayID, int size):
|
||||
- changes array size
|
||||
- applicable to maps too, but only to reduce elements
|
||||
- there are number of special negative values of "size" which perform various operations on the array,
|
||||
use macros sort_array, sort_array_reverse, reverse_array, shuffle_array from sfall.h header
|
||||
|
||||
> void free_array(int arrayID):
|
||||
- deletes any array
|
||||
- if array was "saved", it will be removed from a savegame
|
||||
|
||||
> mixed scan_array(int arrayID, mixed value):
|
||||
- searches for a first occurence of given value inside given array
|
||||
- if value is found, returns it's index (for lists) or key (for maps)
|
||||
- if value is not found, returns -1 (be careful, as -1 can be a valid key for a map)
|
||||
|
||||
> int len_array(int arrayID):
|
||||
- returns number of elements or key=>value pairs in a given array
|
||||
- if array is not found, returns -1 (can be used to check if given array exist)
|
||||
|
||||
> mixed array_key(int arrayID, int index):
|
||||
- don't use it directly; it is generated by the compiler in foreach loops
|
||||
- for lists, returns index back (no change)
|
||||
- for maps, returns a key at the specified numeric index (don't rely on the order in which keys are stored though)
|
||||
- can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map
|
||||
|
||||
> int arrayexpr(mixed key, mixed value):
|
||||
- don't use it directly; it is used by compiler to create array expressions
|
||||
- assigns value to a given key in an array, created by last "create_array" or "temp_array" call
|
||||
- always returns 0
|
||||
|
||||
> void save_array(mixed key, int arrayID):
|
||||
- makes the array saveable; it will be saved in sfallgv.sav file when saving the game
|
||||
- arrayID is associated with given "key"
|
||||
- array becomes permanent (if it was temporary) and "saved"
|
||||
- key can be of any type (int, float or string)
|
||||
- if you specify 0 as the key for the array ID, it will make the array "unsaved"
|
||||
|
||||
> int load_array(mixed key):
|
||||
- load array from savegame data by the same key provided in "save_array"
|
||||
- arrayID is returned or zero (0) if none found
|
||||
|
||||
|
||||
|
||||
>>> BACKWARD COMPATIBILITY NOTES <<<
|
||||
|
||||
For those who used arrays in their mods before sfall 3.4:
|
||||
1) There is an INI parameter "arraysBehavior" in "Misc" section of ddraw.ini. If set to 0, all scripts which used sfall arrays before should work. This basically changes that "create_array" will create permanent arrays which are "saved" by default and their ID is also permanent. It is 1 by default.
|
||||
2) How savegame compatibility is handled?
|
||||
Saved arrays are stored in sfallgv.sav file (in savegame) in new (more flexible) format, just after the old arrays. So basically, when you load older savegame, sfall will load arrays from old format and save them to new format on next game save. If you load savegame made with sfall 3.4 using sfall 3.3 (for example), game shouldn't crash, but all arrays will be lost.
|
||||
3) Previously you had to specify size in bytes for array elements. This parameter is now ignored and you can store strings of arbitrary length in arrays.
|
||||
|
||||
@@ -189,7 +189,7 @@
|
||||
|
||||
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.
|
||||
__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
|
||||
@@ -257,9 +257,9 @@
|
||||
|
||||
Run when checking to see if a hex blocks movement or shooting. (or ai-ing, presumably...)
|
||||
|
||||
__NOTE:__ these hook scripts can become very CPU-intensive and you should avoid using them.
|
||||
For this reason, they may be removed in future versions.
|
||||
If you want to check if some tile or path is blocked, use functions: `obj_blocking_tile`, `obj_blocking_line`, `path_find_to`.
|
||||
__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.
|
||||
|
||||
```
|
||||
@@ -316,7 +316,7 @@
|
||||
* 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.
|
||||
__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
|
||||
@@ -360,7 +360,8 @@
|
||||
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)));`
|
||||
Example message (vanilla behavior):<br>
|
||||
`display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg3 * 2), obj_name(arg2)));`
|
||||
|
||||
```
|
||||
Critter arg0 - Thief
|
||||
@@ -376,7 +377,9 @@
|
||||
doc: |
|
||||
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.
|
||||
__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.
|
||||
|
||||
@@ -430,7 +433,7 @@
|
||||
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.
|
||||
__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.
|
||||
|
||||
```
|
||||
@@ -449,7 +452,7 @@
|
||||
Runs after calculating character figure FID on the inventory screen, whenever the game decides that character appearance might change.
|
||||
Also happens on other screens, like barter.
|
||||
|
||||
__NOTE:__ FID has following format: 0x0ABBCDDD, where A is object type, BB - animation code (always 0 in this case), C - weapon code, DDD - FRM index in LST file.
|
||||
__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
|
||||
@@ -596,7 +599,7 @@
|
||||
doc: |
|
||||
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.
|
||||
__NOTE:__ The user critter can't be overridden when using Steal skill.
|
||||
|
||||
```
|
||||
Critter arg0 - the user critter (usually dude_obj)
|
||||
|
||||
@@ -56,7 +56,7 @@ Use zero (0) as the second argument to unregister the hook from the current glob
|
||||
#### `void register_hook_proc_spec(int hookID, procedure proc)`
|
||||
Works very similar to `register_hook_proc`, except that it registers the current 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). All scripts hooked to a single hook point with this function are executed in exact order of how they were registered, as opposed to the description below, which refers to using `register_hook` and `register_hook_proc` functions.
|
||||
|
||||
__NOTE:__ you can hook several scripts to a single hook point, for example if it's different mods from different authors or just some different aspects of one larger mod. In this case scripts are executed in reverse order of how they were registered. When one of the scripts in a chain returns value with `set_sfall_return`, the next script may override this value if calls `set_sfall_return` again. Sometimes you need to multiply certain value in a chain of hook scripts.
|
||||
__NOTE:__ You can hook several scripts to a single hook point, for example, if it's different mods from different authors or just some different aspects of one larger mod. In this case scripts are executed in reverse order of how they were registered. When one of the scripts in a chain returns value with `set_sfall_return`, the next script may override this value if calls `set_sfall_return` again. Sometimes you need to multiply certain value in a chain of hook scripts.
|
||||
|
||||
Example: let's say we have a Mod A which reduces all "to hit" chances by 50%. The code might look like this:
|
||||
```js
|
||||
@@ -256,7 +256,7 @@ Runs when:
|
||||
|
||||
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.
|
||||
__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
|
||||
@@ -276,7 +276,7 @@ Runs when:
|
||||
|
||||
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.
|
||||
__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
|
||||
@@ -305,7 +305,7 @@ Obj arg4 - The destination object when the item is moved to another object,
|
||||
|
||||
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.
|
||||
__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)
|
||||
@@ -347,9 +347,9 @@ int ret0 - the new AP cost
|
||||
|
||||
Run when checking to see if a hex blocks movement or shooting. (or ai-ing, presumably...)
|
||||
|
||||
__NOTE:__ these hook scripts can become very CPU-intensive and you should avoid using them.
|
||||
For this reason, they may be removed in future versions.
|
||||
If you want to check if some tile or path is blocked, use functions: `obj_blocking_tile`, `obj_blocking_line`, `path_find_to`.
|
||||
__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.
|
||||
|
||||
```
|
||||
@@ -385,7 +385,7 @@ int ret1 - The new maximum damage
|
||||
|
||||
Runs when calculating ammo cost for a weapon. Doesn't affect damage, only how much ammo is spent.
|
||||
By default, weapon will shoot when at least 1 round is left, regardless of ammo cost calculations.
|
||||
To add proper check for ammo before shooting and proper calculation of number of burst rounds (hook type 1 and 2 in arg3), set **CheckWeaponAmmoCost=1** in **Misc** section of ddraw.ini.
|
||||
To add proper check for ammo before shooting and proper calculation of number of burst rounds (hook type 1 and 2 in `arg3`), set **CheckWeaponAmmoCost=1** in **Misc** section of ddraw.ini.
|
||||
|
||||
```
|
||||
Item arg0 - The weapon
|
||||
@@ -409,7 +409,7 @@ 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.
|
||||
__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
|
||||
@@ -457,7 +457,8 @@ Runs when checking an attempt to steal or plant an item in other inventory using
|
||||
|
||||
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)));`
|
||||
Example message (vanilla behavior):<br>
|
||||
`display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg3 * 2), obj_name(arg2)));`
|
||||
|
||||
```
|
||||
Critter arg0 - Thief
|
||||
@@ -474,7 +475,9 @@ int ret0 - overrides hard-coded handler (1 - force success, 0 - force fail,
|
||||
|
||||
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.
|
||||
__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.
|
||||
|
||||
@@ -531,7 +534,7 @@ int ret0 - Override setting (-1 - use engine handler, any other value - prev
|
||||
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.
|
||||
__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.
|
||||
|
||||
```
|
||||
@@ -551,7 +554,7 @@ int ret0 - overrides hard-coded handler (-1 - use engine handler, any other
|
||||
Runs after calculating character figure FID on the inventory screen, whenever the game decides that character appearance might change.
|
||||
Also happens on other screens, like barter.
|
||||
|
||||
__NOTE:__ FID has following format: 0x0ABBCDDD, where A is object type, BB - animation code (always 0 in this case), C - weapon code, DDD - FRM index in LST file.
|
||||
__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
|
||||
@@ -666,6 +669,7 @@ int ret1 - overrides the result of engine calculation: 0/1 - failure, 2/3 -
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
@@ -680,7 +684,7 @@ int ret0 - a pointer to the new text received by using get_string_pointer fu
|
||||
|
||||
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.
|
||||
__NOTE:__ The user critter can't be overridden when using Steal skill.
|
||||
|
||||
```
|
||||
Critter arg0 - the user critter (usually dude_obj)
|
||||
@@ -776,7 +780,7 @@ int ret1 - overrides the duration time for the current result
|
||||
|
||||
Runs before or after Fallout engine 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.
|
||||
__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 define.h)
|
||||
@@ -867,7 +871,7 @@ int arg1 - the value of roll result (see ROLL_* constants), which is calcula
|
||||
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 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
|
||||
```
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -73,7 +73,7 @@ The `list_xxx` functions can be used to loop over all items on a map. `list_begi
|
||||
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 `int`, `float` and `string` 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. You must remember to free any arrays you create with `create_array` when you are done with them, or you will leak memory. 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.<br>
|
||||
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.<br>
|
||||
__NOTE:__ the above description only applies when **arraysBehavior** is set to 0 in ddraw.ini. Refer to **arrays.md** for detailed description of new arrays behavior.
|
||||
|
||||
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.
|
||||
@@ -216,7 +216,7 @@ FUNCTION REFERENCE
|
||||
##### `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.
|
||||
- `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.
|
||||
|
||||
-----
|
||||
##### `void set_critter_pickpocket_mod(object, int max, int mod)`
|
||||
@@ -308,7 +308,7 @@ FUNCTION REFERENCE
|
||||
-----
|
||||
##### `string substr(string, start, 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 starting position from the end of the string (for example `substr("test", -2, 2)` will return last 2 charactes: "st").
|
||||
- If `start` is negative - it indicates starting position 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).
|
||||
|
||||
@@ -367,9 +367,11 @@ FUNCTION REFERENCE
|
||||
|
||||
-----
|
||||
##### `float sin(float x)`
|
||||
- Sine of `x`.
|
||||
|
||||
-----
|
||||
##### `float cos(float x)`
|
||||
- Cosine of `x`.
|
||||
|
||||
-----
|
||||
##### `float tan(float x)`
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user