From 143ec750cf4e0ec355d514c12dd757bacd3539be Mon Sep 17 00:00:00 2001 From: NovaRain Date: Mon, 16 Oct 2023 11:32:52 +0800 Subject: [PATCH] Updated documents (mainly array functions) --- artifacts/scripting/arrays.md | 26 +++--- artifacts/scripting/functions.yml | 109 ++++++++++++++-------- artifacts/scripting/hookscripts.md | 2 +- artifacts/scripting/sfall opcode list.md | 8 +- artifacts/scripting/sfall opcode list.txt | 6 +- docs/arrays.md | 22 ++--- 6 files changed, 103 insertions(+), 70 deletions(-) diff --git a/artifacts/scripting/arrays.md b/artifacts/scripting/arrays.md index 7f8fc690e..c098e90fb 100644 --- a/artifacts/scripting/arrays.md +++ b/artifacts/scripting/arrays.md @@ -193,7 +193,7 @@ _*mixed means any type_ #### `void resize_array(int arrayID, int size)` - changes array size - applicable to maps too, but only to reduce elements -- there are number of special negative values of "size" which perform various operations on the array, use macros `sort_array`, `sort_array_reverse`, `reverse_array`, `shuffle_array` from **sfall.h** header +- there are number of special negative values of "size" which perform various operations on the array, see macros `sort_array`, `sort_array_reverse`, `reverse_array`, `shuffle_array`, `sort_map_value`, and `sort_map_reverse` from **sfall.h** header #### `void free_array(int arrayID)` - deletes any array @@ -206,18 +206,7 @@ _*mixed means any type_ #### `int len_array(int arrayID)` - returns number of elements or key=>value pairs in a given array -- if array is not found, returns -1 (can be used to check if given array exist) - -#### `mixed array_key(int arrayID, int index)` -- don't use it directly; it is generated by the compiler in foreach loops -- for lists, returns index back (no change) -- for maps, returns a key at the specified numeric index (don't rely on the order in which keys are stored though) -- can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map - -#### `int arrayexpr(mixed key, mixed value)` -- don't use it directly; it is used by compiler to create array expressions -- assigns value to a given key in an array, created by last `create_array` or `temp_array` call -- always returns 0 +- if array is not found, returns -1 (can be used to check if given array exist) #### `void save_array(mixed key, int arrayID)` - makes the array saveable; it will be saved in **sfallgv.sav** file when saving the game @@ -230,6 +219,17 @@ _*mixed means any type_ - loads array from savegame data by the same key provided in `save_array` - returns array ID or zero (0) if none found +#### `mixed array_key(int arrayID, int index)` +- don't use it directly; it is generated by the compiler in foreach loops +- for lists, returns index back (no change) +- for maps, returns a key at the specified numeric index (don't rely on the order in which keys are stored though) +- can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map + +#### `int arrayexpr(mixed key, mixed value)` +- don't use it directly; it is used by compiler to create array expressions +- assigns value to a given key in an array, created by last `create_array` or `temp_array` call +- always returns 0 + ___ ### BACKWARD COMPATIBILITY NOTES diff --git a/artifacts/scripting/functions.yml b/artifacts/scripting/functions.yml index d6ac7fa78..e24955cd3 100644 --- a/artifacts/scripting/functions.yml +++ b/artifacts/scripting/functions.yml @@ -227,7 +227,7 @@ - name: set_shader_mode detail: void set_shader_mode(int mode) opcode: 0x81ae - doc: Tells sfall when to use a shader. The parameter is a set of 32 flags which specify the screens on which the shader will be disabled, unless bit 32 is set, in which case the shader will only be active on those screens. Remember that screens are displayed on top of each other; if the player opens the character menu which in combat, the game still considers the player to be in combat. See `sfall.h` for a list of defines. + doc: Tells sfall when to use a shader. The parameter is a set of 32 flags which specify the screens on which the shader will be disabled, unless bit 32 is set, in which case the shader will only be active on those screens. Remember that screens are displayed on top of each other; if the player opens the character menu which in combat, the game still considers the player to be in combat. See **sfall.h** for a list of defines. - name: force_graphics_refresh detail: void force_graphics_refresh(bool enabled) opcode: 0x81b0 @@ -478,7 +478,7 @@ detail: void force_encounter_with_flags(int map, int flags) opcode: 0x8229 doc: | - Does the same thing as force_encounter, but allows the specification of some extra options (see `sfall.h` for available flags). + Does the same thing as force_encounter, but allows the specification of some extra options (see **sfall.h** for available flags). Forcing a random encounter on a map that is not normally used for random encounters may cause the player to lose the car, if they have it. In this case use `force_encounter_with_flags` with the `ENCOUNTER_FLAG_NO_CAR` flag set. - name: set_map_time_multi detail: void set_map_time_multi(float multi) @@ -682,7 +682,7 @@ - name: Lists parent: Arrays - doc: The `list_xxx` functions can be used to loop over all items on a map. `list_begin` takes an argument telling sfall what you want to list. (Defined in `sfall.h`) It returns a list pointer, which you iterate through with `list_next`. Finally, when you've finished with the list use `list_end` on it. Not calling `list_end` will result in a memory leak. Alternatively, use `list_as_array` to get the whole list at once as a temp array variable, which can be looped over using `len_array` and which you don't need to remember to free afterwards. + doc: The `list_xxx` functions can be used to loop over all items on a map. `list_begin` takes an argument telling sfall what you want to list (defined in **sfall.h**). It returns a list pointer, which you iterate through with `list_next`. Finally, when you've finished with the list use `list_end` on it. Not calling `list_end` will result in a memory leak. Alternatively, use `list_as_array` to get the whole list at once as a temp array variable, which can be looped over using `len_array` and which you don't need to remember to free afterwards. items: - name: list_begin detail: int list_begin(int type) @@ -867,7 +867,7 @@ - name: obj_blocking_line detail: ObjectPtr obj_blocking_line(ObjectPtr objFrom, int tileTo, int blockingType) - doc: Returns first object which blocks direct linear path from `objFrom` to `tileTo` using selected blocking function (see `BLOCKING_TYPE_*` constants in `sfall.h`). If path is clear (no blocker was encountered by selected function) - returns 0. `objFrom` is always excluded from calculations, but is required to be a valid object. + doc: Returns first object which blocks direct linear path from `objFrom` to `tileTo` using selected blocking function (see `BLOCKING_TYPE_*` constants in **sfall.h**). If path is clear (no blocker was encountered by selected function) - returns 0. `objFrom` is always excluded from calculations, but is required to be a valid object. opcode: 0x826e - name: path_find_to detail: array path_find_to(ObjectPtr objFrom, int tileTo, int blockingType) @@ -1032,7 +1032,7 @@ - name: message_str_game detail: string message_str_game(int fileId, int messageId) doc: | - Works exactly the same as message_str, except you get messages from files in `text/english/game` folder. Use `GAME_MSG_*` defines or `mstr_*` macros from `sfall.h` to use specific msg file + Works exactly the same as message_str, except you get messages from files in `text/english/game` folder. Use `GAME_MSG_*` defines or `mstr_*` macros from **sfall.h** to use specific msg file - Additional game msg files added by `ExtraGameMsgFileList` setting will have consecutive fileIds assigned beginning from 0x2000 to 0x2FFF. (e.g. if you set `ExtraGameMsgFileList=foo,bar` in `ddraw.ini`, `foo.msg` will be associated with 0x2000 and `bar.msg` with 0x2001.). - If a file has a specific number assigned in `ExtraGameMsgFileList`, its fileId will be (0x2000 + assigned number). (e.g. with `ExtraGameMsgFileList=foo,bar:2,foobar` in `ddraw.ini`, `bar.msg` will be associated with 0x2002 and `foobar.msg` with 0x2003.) opcode: 0x826b @@ -1052,7 +1052,7 @@ doc: | unequips an item from the specified slot for a critter or the player can take off player's equipped item when the inventory is opened, or the player is in the barter screen - slot: 0 - armor slot, 1 - right slot, 2 - left slot (see `INVEN_TYPE_*` in `define.h`) + slot: 0 - armor slot, 1 - right slot, 2 - left slot (see `INVEN_TYPE_*` in **define.h**) - name: add_trait @@ -1209,7 +1209,7 @@ doc: Gets the value of hook argument with the specified argument number (first argument of hook starts from 0) macro: sfall.h - name: set_sfall_return - detail: void set_sfall_return(int value) + detail: void set_sfall_return(any value) doc: Used to return the new values from the script. Each time it's called it sets the next value, or if you've already set all return values it does nothing. opcode: 0x81e5 - name: set_sfall_arg @@ -1250,7 +1250,7 @@ So if you combine both mods together, they will run in chain and the end result will be a 75% from original hit chance (hook register order doesn't matter in this case, if you use `set_sfall_arg` in both hooks). - The defines to use for the `hookID` are in `sfall.h`. + The defines to use for the `hookID` are in **sfall.h**. opcode: 0x8262 - name: register_hook_proc_spec detail: void register_hook_proc_spec(int hookID, procedure proc) @@ -1266,11 +1266,16 @@ items: - name: create_array detail: int create_array(int size, int nothing) - doc: Creates permanent array (but not "saved"). + doc: | + Creates permanent array (but not "saved"). + - 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. + - returns array ID (valid until array is deleted). opcode: 0x822d - name: temp_array detail: int temp_array(int size, int nothing) - doc: Works exactly like "create_array", only created array becomes "temporary." + doc: Works exactly like `create_array`, only created array becomes "temporary". opcode: 0x8233 - name: fix_array detail: void fix_array(int arrayID) @@ -1278,46 +1283,74 @@ opcode: 0x8234 - name: set_array detail: void set_array(int arrayID, mixed key, mixed value) - doc: 'Sets array value (shorthand: arrayID[key] := value).' + doc: | + Sets array value (shorthand: `arrayID[key] := value`). + - 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 opcode: 0x822e - name: get_array detail: mixed get_array(int arrayID, mixed key) doc: | - Returns array value by key or index (shorthand: arrayID[key]). - - If array with given arrayID doesn't exist, returns 0. + Returns array value by key or index (shorthand: `arrayID[key]`). + - if key doesn't exist or index is not in valid range, returns 0. opcode: 0x822f - name: resize_array detail: void resize_array(int arrayID, int size) doc: Changes array size. + - applicable to maps too, but only to reduce elements. + - there are number of special negative values of "size" which perform various operations on the array, use macros `sort_array`, `sort_array_reverse`, `reverse_array`, `shuffle_array` from **sfall.h** header. opcode: 0x8232 - name: free_array detail: void free_array(int arrayID) - doc: Deletes any array. + doc: | + Deletes any array. + - if array was "saved", it will be removed from a savegame. opcode: 0x8230 - name: scan_array detail: mixed scan_array(int arrayID, mixed value) - doc: Searches for a first occurence of given value inside given array. + doc: | + Searches for a first occurence of given value inside given array. + - if value is found, returns its index (for lists) or key (for maps). + - if value is not found, returns -1 (be careful, as -1 can be a valid key for a map). opcode: 0x8239 - name: len_array detail: int len_array(int arrayID) - doc: Returns number of elements or key=>value pairs in a given array. + doc: | + Returns number of elements or key=>value pairs in a given array. + - if array is not found, returns -1 (can be used to check if given array exist). opcode: 0x8231 - - name: array_key - detail: mixed array_key(int arrayID, int index) - doc: Don't use it directly; it is generated by the compiler in foreach loops. - opcode: 0x8256 - - name: arrayexpr - detail: int arrayexpr(mixed key, mixed value) - doc: Don't use it directly; it is used by compiler to create array expressions. - opcode: 0x8257 - name: save_array detail: void save_array(mixed key, int arrayID) - doc: Array is saved (arrayID is associated with given "key"). + doc: | + Makes the array saveable; it will be saved in **sfallgv.sav** file when saving the game. + - array ID 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". opcode: 0x8254 - name: load_array detail: int load_array(mixed key) - doc: Load array from savegame data by the same key provided in "save_array". + doc: | + Loads array from savegame data by the same key provided in `save_array`. + - returns array ID or zero (0) if none found. opcode: 0x8255 + - name: array_key + detail: mixed array_key(int arrayID, int index) + doc: | + Don't use it directly; it is generated by the compiler in foreach loops. + - for lists, returns index back (no change). + - for maps, returns a key at the specified numeric index (don't rely on the order in which keys are stored though). + - can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map. + opcode: 0x8256 + - name: arrayexpr + detail: int arrayexpr(mixed key, mixed value) + doc: | + Don't use it directly; it is used by compiler to create array expressions. + - assigns value to a given key in an array, created by last `create_array` or `temp_array` call. + - always returns 0. + opcode: 0x8257 - name: Sfall # just parent page @@ -1382,7 +1415,7 @@ macro: sfall.h - name: set_rest_mode detail: void set_rest_mode(int flags) - doc: 'Sets the bit flags for the rest mode (see `RESTMODE_*` constants in `sfall.h`). Passing 0 will reset the rest mode. It will also be reset each time the player reloads the game.' + doc: 'Sets the bit flags for the rest mode (see `RESTMODE_*` constants in **sfall.h**). Passing 0 will reset the rest mode. It will also be reset each time the player reloads the game.' macro: sfall.h - name: get_metarule_table @@ -1402,7 +1435,7 @@ - name: get_object_ai_data detail: int get_object_ai_data(ObjectPtr object, int aiParam) - doc: Returns the setting value from the AI packet of an object (critter). Use `AI_CAP_*` constants from `define_extra.h` for the `aiParam` argument to get AI value. + doc: Returns the setting value from the AI packet of an object (critter). Use `AI_CAP_*` constants from **define_extra.h** for the `aiParam` argument to get AI value. macro: sfall.h - name: npc_engine_level_up @@ -1481,7 +1514,7 @@ - name: objects_in_radius detail: objects_in_radius", int tile, int radius, int elevation, int type) doc: | - - returns an array of objects of a type (see `OBJ_TYPE_*` constants in `define_extra.h`) within the specified radius from the given tile + - returns an array of objects of a type (see `OBJ_TYPE_*` constants in **define_extra.h**) within the specified radius from the given tile - passing -1 to the `type` argument or _not specifying it_ will return all objects within the radius - the radius is limited to 50 hexes macro: sfall.h @@ -1551,7 +1584,7 @@ - name: combat_data detail: mixed combat_data doc: | - - returns a pointer to the `C_ATTACK_*` data for the current combat attack process (see defined constants in `define_extra.h`) + - returns a pointer to the `C_ATTACK_*` data for the current combat attack process (see defined constants in **define_extra.h**) - can be used in conjunction with the `get_object_data` and `set_object_data` functions example: `sfall_func3("set_object_data", sfall_func0("combat_data"), C_ATTACK_UNUSED, 255);` - name: set_bodypart_hit_modifier @@ -1649,7 +1682,7 @@ int sfall_func6("interface_art_draw", int winType, string artFile/int artID, int x, int y, int frame, array param) ``` - draws the specified PCX or FRM image in the game interface window, returns -1 on any error - - `winType`: the type number of the interface window (see `WINTYPE_*` constants in `sfall.h`) + - `winType`: the type number of the interface window (see `WINTYPE_*` constants in **sfall.h**) this also takes the value of the flag (0x1000000) to prevent immediate redrawing of the interface window - `artFile/artId`: path to the PCX/FRM file (e.g. `art\\inven\\5mmap.frm`), or its FRM ID number (e.g. `0x7000026`, see specification of the FID format) - `x/y`: offset relative to the top-left corner of the window @@ -1717,7 +1750,7 @@ doc: | Alternative form: `int sfall_func2("get_window_attribute", int winType, int attrType)` Returns the attribute of the specified interface window by the `attrType` argument. - - `winType`: the type number of the interface window (see `WINTYPE_*` constants in `sfall.h`) + - `winType`: the type number of the interface window (see `WINTYPE_*` constants in **sfall.h**) - `attrType`: `0` - checks and returns a value of 1 if the specified interface window is created by the game (same as without the argument) `1` - X position, `2` - Y position (relative to the top-left corner of the game screen) `3` - interface width size, `4` - interface height size @@ -1740,7 +1773,7 @@ Changes the specified flag for the created script or game interface window. - winName: the window name, assigned to the window by the `CreateWin/create_win` function - winID: the ID number of the interface or script window obtained with the `get_window_under_mouse` function, or 0 for the current game interface - - flag: the flag to change (see `WIN_FLAG_*` constants in `define_extra.h`) + - flag: the flag to change (see `WIN_FLAG_*` constants in **define_extra.h**) - value: `True` - set the flag, `False` - unset the flag macro: sfall.h @@ -1755,7 +1788,7 @@ Alternative form: `int sfall_func6("interface_overlay", int winType, 2, int x, int y, int width, int height)`. Creates an additional drawing surface above the graphic layer of the specified interface window. All subsequent calls of `interface_art_draw` and `interface_print` functions will draw on it. - - `winType`: the type number of the interface window (see `WINTYPE_*` constants in `sfall.h`) + - `winType`: the type number of the interface window (see `WINTYPE_*` constants in **sfall.h**) - `mode`: 1 - creates a new overlay surface 2 - clears the overlay area or the specified rectangle defined by the `x`, `y`, `width`, `height` arguments 0 - destroys the created overlay surface (frees up the memory allocated to the surface) @@ -1774,7 +1807,7 @@ - name: set_outline detail: void set_outline(ObjectPtr obj, int color) doc: | - - sets the outline color of an object (see `OUTLINE_*` constants in `sfall.h`) + - sets the outline color of an object (see `OUTLINE_*` constants in **sfall.h**) - can also set a custom color from the game palette by shifting the color index value left by 8 bits: `0xCC00` where `CC` is the palette index (available since sfall 4.2.7/3.8.27) - passing 0 will disable the outline macro: sfall.h @@ -1792,7 +1825,7 @@ doc: | Redraws main game interface. Useful after direct changes to current player weapons or stats to reflect changes. - redraws main game interface, useful to reflect changes after directly changing current player weapons or stats - - `winType`: the type number of the interface window (see `WINTYPE_*` constants in `sfall.h`). Pass `-1` to redraw all interface windows. + - `winType`: the type number of the interface window (see `WINTYPE_*` constants in **sfall.h**). Pass `-1` to redraw all interface windows. - name: intface_hide detail: void intface_hide() doc: Hides main interface. @@ -1968,7 +2001,7 @@ - name: get_object_data detail: get_object_data(ObjectPtr object, int offset) - doc: Returns the data at the specified offset of an object (see `OBJ_DATA_*` constants in `define_extra.h` for offsets). + doc: Returns the data at the specified offset of an object (see `OBJ_DATA_*` constants in **define_extra.h** for offsets). macro: sfall.h - name: set_object_data detail: set_object_data(ObjectPtr object, int offset, int data) @@ -1977,7 +2010,7 @@ - name: get_flags detail: int get_flags(ObjectPtr obj) - doc: Gets the current value of object flags (see `define_extra.h` for available flags). + doc: Gets the current value of object flags (see **define_extra.h** for available flags). macro: sfall.h - name: set_flags detail: void set_flags(ObjectPtr obj, int flags) diff --git a/artifacts/scripting/hookscripts.md b/artifacts/scripting/hookscripts.md index 870967337..0c682bfcd 100644 --- a/artifacts/scripting/hookscripts.md +++ b/artifacts/scripting/hookscripts.md @@ -38,7 +38,7 @@ You can arbitrarily get the value of any argument using the `sfall_func1("get_sf #### `array get_sfall_args()` Returns all hook arguments as a new temp array. -#### `void set_sfall_return(int value)` +#### `void set_sfall_return(any value)` Used to return the new values from the script. Each time it's called it sets the next value, or if you've already set all return values it does nothing. #### `void set_sfall_arg(int argNum, int value)` diff --git a/artifacts/scripting/sfall opcode list.md b/artifacts/scripting/sfall opcode list.md index 2a0588072..4e549c3e7 100644 --- a/artifacts/scripting/sfall opcode list.md +++ b/artifacts/scripting/sfall opcode list.md @@ -143,10 +143,10 @@ _^ - These functions require AllowUnsafeScripting to be enabled in ddraw.ini_ 0x8233 - `int temp_array(int element_count, int flags)`\ 0x8234 - `void fix_array(int array)`\ 0x8239 - `int scan_array(int array, int/float var)`\ -0x8256 - `int array_key(int array, int index)`\ -0x8257 - `int arrayexpr(any key, any value)`\ 0x8254 - `void save_array(any key, int array)`\ -0x8255 - `int load_array(any key)` +0x8255 - `int load_array(any key)`\ +0x8256 - `int array_key(int array, int index)`\ +0x8257 - `int arrayexpr(any key, any value)` 0x81a0 - `void set_pickpocket_max(int percentage)`\ 0x81a1 - `void set_hit_chance_max(int percentage)`\ @@ -212,7 +212,7 @@ _^ - These functions require AllowUnsafeScripting to be enabled in ddraw.ini_ 0x81e4 - `int get_sfall_arg()`\ 0x823c - `array get_sfall_args()`\ 0x823d - `void set_sfall_arg(int argnum, int value)`\ -0x81e5 - `void set_sfall_return(int value)`\ +0x81e5 - `void set_sfall_return(any value)`\ 0x81ea - `int init_hook()` 0x81e6 - `void set_unspent_ap_bonus(int multiplier)`\ diff --git a/artifacts/scripting/sfall opcode list.txt b/artifacts/scripting/sfall opcode list.txt index 11e93ce5e..9c392d885 100644 --- a/artifacts/scripting/sfall opcode list.txt +++ b/artifacts/scripting/sfall opcode list.txt @@ -143,10 +143,10 @@ 0x8233 - int temp_array(int element_count, int flags) 0x8234 - void fix_array(int array) 0x8239 - int scan_array(int array, int/float var) -0x8256 - int array_key(int array, int index) -0x8257 - int arrayexpr(any key, any value) 0x8254 - void save_array(any key, int array) 0x8255 - int load_array(any key) +0x8256 - int array_key(int array, int index) +0x8257 - int arrayexpr(any key, any value) 0x81a0 - void set_pickpocket_max(int percentage) 0x81a1 - void set_hit_chance_max(int percentage) @@ -212,7 +212,7 @@ 0x81e4 - int get_sfall_arg() 0x823c - array get_sfall_args() 0x823d - void set_sfall_arg(int argnum, int value) -0x81e5 - void set_sfall_return(int value) +0x81e5 - void set_sfall_return(any value) 0x81ea - int init_hook() 0x81e6 - void set_unspent_ap_bonus(int multiplier) diff --git a/docs/arrays.md b/docs/arrays.md index e670482e3..da145561f 100644 --- a/docs/arrays.md +++ b/docs/arrays.md @@ -212,17 +212,6 @@ _*mixed means any type_ - returns number of elements or key=>value pairs in a given array - if array is not found, returns -1 (can be used to check if given array exist) -* `mixed array_key(int arrayID, int index)`: - - don't use it directly; it is generated by the compiler in foreach loops - - for lists, returns index back (no change) - - for maps, returns a key at the specified numeric index (don't rely on the order in which keys are stored though) - - can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map - -* `int arrayexpr(mixed key, mixed value)`: - - don't use it directly; it is used by compiler to create array expressions - - assigns value to a given key in an array, created by last `create_array` or `temp_array` call - - 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" @@ -234,6 +223,17 @@ _*mixed means any type_ - loads array from savegame data by the same key provided in `save_array` - returns array ID or zero (0) if none found +* `mixed array_key(int arrayID, int index)`: + - don't use it directly; it is generated by the compiler in foreach loops + - for lists, returns index back (no change) + - for maps, returns a key at the specified numeric index (don't rely on the order in which keys are stored though) + - can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map + +* `int arrayexpr(mixed key, mixed value)`: + - don't use it directly; it is used by compiler to create array expressions + - assigns value to a given key in an array, created by last `create_array` or `temp_array` call + - always returns 0 + ## Backward compatibility notes For those who used arrays in their mods before sfall 3.4: