fallout2sfall/sfall
0
0
Fork 0
mirror of https://github.com/sfall-team/sfall.git synced 2026-07-27 16:52:34 -07:00
Code Issues Packages Projects Releases Wiki Activity

Updated files for online documents

Browse Source 
Fixed typos in hookscripts.md & sslc_readme.txt.
This commit is contained in:
NovaRain
2021-05-18 11:31:20 +08:00
parent 9ce3a42102
commit 6b368e6a69
5 changed files with 213 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
artifacts/scripting/compiler/sslc_readme.txt
+1 -1
View File
@@ -90,7 +90,7 @@ old:
x := 5;
> Multiple variable decleration: Multiple variables can be declared on one line, seperated by commas. This is an alterative to the ugly begin/end block, or the bulky single variable per line style.
> Multiple variable declaration: Multiple variables can be declared on one line, seperated by commas. This is an alterative to the ugly begin/end block, or the bulky single variable per line style.
new:
variable a, b, c;
artifacts/scripting/functions.yml
+12 -2
View File
@@ -1151,7 +1151,7 @@
items:
- name: init_hook
detail: int init_hook()
doc: The hook script equivalent of game_loaded; it returns 2 when the script is first loaded, 1 when the player reloads and 0 otherwise.
doc: The hook script equivalent of `game_loaded`; it returns 1 when the script is loaded for the first time or when the player reloads the game, and 0 otherwise.
opcode: 0x81ea
- name: get_sfall_arg
detail: mixed get_sfall_arg()
@@ -1743,6 +1743,16 @@
doc: 'Redraws inventory items list in the inventory/loot/barter screens. Argument invSide specifies which side needs to be redrawn: 0 - the player, 1 - target (container/NPC in loot/barter screens), -1 - both sides (same as without argument).'
macro: sfall.h
- name: Pip-Boy
parent: Interface
items:
- name: set_quest_failure_value
detail: void sfall_func2("set_quest_failure_value", int gvarNumber, int thresholdValue)
doc: |
- 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
- name: Cursor
parent: Interface
items:
@@ -1860,7 +1870,7 @@
- True - only checks critters and ignores their cover (roof tiles, walls, scenery, etc.)
- False - checks all objects (can't check critters under objects)
- passing False to the includeDude argument will ignore dude_obj
**NOTE:** the function will always return 0 if the cursor is in movement mode (hexagon cursor).
- **NOTE:** to get an object located on a tile when the cursor is in movement mode (hexagon cursor), use the `tile_under_cursor` function
macro: sfall.h
- name: get_object_data
artifacts/scripting/hooks.yml
+145 -69
View File
@@ -14,8 +14,8 @@
```
int arg0 - The hit chance (capped)
critter arg1 - The attacker
critter arg2 - The target of the attack
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 (one of ATKTYPE_*)
@@ -31,27 +31,30 @@
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 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
Critter ret2 - Override the target of the attack
```
- name: CalcAPCost
id: HOOK_CALCAPCOST
doc: |
Runs whenever Fallout is calculating the AP cost of using the weapon (or unarmed attack). Doesn't run for using other item types or moving. Note that the first time a game is loaded, this script doesn't run before the initial interface is drawn, so if the script effects the AP cost of whatever is in the player's hands at the time the wrong AP cost will be shown. It will be fixed the next time the interface is redrawn. You can get the weapon object by checking item slot based on attack type (`ATKTYPE_LWEP1`, `ATKTYPE_LWEP2`, etc) and then calling `critter_inven_obj()`.
Runs whenever Fallout is calculating the AP cost of using the weapon (or unarmed attack). Doesn't run for using other item types or moving.
Note that the first time a game is loaded, this script doesn't run before the initial interface is drawn, so if the script effects the AP cost of whatever is in the player's hands at the time the wrong AP cost will be shown. It will be fixed the next time the interface is redrawn.
You can get the weapon object by checking item slot based on attack type (`ATKTYPE_LWEP1`, `ATKTYPE_LWEP2`, etc) and then calling `critter_inven_obj`.
```
critter arg0 - The critter performing the action
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 normal AP cost
int arg3 - The default AP cost
Item arg4 - The weapon for which the cost is calculated. If it is 0, the pointer to the weapon can still be obtained by the aforementioned method
int ret0 - The new AP cost
```
@@ -60,13 +63,12 @@
id: HOOK_DEATHANIM1
doc: |
Runs before Fallout tries to calculate the death animation. Lets you switch out which weapon Fallout sees.
Does not run for critters in the knockdown/out state.
```
int arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
critter arg1 - The attacker
critter arg2 - The target
Critter arg1 - The attacker
Critter arg2 - The target
int arg3 - The amount of damage
int arg4 - Unused, always -1. Use this if you are using the same procedure for HOOK_DEATHANIM1 and HOOK_DEATHANIM2 (since sfall 4.1/3.8.24)
@@ -76,14 +78,14 @@
- name: DeathAnim2
id: HOOK_DEATHANIM2
doc: |
Runs after Fallout has calculated the death animation. Lets you set your own custom frame id, so more powerful than hs_deathanim1, but performs no validation.
When using `critter_dmg` function, this script will also run. In that case weapon pid will be `-1` and attacker will point to an object with `obj_art_fid == 0x20001F5`.
Runs after Fallout has calculated the death animation. Lets you set your own custom frame id, so more powerful than `HOOK_DEATHANIM1`, but performs no validation.
When using `critter_dmg` function, this script will also run. In that case weapon pid will be -1 and attacker will point to an object with `obj_art_fid == 0x20001F5`.
Does not run for critters in the knockdown/out state.
```
item arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
critter arg1 - The attacker
critter arg2 - The target
Item arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
Critter arg1 - The attacker
Critter arg2 - The target
int arg3 - The amount of damage
int arg4 - The death anim id calculated by Fallout
@@ -101,8 +103,8 @@
Does not run for misses, or non-combat damage like dynamite explosions.
```
critter arg0 - The target
critter arg1 - The attacker
Critter arg0 - The target
Critter arg1 - The attacker
int arg2 - The amount of damage to the target
int arg3 - The amount of damage to the attacker
int arg4 - The special effect flags for the target (use bwand DAM_* to check specific flags)
@@ -127,28 +129,36 @@
doc: |
Runs immediately after a critter dies for any reason. No return values; this is just a convenience for when you need to do something after death for a large number of different critters and don't want to have to script each and every one of them.
`Critter arg0 - The critter that just died`
```
Critter arg0 - The critter that just died
```
- name: FindTarget
id: HOOK_FINDTARGET
doc: |
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
Runs when the AI is trying to pick a target in combat. Fallout first chooses a list of 4 likely suspects, then normally sorts them in order of weakness/distance/etc depending on the AI caps of the attacker.
This hook replaces that sorting function, allowing you to sort the targets in some arbitrary way.
The return values can include critters that weren't in the list of possible targets, but the additional targets may still be discarded later on in the combat turn if they are out of the attackers perception or the chance of a successful hit is too low. The list of possible targets often includes duplicated entries.
Use `sfall_return` to give the 4 targets, in order of preference. If you want to specify less than 4 targets, fill in the extra spaces with 0's or pass -1 to skip the return value.
The return values can include critters that weren't in the list of possible targets, but the additional targets may still be discarded later on in the combat turn if they are out of the attackers perception or the chance of a successful hit is too low. The list of possible targets often includes duplicated entries, but this is fixed in sfall 4.2.3/3.8.23.
Use `set_sfall_return` to give the 4 targets, in order of preference. If you want to specify less than 4 targets, fill in the extra spaces with 0's or pass -1 to skip the return value.
__NOTE:__ The engine can choose targets by the following criteria:
1) The nearest enemy to the attacker.
2) The enemy that attacked the attacker.
3) The enemy that attacked an NPC from the same team as the attacker.
4) The enemy that is attacked by an NPC from the same team as the attacker.
```
critter arg0 - The attacker
critter arg1 - A possible target
critter arg2 - A possible target
critter arg3 - A possible target
critter arg4 - A possible target
Critter 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
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
```
- name: UseObjOn
@@ -177,12 +187,13 @@
1. a critter uses an object from inventory which have "Use" action flag set or it's an active flare or dynamite.
2. player uses an object from main interface
This is fired before the object is used, and the relevant use_obj script procedures are run. You can disable default item behavior.
This is fired before the object is used, and the relevant `use_obj` script procedures are run. You can disable default item behavior.
__NOTE:__ you can't remove and/or destroy this object during the hookscript (game will crash otherwise). To remove it, return 1.
```
Critter arg0 - The user
int arg1 - The object used
Obj arg1 - The object used
int ret0 - overrides hard-coded handler and selects what should happen with the item (0 - place it back, 1 - remove it, -1 - use engine handler)
```
@@ -194,7 +205,7 @@
```
Obj arg0 - the owner that the object is being removed from
item arg1 - the item that is being removed
Item arg1 - the item that is being removed
int arg2 - the number of items to remove
int arg3 - The reason the object is being removed (see RMOBJ_* constants)
Obj arg4 - The destination object when the item is moved to another object, 0 otherwise
@@ -205,17 +216,16 @@
doc: |
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)
critter arg1 - the critter being bartered with
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)
Critter arg3 - table of requested goods (being bought from NPC)
int arg4 - the amount of actual caps in the barter stack (as opposed to goods)
int arg5 - the value of all goods being traded before skill modifications
critter arg6 - table of offered goods (being sold to NPC)
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 a party member), 0 otherwise
int arg9 - 1 if trading with a party member, 0 otherwise
@@ -227,7 +237,7 @@
- name: MoveCost
id: HOOK_MOVECOST
doc: |
Runs when calculating the AP cost of movement
Runs when calculating the AP cost of movement.
```
Critter arg0 - the critter doing the moving
@@ -250,24 +260,26 @@
__NOTE:__ these hook scripts can become very CPU-intensive and you should avoid using them.
For this reason, they may be removed in future versions.
If you want to check if some tile or path is blocked, use functions: `obj_blocking_tile`, `obj_blocking_line`, `path_find_to`.
If you want script to be called every time NPC moves by hex in combat, use `hs_movecost hook`.
If you want script to be called every time NPC moves by hex in combat, use `HOOK_MOVECOST` hook.
```
Critter arg0 - the critter doing the moving
int arg1 - the tile number being checked
int arg2 - the elevation being checked
int arg3 - 1 if the hex would normally be blocking
object* ret0 - 0 if the hex doesn't block, or any sort of object pointer if it does
Obj ret0 - 0 if the hex doesn't block, or any sort of object pointer if it does
```
- name: ItemDamage
id: HOOK_ITEMDAMAGE
doc: |
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)
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
@@ -281,22 +293,27 @@
doc: |
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 `Misc.CheckWeaponAmmoCost=1` in 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 - weapon
int arg1 - Number of bullets in burst (1 for single shots)
int arg2 - Ammo cost calculated by original function (this is basically 2 for Super Cattle Prod and Mega Power Fist)
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)
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, calculated by the original ammo cost function (this is basically 2 for Super Cattle Prod and Mega Power Fist)
NOTE: for hook type 2, this value is the ammo cost per round (default is always 1)
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 - new ammo cost value (set to 0 for unlimited ammo)
int ret0 - The new amount of ammo to be consumed, or ammo cost per round for hook type 2 (set to 0 for unlimited ammo)
```
- name: KeyPress
id: HOOK_KEYPRESS
doc: |
Runs once every time when any key was pressed or released.
* DX codes: (see dik.h header)
* 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.
@@ -324,7 +341,7 @@
doc: |
Runs when using any skill on any object.
This is fired before the default handlers are called, which you can override. In this case you should write your own skill use handler entirely, or otherwise nothing will happen (this includes fade in/fade out, time lapsing and messages - all of this can be scripted; to get vanilla text messages - use `message_str_game()` along with `sprintf()`).
This is fired before the default handlers are called, which you can override. In this case you should write your own skill use handler entirely, or otherwise nothing will happen (this includes fade in/fade out, time lapsing and messages - all of this can be scripted; to get vanilla text messages - use `message_str_game` along with `sprintf`).
Suggested use - override first aid/doctor skills to buff/nerf them, override steal skill to disallow observing NPCs inventories in some cases.
Doesn't seem to run when lock picking.
@@ -343,7 +360,7 @@
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): `display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg3*2), obj_name(arg2)));`
```
Critter arg0 - Thief
@@ -373,7 +390,10 @@
3 - when AI determines whether it sees a potential target when selecting attack targets
0 - all other cases
int ret0 - overrides the returned result of the function: 0 - not in range (can't see), 1 - in range (will see if not blocked), 2 - forced detection (will see regardless, only used in obj_can_see_obj scripting function which is called by every critter in the game)
int ret0 - overrides the returned result of the function:
0 - not in range (can't see)
1 - in range (will see if not blocked)
2 - forced detection (will see regardless, only used in obj_can_see_obj scripting function which is called by every critter in the game)
```
- name: InventoryMove
@@ -388,7 +408,16 @@
- apply or remove some special scripted effects depending on PC's armor
```
int arg0 - Target slot (0 - main backpack, 1 - left hand, 2 - right hand, 3 - armor slot, 4 - weapon, when reloading it by dropping ammo, 5 - container, like bag/backpack, 6 - dropping on the ground, 7 - picking up item, 8 - dropping item on the character portrait)
int arg0 - Target slot:
0 - main backpack
1 - left hand
2 - right hand
3 - armor slot
4 - weapon, when reloading it by dropping ammo
5 - container, like bag/backpack
6 - dropping on the ground
7 - picking up item
8 - dropping item on the character portrait
Item arg1 - Item being moved
Item arg2 - Item being replaced, weapon being reloaded, or container being filled (can be 0)
@@ -400,12 +429,13 @@
doc: |
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.
```
Critter arg0 - critter
Obj arg1 - item being wielded or unwielded (weapon/armor)
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
@@ -434,8 +464,12 @@
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)
int arg1 - critter doing the turn
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
bool arg2 - 1 at the start/end of the player's turn after loading a game saved in combat mode, 0 otherwise
int ret0 - pass 1 at the start of turn to skip the turn, pass -1 at the end of turn to force end of combat
@@ -446,6 +480,7 @@
doc: |
Runs before Fallout executes a standard procedure (handler) in any script of any object.
NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures.
```
int arg0 - the number of the standard script handler (see define.h)
Obj arg1 - the object that owns this handler (self_obj)
@@ -459,6 +494,7 @@
doc: |
Runs after Fallout executes a standard procedure (handler) in any script of any object.
NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures.
```
int arg0 - the number of the standard script handler (see define.h)
Obj arg1 - the object that owns this handler (self_obj)
@@ -509,6 +545,7 @@
id: HOOK_GAMEMODECHANGE
doc: |
Runs once every time when the game mode was changed, like opening/closing the inventory, character screen, pipboy, etc.
```
int arg0 - event type: 1 - when the player exits the game, 0 - otherwise
int arg1 - the previous game mode
@@ -558,6 +595,7 @@
id: HOOK_USESKILLON
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.
```
@@ -577,11 +615,11 @@
```
int arg0 - event type: 1 - when checking objects within the explosion radius without causing damage (e.g. the player drops an active explosive), 0 - otherwise
Critter arg1 - The attacker
int arg2 - The tile on which the explosion occurs
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
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
@@ -593,21 +631,21 @@
This hook overrides the vanilla damage calculation formula.
Runs when:
1. Before the game calculates how much damage each target will get. This includes primary target as well as all extras (explosions and bursts).
1. AI decides whether it is safe to use area attack (burst, grenades), if he might hit friendlies.
2. AI decides whether it is safe to use area attack (burst, grenades), if he might hit friendlies.
Does not run for misses, non-combat damage like dynamite explosions, or if one of the damage formulas is selected in ddraw.ini.
```
Critter arg0 - the attacker
Critter arg1 - the target
Obj arg2 - the weapon used in the attack
int arg3 - attack Type (see ATKTYPE_* constants)
Item arg2 - the weapon used in the attack
int arg3 - attack type (see ATKTYPE_* constants)
int arg4 - number of bullets actually hit the target (1 for melee attacks)
int arg5 - target's Damage Resistance (DR) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
int arg6 - target's Damage Threshold (DT) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
int arg7 - bonus ranged damage from the perk
int arg8 - damage Multiplier (this is divided by 2, so a value of 3 does 1.5x damage, and 8 does 4x damage. Usually it's 2; for critical hits, the value is taken from the critical table; with Silent Death perk and the corresponding attack conditions, the value will be doubled)
int arg9 - combat Difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it's always 100)
int arg8 - damage multiplier (this is divided by 2, so a value of 3 does 1.5x damage, and 8 does 4x damage. Usually it's 2; for critical hits, the value is taken from the critical table; with Silent Death perk and the corresponding attack conditions, the value will be doubled)
int arg9 - combat difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it's always 100)
int arg10 - the calculated amount of damage (usually 0, required when using multiple hook scripts to calculate damage and using the set_sfall_arg function)
mixed arg11 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)
@@ -648,6 +686,7 @@
doc: |
Runs when the targeting cursor hovers over an object, or when the player tries to attack the target object.
You can override the target object or prevent the player from attacking the chosen target.
```
int arg0 - event type: 0 - when the targeting cursor hovers over the object, 1 - when trying to attack the target object
int arg1 - 1 when the target object is valid to attack, 0 otherwise
@@ -661,6 +700,7 @@
doc: |
Runs whenever a random encounter occurs (except the Horrigan meeting and scripted encounters), or when the player enters a local map from the world map.
You can override the map for loading or the encounter.
```
int arg0 - event type: 0 - when a random encounter occurs, 1 - when the player enters from the world map
int arg1 - the map ID that the encounter will load (see MAPS.h or Maps.txt)
@@ -674,6 +714,7 @@
id: HOOK_ADJUSTPOISON
doc: |
Runs when a critter's poison level is changed, or when the player takes damage from the poison.
```
Critter arg0 - the critter
int arg1 - the amount of poison being added/removed
@@ -682,21 +723,25 @@
int ret0 - the new amount of poison being added/removed
int ret1 - the new damage value, only negative values are allowed (will only be valid at the time of taking damage from the poison)
````
```
- name: AdjustRads
id: HOOK_ADJUSTRADS
doc: |
Runs when a critter's radiation level is changed.
```
Critter arg0 - the critter (usually dude_obj)
int arg1 - the amount of radiation being added/removed
int ret0 - the new amount of radiation being added/removed
```
- name: RollCheck
id: HOOK_ROLLCHECK
doc: |
Runs when a game event performs a random roll to check the chance of success or failure.
```
int arg0 - event type:
1 - checks the chance of an attack hitting the target
@@ -715,3 +760,34 @@
int ret0 - overrides the roll result
```
- name: BestWeapon
id: HOOK_BESTWEAPON
doc: |
Runs when the AI decides which weapon is the best while searching the inventory for a weapon to equip in combat.
This also runs when the player presses the "Use Best Weapon" button on the party member control panel.
```
Critter arg0 - the critter searching for a weapon
Item arg1 - the best weapon chosen from two items
Item arg2 - the first choice of weapon
Item arg3 - the second choice of weapon
Critter arg4 - the target of the critter (can be 0)
Item ret0 - overrides the chosen best weapon
```
- name: CanUseWeapon
id: HOOK_CANUSEWEAPON
doc: |
Run when the AI checks whether it can use a weapon.
This mostly happens when NPCs try to find weapons in their inventory or on the map.
```
Critter arg0 - the critter doing the check
Item arg1 - the weapon being checked
int arg2 - attack type (see ATKTYPE_* constants)
int arg3 - original result of engine function: 1 - can use, 0 - can't use
int ret0 - overrides the result of engine function. Any non-zero value allows using the weapon
```
artifacts/scripting/hookscripts.md
+14 -14
View File
@@ -87,8 +87,8 @@ The defines to use for the hookID are in **sfall.h**.
#### `HOOK_TOHIT (hs_tohit.int)`
Runs when Fallout is calculating the chances of an attack striking a target
Runs after the hit chance is fully calculated normally, including applying the 95% cap
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)
@@ -107,7 +107,7 @@ int ret0 - the new hit chance
#### `HOOK_AFTERHITROLL (hs_afterhitroll.int)`
Runs after Fallout has decided if an attack will hit or miss
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
@@ -160,7 +160,7 @@ int ret0 - The pid of an object to override the attacking weapon with
#### `HOOK_DEATHANIM2 (hs_deathanim2.int)`
Runs after Fallout has calculated the death animation. Lets you set your own custom frame id, so more powerful than `HOOK_DEATHANIM2`, but performs no validation.
Runs after Fallout has calculated the death animation. Lets you set your own custom frame id, so more powerful than `HOOK_DEATHANIM1`, but performs no validation.
When using `critter_dmg` function, this script will also run. In that case weapon pid will be -1 and attacker will point to an object with `obj_art_fid == 0x20001F5`.
Does not run for critters in the knockdown/out state.
@@ -308,13 +308,13 @@ 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
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)
Critter arg3 - table of requested goods (being bought from NPC)
int arg4 - the amount of actual caps in the barter stack (as opposed to goods)
int arg5 - the value of all goods being traded before skill modifications
critter arg6 - table of offered goods (being sold to NPC)
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 a party member), 0 otherwise
int arg9 - 1 if trading with a party member, 0 otherwise
@@ -345,7 +345,7 @@ int ret0 - the new AP cost
* `HOOK_HEXSHOOTBLOCKING (hs_hexshootblocking.int)`
* `HOOK_HEXSIGHTBLOCKING (hs_hexsightblocking.int)`
Runs when checking to see if a hex blocks movement or shooting. (or ai-ing, presumably...)
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.
@@ -375,7 +375,7 @@ 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 ret2 isn't given, or the new minimum damage if it is
int ret0 - Either the damage to be used, if ret1 isn't given, or the new minimum damage if it is
int ret1 - The new maximum damage
```
@@ -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 arg4), 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
@@ -457,7 +457,7 @@ 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) + arg4*2), obj_name(arg3)));`
Example message (vanilla behavior): `display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg3*2), obj_name(arg2)));`
```
Critter arg0 - Thief
@@ -815,7 +815,7 @@ int arg1 - the map ID that the encounter will load (see MAPS.h or Maps.txt)
int arg2 - 1 when the encounter occurs is a special encounter, 0 otherwise
int ret0 - overrides the map ID, or pass -1 for event type 0 to cancel the encounter and continue traveling
int ret1 - pass 1 to cancel the encounter and load the specified map from the ret1 (only for event type 0)
int ret1 - pass 1 to cancel the encounter and load the specified map from the ret0 (only for event type 0)
```
-------------------------------------------
@@ -867,7 +867,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
```
docs/arrays.md
+34 -32
View File
@@ -20,14 +20,14 @@ See array function reference [here]({{ site.baseurl }}/array-functions/).
## Arrays concept
Array elements are accessed by index or key. For example:
```c++
// this code puts some string in array "list" at index 5:
list[5] := "Value";
```
There are 2 different types of arrays currently available:
* 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.
* **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:
```c++
@@ -40,8 +40,8 @@ There are 2 different types of arrays currently available:
- 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).
* **Maps** (or associative arrays) - a set of key=>value pairs, where all elements (values) are accessed by corresponding keys.
* 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).
@@ -58,11 +58,13 @@ Basically arrays are implemented using number of new operators (scripting functi
display_msg(arr[5]);
mymap["price"] := 515.23;
```
* Alternative accessing for maps. Use dot:
```js
display_msg(mymap.name);
mymap.price := 232.23;
```
* Array expressions. Create and fill arrays with just one expression:
```c++
// create list with 5 values
@@ -71,12 +73,10 @@ Basically arrays are implemented using number of new operators (scripting functi
// 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).
* Iterating in loop. Use "foreach" key word like this:
* Iterating in loop. Use `foreach` key word like this:
```js
foreach (item in myarray) begin
// this block is executed for each array element, where "item" contains current value on each step
@@ -88,26 +88,26 @@ Basically arrays are implemented using number of new operators (scripting functi
end
```
See "Script editor\docs\sslc readme.txt" file for full information on new SSL syntax features.
See "scripting_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:
* Temporary. They are created using `temp_array` function or when using array expressions.
* **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.
* Permanent. They are created using `create_array` function or `fix_array` (from pre-existing temporary array).
* **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).
* 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:
* **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.
```js
variable savedArray;
procedure start begin
Example:
```js
variable savedArray;
procedure start begin
if game_loaded then begin
savedArray := load_array("traps");
end else begin
@@ -115,13 +115,12 @@ procedure start begin
....
end
end
end
```
end
```
## Practical examples
### Use arrays to implement variable-argument procedures
```js
// define it
procedure give_item(variable critter, variable pidList) begin
@@ -135,7 +134,6 @@ call give_item(dude_obj, {PID_SHOTGUN: 1, PID_SHOTGUN_SHELLS: 4, PID_STIMPAK: 3}
```
### Create arrays of objects (maps) for advanced scripting
```js
variable traps;
procedure init_traps begin
@@ -167,15 +165,14 @@ end
## Array operators reference
*mixed means any type
_*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
- if `size >= 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)`:
@@ -189,9 +186,8 @@ end
- 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;`
* 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
@@ -228,20 +224,26 @@ end
- 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
- loads array from savegame data by the same key provided in `save_array`
- returns array ID or zero (0) if none found
## Backward compatibility notes
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.
* If `arraysBehaviour=0`:
* 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.
* If `ArraysBehaviour=0`:
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/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.
* 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.
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.