Merge branch 'scriptable-burst' into develop

artifacts/scripting/functions.yml

@@ -703,7 +703,7 @@
   items:
   - name: metarule2_explosions
     detail: int metarule2_explosions(int arg1, int arg2)
-    doc: Was made as a dirty easy hack to allow dynamically change some explosion parameters (ranged attack). All changed parameters are reset to vanilla state automatically after each attack action.
+    doc: Was made as a dirty easy hack to allow to dynamically change some explosion parameters (ranged attack). All changed parameters are automatically reset to vanilla state after each attack action.
     opcode: 0x8261
 
   - name: set_attack_explosion_pattern
@@ -1556,6 +1556,16 @@
     opcode: 0x8192
     doc: Should only be used during the target critters turn while in combat.
 
+  - name: set_spray_settings
+    detail: void set_spray_settings(int centerMult, int centerDiv, int targetMult, int targetDiv)
+    doc: |
+      Allows to dynamically change the multipilers and divisors for the bullet distribution of burst attacks. All settings are automatically reset to default values (**ComputeSpray_\*** settings in ddraw.ini) after each attack action
+      - Should be called before the calculation of the bullet distribution (e.g. in `HOOK_TOHIT` or `HOOK_AMMOCOST` with **CheckWeaponAmmoCost=1** in ddraw.ini)
+      - `centerDiv/targetDiv`: the minimum value of divisor is 1
+      - `centerMult/targetMult`: multiplier values are capped at divisor values
+      - __NOTE:__ refer to the description of **ComputeSpray_\*** settings in ddraw.ini for details of the bullet distribution of burst attacks
+    macro: sfall.h
+
 - name: Car
   items:
   - name: set_car_current_town

artifacts/scripting/headers/sfall.h

@@ -373,6 +373,7 @@
 #define set_rest_heal_time(time)                                sfall_func1("set_rest_heal_time", time)
 #define set_rest_mode(mode)                                     sfall_func1("set_rest_mode", mode)
 #define set_scr_name(name)                                      sfall_func1("set_scr_name", name)
+#define set_spray_settings(ctrMult, ctrDiv, tgtMult, tgtDiv)    sfall_func4("set_spray_settings", ctrMult, ctrDiv, tgtMult, tgtDiv)
 #define set_terrain_name(x, y, name)                            sfall_func3("set_terrain_name", x, y, name)
 #define set_town_title(areaID, title)                           sfall_func2("set_town_title", areaID, title)
 #define set_unique_id(obj)                                      sfall_func1("set_unique_id", obj)

artifacts/scripting/sfall function notes.md

@@ -261,7 +261,7 @@ FUNCTION REFERENCE
 
 -----
 ##### `int/array metarule2_explosions(int arg1, int arg2, int arg3)`
-- Was made as a dirty easy hack to allow dynamically change some explosion parameters (ranged attack). All changed parameters are reset to vanilla state automatically after each attack action. Following macros are available in **sfall.h**:
+- Was made as a dirty easy hack to allow to dynamically change some explosion parameters (ranged attack). All changed parameters are automatically reset to vanilla state after each attack action. Following macros are available in **sfall.h**:
 
 -----
 ##### `void set_attack_explosion_pattern(x, y)`
@@ -569,7 +569,7 @@ sfall_funcX metarule functions
 #### set_dude_obj
 `object sfall_func1("set_dude_obj", critter)`
 - Take control of a given critter
-- passing 0 will reset control back to "real" dude
+- Passing 0 will reset control back to "real" dude
 
 ----
 #### real_dude_obj
@@ -1063,6 +1063,16 @@ sfall_funcX metarule functions
 `bool sfall_func1("obj_is_openable", object obj)`
 - Returns True if the object is openable (i.e. has an opening/closing animation), False otherwise
 
+----
+##### set_spray_settings
+`void sfall_func4("set_spray_settings", int centerMult, int centerDiv, int targetMult, int targetDiv)`
+
+- Allows to dynamically change the multipilers and divisors for the bullet distribution of burst attacks. All settings are automatically reset to default values (**ComputeSpray_\*** settings in ddraw.ini) after each attack action
+- Should be called before the calculation of the bullet distribution (e.g. in `HOOK_TOHIT` or `HOOK_AMMOCOST` with **CheckWeaponAmmoCost=1** in ddraw.ini)
+- `centerDiv/targetDiv`: the minimum value of divisor is 1
+- `centerMult/targetMult`: multiplier values are capped at divisor values
+- __NOTE:__ refer to the description of **ComputeSpray_\*** settings in ddraw.ini for details of the bullet distribution of burst attacks
+
 
 ****
 _See other documentation files (arrays.md, hookscripts.md) for related functions reference._