Added a new hook: HOOK_BESTWEAPON

artifacts/scripting/headers/sfall.h

@@ -72,6 +72,7 @@
 #define HOOK_ADJUSTPOISON     (44)
 #define HOOK_ADJUSTRADS       (45)
 #define HOOK_ROLLCHECK        (46)
+#define HOOK_BESTWEAPON       (47)
 
 //Valid arguments to list_begin
 #define LIST_CRITTERS    (0)

artifacts/scripting/hookscripts.txt

@@ -317,7 +317,7 @@ 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
 
 -------------------------------------------
 
@@ -748,3 +748,18 @@ 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 game (AI) decides which weapon is the best while searching the inventory for a weapon to equip in combat.
+This is 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