From 7c0adc558aea276639c299c64c8fdb56a535377a Mon Sep 17 00:00:00 2001 From: NovaRain Date: Wed, 12 Jan 2022 09:40:18 +0800 Subject: [PATCH] Updated documents for the removal of ArraysBehavior option Some other minor edits to documents. --- artifacts/ddraw.ini | 4 ++-- artifacts/scripting/arrays.md | 8 ++++---- artifacts/scripting/compiler/sslc_readme.md | 10 +++++----- artifacts/scripting/compiler/sslc_readme.txt | 10 +++++----- artifacts/scripting/functions.yml | 20 ++++++++++---------- artifacts/scripting/hooks.yml | 2 +- artifacts/scripting/hookscripts.md | 2 +- artifacts/scripting/sfall function notes.md | 6 +++--- docs/arrays.md | 9 +++------ docs/sslc.md | 4 ++-- 10 files changed, 36 insertions(+), 39 deletions(-) diff --git a/artifacts/ddraw.ini b/artifacts/ddraw.ini index 580d280e..f6e04a2c 100644 --- a/artifacts/ddraw.ini +++ b/artifacts/ddraw.ini @@ -17,7 +17,7 @@ UseCommandLine=0 [ExtraPatches] ;This section allows you to set multiple paths to folders containing mods or patches that will be loaded by the game ;If DataLoadOrderPatch is enabled, the data load order is: -;master_patches > critter_patches > PatchFile99..PatchFile0 > patchXXX.dat > critter_dat > f2_res_patches > f2_res_dat > master_dat +;master_patches > critter_patches > [extra patches] > patchXXX.dat > sfall.dat > critter_dat > f2_res_patches > f2_res_dat > master_dat ;Paths to folders and Fallout .dat files are supported ;The PatchFile## options are available from 0 to 99. Larger numbers take precedence over smaller numbers (same as patchXXX.dat) ;PatchFile0=mods\RP_data @@ -111,7 +111,7 @@ ActionPointsBar=0 ;Set to 2 to skip correcting the position of entrance markers on town maps ;You can use resized FRMs in 700x682 for town maps in the expanded world map interface ;Requires High Resolution Patch v4.1.8 and a new WORLDMAP.frm file in art\intrface\ (included in sfall.dat) -;The resolution of hi-res patch must be set to at least 890x720 +;The resolution of the hi-res patch must be set to at least 890x720 ExpandWorldMap=0 ;Set to 1 to draw a dotted line while traveling on the world map (similar to Fallout 1) diff --git a/artifacts/scripting/arrays.md b/artifacts/scripting/arrays.md index d8bc4178..0727c6e6 100644 --- a/artifacts/scripting/arrays.md +++ b/artifacts/scripting/arrays.md @@ -45,7 +45,7 @@ Both array types have their pros and cons and are suited for different tasks. ___ ### ARRAYS SYNTAX -Basically arrays are implemented using number of new operators (scripting functions). But for ease of use, there are some new syntax elements: +Basically arrays are implemented using number of new operators (script functions). But for ease of use, there are some new syntax elements: * Accessing elements. Use square brackets: ```js @@ -94,7 +94,7 @@ There a 3 types of arrays: Arrays of this type are auto-deleted at the end of the frame. So, for example, if you have a global script which runs at regular intervals, where you create a temporary array, it will not be available next time your global script is executed. * **Permanent**. They are created using `create_array` function or `fix_array` (from pre-existing temporary array). -This type of arrays are always available (by their ID) until you start a new game or load a saved game (at which point they are deleted). +This type of arrays are always available (by their IDs) until you start a new game or load a saved game (at which point they are deleted). * **Saved**. If you want your array to really stay for a while, use function `save_array` to make any array "saved". However, they are, like permanent arrays, "deleted" from memory when loading game. In order to use them properly, you must load them from the savegame using `load_array` whenever you want to use them. @@ -236,9 +236,9 @@ ___ For those who used arrays in their mods before sfall 3.4: -* There is an INI parameter **arraysBehavior** in **Misc** section of ddraw.ini. If set to 0, all scripts which used sfall arrays before should work. This basically changes that `create_array` will create permanent arrays which are "saved" by default and their ID is also permanent. It is 1 by default. +* Previously `create_array` would create permanent arrays which were "saved" by default and their IDs were also permanent. Now permanent arrays from `create_array` are not "saved" by default anymore. Make sure to review your scripts if you need to save arrays into savegames. * How savegame compatibility is handled?\ - Saved arrays are stored in **sfallgv.sav** file (in savegame) in new (more flexible) format, just after the old arrays. So basically, when you load older savegame, sfall will load arrays from old format and save them to new format on next game save. If you load savegame made with sfall 3.4 using sfall 3.3 (for example), game shouldn't crash, but all arrays will be lost. + Saved arrays are stored in **sfallgv.sav** file (in savegame) in new (more flexible) format, just after the old arrays. So basically, when you load older savegame, sfall will load arrays from old format and save them to new format on next game save. If you load savegame made with sfall 3.4 using sfall 3.3 (for example), the game shouldn't crash, but all arrays will be lost. * Previously you had to specify size in bytes for array elements. This parameter is now ignored and you can store strings of arbitrary length in arrays. diff --git a/artifacts/scripting/compiler/sslc_readme.md b/artifacts/scripting/compiler/sslc_readme.md index eb7cb0e9..5a81e1bf 100644 --- a/artifacts/scripting/compiler/sslc_readme.md +++ b/artifacts/scripting/compiler/sslc_readme.md @@ -1,7 +1,7 @@ SSLC ---- -This is a modified copy of sslc, that has a few bugfixes from the original, that will recognise and compile the additional scripting functions provided by sfall, that can also understand some additional syntax, and that has an integrated preprocessor and optimizer. +This is a modified copy of sslc, that has a few bugfixes from the original, that will recognise and compile the additional script functions provided by sfall, that can also understand some additional syntax, and that has an integrated preprocessor and optimizer. Unlike the original script compiler, this has not been compiled as a dos program. When using this in place of the original compile.exe but still using p.bat, you need to either get rid of the dos4gw.exe reference from p.bat or replace the original dos4gw.exe with the one in this archive. @@ -9,7 +9,7 @@ If you use Fallout Script Editor, you can extract `compile.exe` and `dos4gw.exe` When compiling global or hook scripts for sfall 3.4 or below, you _must_ include the line `procedure start;` before any `#include` files that define procedures to avoid a few weird problems. (this is no longer required starting from 3.5) -This version of compiler was designed primarily for new sfall functions, but it can safely (and is recommended) to be used with non-sfall scripts as well, as long as you don't use any of the arrays syntax and any sfall scripting functions. +This version of compiler was designed primarily for new sfall functions, but it can safely (and is recommended) to be used with non-sfall scripts as well, as long as you don't use any of the arrays syntax and any sfall script functions. The original unmodified sslc source is over here: [http://www.teamx.ru/site_arc/utils/index.html](http://www.teamx.ru/site_arc/utils/index.html) @@ -405,9 +405,9 @@ There are several changes in this version of sslc which may result in problems f - fixed more invalid results in constant folding - implemented optional arguments for user-defined procedures - implemented stringify procedure names using `@` operator, which is helpful to pass procedures around to call them from variables (it will properly handle references) -- logic for procedures passed as arguments to scripting functions was moved from code generation to parsing stage -- now it is possible to call user-defined procedures inside argument list of scripting functions, without compiler attempting to treat them as procedure references and probably fail (procedures will still be passed, but only to appropriate scripting functions at appropriate argument positions) -- **int2ssl** will now place empty parantheses after a call to user-defined procedure - this will distinct calls from passing procedures to some scripting functions (like `giq_option`) +- logic for procedures passed as arguments to script functions was moved from code generation to parsing stage +- now it is possible to call user-defined procedures inside argument list of script functions, without compiler attempting to treat them as procedure references and probably fail (procedures will still be passed, but only to appropriate script functions at appropriate argument positions) +- **int2ssl** will now place empty parantheses after a call to user-defined procedure - this will distinct calls from passing procedures to some script functions (like `giq_option`) - fixed `inline` procedure "calls" not working when optimization is enabled - added column numbers to error/warning output - added code to simplify adding sfall opcodes into compiler (need to add code in 3 places, instead of 7 places for each opcode) diff --git a/artifacts/scripting/compiler/sslc_readme.txt b/artifacts/scripting/compiler/sslc_readme.txt index 7a30d406..a8be9e16 100644 --- a/artifacts/scripting/compiler/sslc_readme.txt +++ b/artifacts/scripting/compiler/sslc_readme.txt @@ -1,4 +1,4 @@ -This is a modified copy of sslc, that has a few bugfixes from the original, that will recognise and compile the additional scripting functions provided by sfall, that can also understand some additional syntax, and that has an integrated preprocessor and optimizer. +This is a modified copy of sslc, that has a few bugfixes from the original, that will recognise and compile the additional script functions provided by sfall, that can also understand some additional syntax, and that has an integrated preprocessor and optimizer. Unlike the original script compiler, this has not been compiled as a dos program. When using this in place of the original compile.exe but still using p.bat, you need to either get rid of the dos4gw.exe reference from p.bat or replace the original dos4gw.exe with the one in this archive. @@ -6,7 +6,7 @@ If you use fallout script editor, you can extract compile.exe and dos4gw.exe to When compiling global or hook scripts for sfall 3.4 or below, you _must_ include the line 'procedure start;' before any #includes that define procedures to avoid a few weird problems. (this is no longer required starting from 3.5) -This version of compiler was designed primarily for new sfall functions, but it can safely (and is recommended) to be used with non-sfall scripts as well, as long as you don't use any of the arrays syntax and any sfall scripting functions. +This version of compiler was designed primarily for new sfall functions, but it can safely (and is recommended) to be used with non-sfall scripts as well, as long as you don't use any of the arrays syntax and any sfall script functions. The original unmodified sslc source is over here: http://www.teamx.ru/eng/files/srcs/index.shtml @@ -385,9 +385,9 @@ There are several changes in this version of sslc which may result in problems f - fixed more invalid results in constant folding - implemented optional arguments for user-defined procedures - implemented stringify procedure names using @ operator, which is helpful to pass procedures around to call them from variables (it will properly handle references) -- logic for procedures passed as arguments to scripting functions was moved from code generation to parsing stage -- now it is possible to call user-defined procedures inside argument list of scripting functions, without compiler attempting to treat them as procedure references and probably fail (procedures will still be passed, but only to appropriate scripting functions at appropriate argument positions) -- int2ssl will now place empty parantheses after a call to user-defined procedure - this will distinct calls from passing procedures to some scripting functions (like giq_option) +- logic for procedures passed as arguments to script functions was moved from code generation to parsing stage +- now it is possible to call user-defined procedures inside argument list of script functions, without compiler attempting to treat them as procedure references and probably fail (procedures will still be passed, but only to appropriate script functions at appropriate argument positions) +- int2ssl will now place empty parantheses after a call to user-defined procedure - this will distinct calls from passing procedures to some script functions (like giq_option) - fixed inline procedure "calls" not working when optimization is enabled - added column numbers to error/warning output - added code to simplify adding sfall opcodes into compiler (need to add code in 3 places, instead of 7 places for each opcode) diff --git a/artifacts/scripting/functions.yml b/artifacts/scripting/functions.yml index f02b8c7a..887c2642 100644 --- a/artifacts/scripting/functions.yml +++ b/artifacts/scripting/functions.yml @@ -1276,39 +1276,39 @@ items: - name: sfall_func0 detail: any sfall_func0(char* funcName) - doc: Calls scripting function with given name and no arguments. + doc: Calls script function with given name and no arguments. opcode: 0x8276 - name: sfall_func1 detail: any sfall_func1(char* funcName, arg1) - doc: Calls scripting function with given name and 1 argument. + doc: Calls script function with given name and 1 argument. opcode: 0x8277 - name: sfall_func2 detail: any sfall_func2(char* funcName, arg1, arg2) - doc: Calls scripting function with given name and 2 arguments. + doc: Calls script function with given name and 2 arguments. opcode: 0x8278 - name: sfall_func3 detail: any sfall_func3(char* funcName, arg1, arg2, arg3) - doc: Calls scripting function with given name and 3 arguments. + doc: Calls script function with given name and 3 arguments. opcode: 0x8279 - name: sfall_func4 detail: any sfall_func4(char* funcName, arg1, arg2, arg3, arg4) - doc: Calls scripting function with given name and 4 arguments. + doc: Calls script function with given name and 4 arguments. opcode: 0x827a - name: sfall_func5 detail: any sfall_func5(char* funcName, arg1, arg2, arg3, arg4, arg5) - doc: Calls scripting function with given name and 5 arguments. + doc: Calls script function with given name and 5 arguments. opcode: 0x827b - name: sfall_func6 detail: any sfall_func6(char* funcName, arg1, arg2, arg3, arg4, arg5, arg6) - doc: Calls scripting function with given name and 6 arguments + doc: Calls script function with given name and 6 arguments opcode: 0x827c - name: sfall_func7 detail: any sfall_func7(string funcName, arg1, arg2, arg3, arg4, arg5, arg6, arg7) - doc: Calls scripting function with given name and 7 arguments + doc: Calls script function with given name and 7 arguments opcode: 0x8280 - name: sfall_func8 detail: any sfall_func8(string funcName, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) - doc: Calls scripting function with given name and 8 arguments + doc: Calls script function with given name and 8 arguments opcode: 0x8281 - name: Sfall funcX macros @@ -1337,7 +1337,7 @@ - name: get_metarule_table detail: array get_metarule_table - doc: Returns names of all currently available scripting functions. + doc: Returns names of all currently available script functions. macro: sfall.h - name: dialog_message diff --git a/artifacts/scripting/hooks.yml b/artifacts/scripting/hooks.yml index e9a4ceda..76eb2616 100644 --- a/artifacts/scripting/hooks.yml +++ b/artifacts/scripting/hooks.yml @@ -396,7 +396,7 @@ int ret0 - overrides the returned result of the function: 0 - not in range (can't see) 1 - in range (will see if not blocked) - 2 - forced detection (will see regardless, only used in obj_can_see_obj scripting function which is called by every critter in the game) + 2 - forced detection (will see regardless, only used in obj_can_see_obj script function which is called by every critter in the game) ``` - name: InventoryMove diff --git a/artifacts/scripting/hookscripts.md b/artifacts/scripting/hookscripts.md index 89325f89..564efb72 100644 --- a/artifacts/scripting/hookscripts.md +++ b/artifacts/scripting/hookscripts.md @@ -496,7 +496,7 @@ int arg3 - Type of hook: int ret0 - overrides the returned result of the function: 0 - not in range (can't see) 1 - in range (will see if not blocked) - 2 - forced detection (will see regardless, only used in obj_can_see_obj scripting function which is called by every critter in the game) + 2 - forced detection (will see regardless, only used in obj_can_see_obj script function which is called by every critter in the game) ``` ------------------------------------------- diff --git a/artifacts/scripting/sfall function notes.md b/artifacts/scripting/sfall function notes.md index 8789e6ec..5d18f26e 100644 --- a/artifacts/scripting/sfall function notes.md +++ b/artifacts/scripting/sfall function notes.md @@ -74,7 +74,7 @@ The `play_sfall_sound` and `stop_sfall_sound` are used to play **mp3/wav/wma** f Starting from sfall 4.2.8/3.8.28, you can pass a value in the **mode** argument for a reduced sound volume. To set the volume, You need to convert the number to hexadecimal and use the argument format `0xZZZZ000Y`, where `ZZZZ` is the volume reduction value in range from 0 to 32767 (the value 32767 is muted), and `Y` is the playback mode. Arrays are created and manipulated with the `xxx_array` functions. An array must first be created with `create_array` or `temp_array`, specifying how many data elements the array can hold. You can store any of ints, floats and strings in an array, and can mix all 3 in a single array. The ID returned by `create_array` or `temp_array` can then be used with the other array functions. Arrays are shared between all scripts. (i.e. you can call `create_array` from one script, and then use the returned ID from another script.) They are also saved across savegames. Arrays created with `temp_array` will be automatically freed at the end of the frame. These functions are safe, in that supplying a bad id or trying to access out of range elements will not crash the script. `create_array` is the only function that returns a permanent array, all other functions which return arrays (`string_split`, `list_as_array`, etc,) all return temp arrays. You can use `fix_array` to make a temp array permanent.\ -__NOTE:__ the above description only applies when **arraysBehavior** is set to 0 in ddraw.ini. Refer to **arrays.md** for detailed description of new arrays behavior. +__NOTE:__ refer to **arrays.md** for detailed description of the array behavior and function usage. The `force_aimed_shots` and `disable_aimed_shots` allow overriding the normal rules regarding which weapons are allowed to make aimed attacks. (e.g. weapons that cause explosive damage normally cannot normally make aimed shots.) `force_aimed_shots` will allow a weapon to make aimed shots even if it normally couldn't, and `disable_aimed_shots` stops a weapon from making aimed shots even if it normally could. Both of these functions affect player and NPCs alike. `force_aimed_shots` does not override the effects of the fast shot trait. The list of edited weapons is not saved over game loads, so you need to call the functions once at each reload. Use a pid of 0 to represent unarmed. @@ -452,7 +452,7 @@ FUNCTION REFERENCE ----- ##### `any sfall_funcX(string funcName, ...)` -- These opcodes allows to use additional scripting functions, that do not require new opcode. +- These opcodes allows to use additional script functions, that do not require new opcode. - First argument is always function name (string). - There are 9 versions of this opcode for different number of additional arguments (for convenience). - Opcodes have return value, but it is not necessary to use it. @@ -464,7 +464,7 @@ sfall_funcX metarule functions #### get_metarule_table `array sfall_func0("get_metarule_table")` -- Returns names of all currently available scripting functions (via `sfall_funcX`) +- Returns names of all currently available script functions (via `sfall_funcX`) ---- #### metarule_exist diff --git a/docs/arrays.md b/docs/arrays.md index e20ea528..4dc6bda2 100644 --- a/docs/arrays.md +++ b/docs/arrays.md @@ -51,7 +51,7 @@ Both array types have their pros and cons and are suited for different tasks. ## Arrays syntax -Basically arrays are implemented using number of new operators (scripting functions). But for ease of use, there are some new syntax elements: +Basically arrays are implemented using number of new operators (script functions). But for ease of use, there are some new syntax elements: * Accessing elements. Use square brackets: ```js @@ -238,12 +238,9 @@ _*mixed means any type_ For those who used arrays in their mods before sfall 3.4: -* There is an INI parameter **arraysBehavior** in **Misc** section of ddraw.ini. If set to 0, all scripts which used sfall arrays before should work. This basically changes that `create_array` will create permanent arrays which are "saved" by default and their ID is also permanent. It is 1 by default. +* Previously `create_array` would create permanent arrays which were "saved" by default and their IDs were also permanent. Now permanent arrays from `create_array` are not "saved" by default anymore. Make sure to review your scripts if you need to save arrays into savegames. -* If `arraysBehaviour=0`: - Arrays are created and manipulated with the `xxx_array` functions. An array must first be created with `create_array` or `temp_array`, specifying how many data elements the array can hold. You can store any of ints, floats and strings in an array, and can mix all 3 in a single array. The id returned by `create/temp_array` can then be used with the other array functions. Arrays are shared between all scripts. (i.e. you can call `create_array` from one script, and then use the returned id from another script.) They are also saved across savegames. Arrays created with `temp_array` will be automatically freed at the end of the frame. These functions are safe, in that supplying a bad id or trying to access out of range elements will not crash the script. `create_array` is the only function that returns a permanent array, all other functions which return arrays (`string_split`, `list_as_array` etc,) all return temp arrays. You can use `fix_array` to make a temp array permanent. - -* How savegame compatibility is handled?
+* How savegame compatibility is handled?\ Saved arrays are stored in **sfallgv.sav** file (in savegame) in new (more flexible) format, just after the old arrays. So basically, when you load older savegame, sfall will load arrays from old format and save them to new format on next game save. If you load savegame made with sfall 3.4 using sfall 3.3 (for example), game shouldn't crash, but all arrays will be lost. * Previously you had to specify size in bytes for array elements. This parameter is now ignored and you can store strings of arbitrary length in arrays. diff --git a/docs/sslc.md b/docs/sslc.md index 68b6afaa..84720667 100644 --- a/docs/sslc.md +++ b/docs/sslc.md @@ -11,7 +11,7 @@ nav_order: 4 * TOC {: toc} -This is a modified copy of sslc, that has a few bugfixes from the original, that will recognise and compile the additional scripting functions provided by sfall, that can also understand some additional syntax, and that has an integrated preprocessor and optimizer. +This is a modified copy of sslc, that has a few bugfixes from the original, that will recognise and compile the additional script functions provided by sfall, that can also understand some additional syntax, and that has an integrated preprocessor and optimizer. Unlike the original script compiler, this has not been compiled as a dos program. When using this in place of the original compile.exe but still using p.bat, you need to either get rid of the dos4gw.exe reference from p.bat or replace the original dos4gw.exe with the one in this archive. @@ -19,7 +19,7 @@ If you use fallout script editor, you can extract `compile.exe` and `dos4gw.exe` When compiling global or hook scripts for sfall 3.4 or below, you _must_ include the line `procedure start;` before any `#include`s that define procedures to avoid a few weird problems. (this is no longer required starting from 3.5) -This version of compiler was designed primarily for new sfall functions, but it can safely (and is recommended) to be used with non-sfall scripts as well, as long as you don't use any of the arrays syntax and any sfall scripting functions. +This version of compiler was designed primarily for new sfall functions, but it can safely (and is recommended) to be used with non-sfall scripts as well, as long as you don't use any of the arrays syntax and any sfall script functions. The original unmodified sslc source is over here: [http://www.teamx.ru/eng/files/srcs/index.shtml](http://www.teamx.ru/eng/files/srcs/index.shtml).