Backported three game hooks from 4.x:

* ROLLCHECK, BESTWEAPON, CANUSEWEAPON

Updated documents.

artifacts/ddraw.ini

@@ -131,7 +131,7 @@ OverrideMusicDir=1
 ;This will slightly increase the startup time of the game on older computers
 AutoSearchSFX=1
 
-;Uncomment these lines to override the names of sound files for game modes
+;Uncomment these lines to override the names of sound files used by the engine
 ;Filenames are limited to 8 characters (without extension)
 ;MainMenuMusic=07desert
 ;WorldMapMusic=23world

artifacts/scripting/headers/sfall.h

@@ -70,6 +70,11 @@
 #define HOOK_STDPROCEDURE_END (41)
 #define HOOK_TARGETOBJECT     (42)
 #define HOOK_ENCOUNTER        (43)
+//#define HOOK_ADJUSTPOISON     (44) // unimplemented
+//#define HOOK_ADJUSTRADS       (45) // unimplemented
+#define HOOK_ROLLCHECK        (46)
+#define HOOK_BESTWEAPON       (47)
+#define HOOK_CANUSEWEAPON     (48)
 
 // Valid arguments to list_begin
 #define LIST_CRITTERS    (0)
@@ -261,6 +266,7 @@
 #define check_pid(pid)                                  (get_proto_data(pid, 0) != -1)
 
 // sets the status of an unusable weapon that cannot be used in combat
+// use the HOOK_CANUSEWEAPON hook with weapon_is_unusable macro to override the engine value
 #define set_weapon_unusable(item)                       set_object_data(item, OBJ_DATA_MISC_FLAGS, get_object_data(item, OBJ_DATA_MISC_FLAGS) bwor  0x00000010)
 #define set_weapon_usable(item)                         set_object_data(item, OBJ_DATA_MISC_FLAGS, get_object_data(item, OBJ_DATA_MISC_FLAGS) bwand 0xFFFFFFEF)
 #define weapon_is_unusable(item)                        (get_object_data(item, OBJ_DATA_MISC_FLAGS) bwand 0x00000010)

artifacts/scripting/hookscripts.md

@@ -795,3 +795,62 @@ 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 ret0 (only for event type 0)
 ```
+
+-------------------------------------------
+
+#### `HOOK_ROLLCHECK (hs_rollcheck.int)`
+
+Runs when a game event performs a random roll to check the chance of success or failure.
+
+```
+int     arg0 - event type:
+               1 - checks the chance of an attack hitting the target
+               2 - checks the chance of a bullet from a burst hitting the target (for burst attacks)
+               3 - checks the chance when using skills (not listed below)
+               4 - check the chance of using Repair skill
+               5 - check the chance of using Doctor skill
+               6 - check the chance of using Steal skill for the thief (usually the player)
+               7 - the second Steal skill chance check for the target to catch the thief, in which the target's failure is the thief's success result
+int     arg1 - the value of roll result (see ROLL_* constants), which is calculated as:
+               for ROLL_CRITICAL_SUCCESS: random(1, 100) <= (random_chance / 10) + bonus
+               for ROLL_CRITICAL_FAILURE: random(1, 100) <= -random_chance / 10
+int     arg2 - the chance value
+int     arg3 - the bonus value, used when checking critical success
+int     arg4 - random chance, calculated as: (chance - random(1, 100)), where a negative value is a failure check (ROLL_FAILURE)
+
+int     ret0 - overrides the roll result
+```
+
+-------------------------------------------
+
+#### `HOOK_BESTWEAPON (hs_bestweapon.int)`
+
+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
+```
+
+-------------------------------------------
+
+#### `HOOK_CANUSEWEAPON (hs_canuseweapon.int)`
+
+Run when the AI checks whether it can use a weapon, or when the game checks whether the player can use an item (weapon) in hand slot.\
+For AI, this mostly happens when NPCs try to find weapons in their inventory or on the map.\
+For the player, this happens when the game updates the item data for active item slots on the interface bar.
+
+```
+Critter arg0 - the critter doing the check
+Item    arg1 - the item being checked
+int     arg2 - attack type (see ATKTYPE_* constants), or -1 for dude_obj
+int     arg3 - original result of engine function: 1 - can use, 0 - cannot use
+
+int     ret0 - overrides the result of engine function. Any non-zero value allows using the weapon
+```