Better docs (#241)

* website skeleton * updated bunder to 2.0, added caching * fix missing plugins? * enable deploy for the branch, try to save cache * need to use relative path? * fix missing css * use doc theme * really enable doc theme? * mayeb this time * come on baby * how about now * please ? * pretty please * ehhh * working theme * added hooks * formatting * formatting 2 * added doc yaml from bgforge mls 1.0.7 * no need for nav order * link reference * hooks on top * added global scripts * pages are generated, exclude them * generate site * pip3 ? * maybe now * hooks page is generated automatically * added table of contents to pages * don't waste so much space * switch highlight classes * mark functions as code in description * more formatting * reformat doc with python * loaded offsets * opcode is loaded into yaml, txt no longer necessary * mark unsafe functions * restore hooks page * clarification * deduplicated hooks doc * saner TOC * typo * move more docs * hook scripts doc is now in md * arrays doc is now in md * added data types page * added more info about old behaviour * minor formatting issues * moved more function docs to yaml * all sfall functions docs are transpiled to yaml format * formatting * fix format * add subcategory support * simplified yaml format, added structure doc * simplified structure and added clarification * generated a separate page for hook types * formatting * disambiguation * format clarification * move get_map* to subcategory: doc is not relevant for other functions * simple permalink * fix links * included more info on the main page * more clarification * rename offset > opcode * try to get more sensible baseurl * added best practices page * what's up with the slashes * allow parent pages with no content * separate docs for direct memory access functions * added latest functions * fixed hook types link * move get_explosion_damage to macros * removed duplicated comment * removed old comments * added hook ids * lowercase sfall * more sfall lowercasing * added proper permalinks * changes from mr.stalin * fix typos * clarification * fix direct memory access page * fixed top navlink * fixed urls * checked sfallgv.sav, it's really not bloating much * format clarification * shorter name * add mixed data type, sort * add proc type, link hooks functions * use same terminology * added bool * rearranged index * added unsafe label * move to root * add stats * more upper/lowercase * should work now * added build status * added combat category, added description for modified_ini, moved global script functions into a subcat * special note for set_self * typo * enable children * cleanup * move lists to arrays * show header filename for macro instead * rearrange more items to be more intuitive * build on bionic * separate object manipulation * added object manipulation link to home * typo * formatting * Added a note about charges * punctuation * formatting * moved floor2 to math * changed label color * moved art and appearance to animations * name too long * search note * moved exex_map_update to maps category * moved more functions from other to skills * too much blue * formatting * moved art_cache_clear to art section * empathize that var name must be exactly 8 characters long * update usages for inc_npc_level * separate objects, scripts and variables * updated url * moved get_string_pointer to strings * updated add_extra_msg_file doc * typo * latest doc updates from develop * updated default layout from upstream * applied local changes: subcategory list * remove unnecessary backticks * added new functions * fix STD_PROCEDURE_END display * formatting * don't fail on missing hook id * formatting * updated doc from upstream * added optimization and sslc pages * order ssl and optimization pages below home * really order optimization on top * merge objects_in_radius variants * updated from upstream * tone down link color * fixed formatting for updated theme * updated travis for ruamel * added favicon * restored separator between functions * updated functions.yml * updated sfall functions * rearranged some window and object function * hook updates, pre-arg renaming * hook args renumbering * merged upstream * added new hooks and functions from upstream * remove the long-winded note about macro * switch to gha for jekyll deployment * sudo for deps * try to fix ruamel missing * switch build to master only, ref https://github.com/phobos2077/sfall/pull/241#discussion_r580365212 * update status badge for https://github.com/phobos2077/sfall/pull/241
2026-07-27 16:52:34 -07:00 · 2021-02-24 11:40:24 +03:00
parent 5b3a83df91
commit 5f0c5ae1fa
37 changed files with 4091 additions and 0 deletions
@@ -0,0 +1,105 @@
+---
+layout: page
+title: Optimization
+permalink: /optimization/
+nav_order: 5
+---
+
+
+# Optimization
+{: .no_toc}
+
+* TOC
+{: toc}
+
+The executation speed of scripts is not typically important in an unmodded game, given the difference in performance between a modern computer and what Fallout was designed for. When you start adding mods to the mix there's the potential for problems again, since sfall's global script system means that you can have a large amount of scripts being run every single frame.
+
+## sslc -O option
+
+The sfall build of sslc supports a -O command line option to perform an optimization pass over the generated code. This isn't a magic make-my-code-go-faster bullet; most of what it does is very limited in scope. It's primary purpose was to strip out the procedures and variables which get automatically pulled into every script that includes define.h, whether you use them or not, and to do something about the additional variables that get created by foreach loops.
+
+There are several levels of optimization available:
+- `-O1` - Basic, only removes unreferenced globals variables and procedures, code itself remains untouched.
+- `-O2` - Full, most code optimizations are on, but only those that were tested on complex scripts.
+- `-O3` - Experimental, provides most efficiency, but tend to break some complex code due to bugs.
+
+The following optimizations are performed:
+
+- constant expression folding: if an expression depends only on values which are known at compile time, then the expression is replaced by its result.
+  `a:=2+2;` -> `a:=4;`
+- constant variable initialization: All variables are initialised to some value, ('0', if you don't specify anything else,) so sslc attempts to make use of that fact to remove the first assignment to a variable if the first assignment is a constant expression.
+  ```
+  variable a;  -> variable a:=4;
+  a:=4;        -> 
+  ```
+- constant propagation: checks for values assigned to variables which can be computed at compile time, and replaces relevent references to the symbol by the constant. The original store is not removed by this optimization. Global variables are considered for this optimization only if they are not marked import or export, and are not assigned to anywhere in the script.
+  ```
+  a:=4     -> a:=4
+  foo(a);  -> foo(4);
+  ```
+- dead code removal: Checks for and removes code which cannot be reached, either because it is hidden behind a return or because the argument to an if statement can be computed at compile time.
+  ```
+  if 1 then begin        -> display_msg("foo");
+    display_msg("foo");  ->
+  end else begin         ->
+    display_msg("bar");  ->
+  end                    ->
+  ```
+-  unreferenced variable elimination: Checks for variables which are never referenced, and removes them. Also applies to global variables, as long as they are not marked for export.
+  ```
+  variable i, j, k;  -> variable i;
+  i:=1;              -> i:=1;
+  return;            -> return;
+  ```
+- unreferenced procedure elimination: Checks for any procedures which are never called, and removes them.
+  ```
+  procedure foo begin return "foo"; end   -> procedure foo begin return "foo"; end
+  procedure bar begin return "bar"; end   -> procedure start begin
+  procedure start begin                   ->   display_msg(foo);
+    display_msg(foo);                     -> end
+  end                                     ->
+  ```
+- dead store removal: Removes variable assignments if the result of the variable is unused, and if the expression used to compute the value of the variable is provably free of side effects. (See 'pure' keyword)
+  ```
+  a:="moo";         -> a:="foo";
+  a:="foo";         -> display_msg(a);
+  display_msg(a);   ->
+  a:="bar";         ->
+  ```
+- store combination: Where there are two stores in a row to the same variable, the two expressions are combined.
+  ```
+  var1 := var2; -> var1 := var2 + var3;
+  var1 += var3; -> 
+  ```
+- variable combination: Where usage regions of variables do not overlap, combine the variables to provide additional candidates for unreferenced variable elimination. Very useful for scripts containing multiple foreach loops, which generate 2 or 3 hidden variables each.
+  ```
+  a:="foo";         -> a:="foo";
+  display_msg(a);   -> display_msg(a);
+  b:="bar";         -> a:="bar";
+  display_msg(b);   -> display_msg(a);
+  ```
+- namelist compression: Fallout stores the names of all file scope variables and procedures in a namelist which is saved into the .int. Any of these that are unreferenced can be removed, and the names of global variables can be modified to make them shorter.
+
+## Writing your own code
+
+- Don't have global scripts running any more often that you need them to. Not everything needs to be run every single frame.
+- Never concat constant strings with the '+' operator, as it forces the operation to be done at runtime. The compiler can cope with constant strings being placed next to each other without the need for a +, which results in far more efficient code as the combination is done at lex time.
+  ```
+  #define GLOB_PREFIX "ts__"                    -> #define GLOB_PREFIX "ts__"
+
+  procedure start begin                         -> procedure start begin
+    set_sfall_global(GLOB_PREFIX + "foo1", 0);  ->   set_sfall_global(GLOB_PREFIX "foo1", 0);
+  end                                           -> end
+  ```
+- Avoid function calls in while loops. function calls are expensive in comparison to variable lookups, so it's more efficient to move the function call out of the loop and store the result in a variable
+  ```
+  while i < len_array(array) do begin           -> tmp:= len_array(array);
+    ...                                         -> while i < tmp do begin
+  end                                           ->   ...
+                                                -> end
+  ```
+- Mark functions with pure or inline where relevent.
+
+  'pure' is a hint to the optimizer that a procedure has no side effects. (i.e. there's no way to tell that it's been called aside from its return value.) Pure procedures cannot modify global variables, or call any other procedure that isn't itself pure. Functions marked with pure can only be used in expressions (i.e. you cannot use the `call <procedure>` syntax to call them.) If there are non-pure terms in an expression, it prevents that expression being considered for dead store removal. Where no such optimizations can be performed, or if optimization is disabled, marking a procedure with pure will have no effect on the compiled code.
+
+  'inline' is an instruction to the compiler to replace calls to the marked procedure with a copy of the procedures code instead of having a seperate call. inlined procedures cannot use the 'return' command, cannot be predefined, and cannot be used as part of an expression. inlining if a procedure is only going to be called once is always a win, but if there are multiple calls to a procedure you will end up bloating the size of the generated code.