Added new HOOK_BUILDSFXWEAPON (#560)

* Hook for gsnd_build_weapon_sfx_name
* Fixed long name ACM crash in AutoSearchSFX
* Updated documents

artifacts/scripting/headers/sfall.h

@@ -76,6 +76,8 @@
 #define HOOK_ROLLCHECK        (46)
 #define HOOK_BESTWEAPON       (47)
 #define HOOK_CANUSEWEAPON     (48)
+// RESERVED 49..60
+#define HOOK_BUILDSFXWEAPON   (61)
 
 // Valid arguments to list_begin
 #define LIST_CRITTERS    (0)

artifacts/scripting/hooks.yml

@@ -818,4 +818,18 @@
     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
+
+
+- name: BuildSfxWeapon
+  id: HOOK_BUILDSFXWEAPON
+  doc: |
+    Runs before each weapon sound effect is played or put in the animation queue to determine the name of sound effect file based on the weapon, target and action being performed.
+
+    ```
+    int     arg0 - weapon sound effect type: 0 - ready/reload, 1 - attack, 2 - out of ammo, 3 - flying (for projectile weapons), 4 - hit
+    Item    arg1 - the weapon being used
+    int     arg2 - attack type (see ATKTYPE_* constants)
+    Obj     arg3 - target of the attack (can be 0)
+
+    String  ret0 - the new sound file name to use, without extension (relative to "sound\sfx" path)
     ```

artifacts/scripting/hookscripts.md

@@ -936,3 +936,18 @@ 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
 ```
+
+-------------------------------------------
+
+#### `HOOK_BUILDSFXWEAPON (hs_buildsfxweapon.int)`
+
+Runs before each weapon sound effect is played or put in the animation queue to determine the name of sound effect file based on the weapon, target and action being performed.
+
+```
+int     arg0 - weapon sound effect type: 0 - ready/reload, 1 - attack, 2 - out of ammo, 3 - flying (for projectile weapons), 4 - hit
+Item    arg1 - the weapon being used
+int     arg2 - attack type (see ATKTYPE_* constants)
+Obj     arg3 - target of the attack (can be 0)
+
+String  ret0 - the new sound file name to use, without extension (relative to "sound\sfx" path)
+```