fallout2sfall/sfall
0
0
Fork 0
mirror of https://github.com/sfall-team/sfall.git synced 2026-07-27 16:52:34 -07:00
Code Issues Packages Projects Releases Wiki Activity
Files
cebdc96e28d53794367220fd0735079b01477f2e
sfall/arrays/index.html
T

68 lines
36 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <title>Arrays - sfall</title> <link rel="shortcut icon" href="/sfall/favicon.ico" type="image/x-icon"> <link rel="stylesheet" href="/sfall/assets/css/just-the-docs-default.css"> <script type="text/javascript" src="/sfall/assets/js/vendor/lunr.min.js"></script> <script type="text/javascript" src="/sfall/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Begin Jekyll SEO tag v2.3.0 --> <title>Arrays | sfall</title> <meta property="og:title" content="Arrays" /> <meta property="og:locale" content="en_US" /> <meta name="description" content="Sfall documentation" /> <meta property="og:description" content="Sfall documentation" /> <link rel="canonical" href="/sfall/arrays/" /> <meta property="og:url" content="/sfall/arrays/" /> <meta property="og:site_name" content="sfall" /> <script type="application/ld+json"> {"@type":"WebPage","mainEntityOfPage":null,"image":null,"url":"/sfall/arrays/","author":null,"headline":"Arrays","dateModified":null,"datePublished":null,"sameAs":null,"publisher":null,"description":"Sfall documentation","name":null,"@context":"http://schema.org"}</script> <!-- End Jekyll SEO tag --> <link rel="apple-touch-icon" sizes="180x180" href="/assets/favicon/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon/favicon-16x16.png"> <link rel="manifest" href="/assets/favicon/site.webmanifest"> <link rel="mask-icon" href="/assets/favicon/safari-pinned-tab.svg" color="#5bbad5"> <meta name="msapplication-TileColor" content="#da532c"> <meta name="msapplication-config" content="/assets/favicon/browserconfig.xml"> <meta name="theme-color" content="#ffffff"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <div class="side-bar"> <div class="site-header"> <a href="/sfall/" class="site-title lh-tight"> sfall </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a> </div> <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item"><a href="/sfall/" class="nav-list-link">Home</a></li><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/arrays/" class="nav-list-link active">Arrays</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/array-functions/" class="nav-list-link">Array functions</a></li><li class="nav-list-item "><a href="/sfall/lists/" class="nav-list-link">Lists</a></li></ul></li><li class="nav-list-item"><a href="/sfall/best-practices/" class="nav-list-link">Best practices</a></li><li class="nav-list-item"><a href="/sfall/data-types/" class="nav-list-link">Data types</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/global-scripts/" class="nav-list-link">Global scripts</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/global-script-functions/" class="nav-list-link">Global script functions</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/hooks/" class="nav-list-link">Hooks</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/hook-functions/" class="nav-list-link">Hook functions</a></li><li class="nav-list-item "><a href="/sfall/hook-types/" class="nav-list-link">Hook types</a></li></ul></li><li class="nav-list-item"><a href="/sfall/sslc/" class="nav-list-link">SSLC</a></li><li class="nav-list-item"><a href="/sfall/optimization/" class="nav-list-link">Optimization</a></li><li class="nav-list-item"><a href="/sfall/animations/" class="nav-list-link">Animations</a></li><li class="nav-list-item"><a href="/sfall/art-and-appearance/" class="nav-list-link">Art and appearance</a></li><li class="nav-list-item"><a href="/sfall/audio/" class="nav-list-link">Audio</a></li><li class="nav-list-item"><a href="/sfall/car/" class="nav-list-link">Car</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/combat/" class="nav-list-link">Combat</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/knockback/" class="nav-list-link">Knockback</a></li><li class="nav-list-item "><a href="/sfall/weapons-and-ammo/" class="nav-list-link">Weapons and ammo</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/direct-memory-access/" class="nav-list-link">Direct memory access</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/call_offset_vx/" class="nav-list-link">call_offset_vX</a></li><li class="nav-list-item "><a href="/sfall/read_xxx/" class="nav-list-link">read_xxx</a></li><li class="nav-list-item "><a href="/sfall/write_xxx/" class="nav-list-link">write_xxx</a></li></ul></li><li class="nav-list-item"><a href="/sfall/explosions/" class="nav-list-link">Explosions</a></li><li class="nav-list-item"><a href="/sfall/global-variables/" class="nav-list-link">Global variables</a></li><li class="nav-list-item"><a href="/sfall/graphics/" class="nav-list-link">Graphics</a></li><li class="nav-list-item"><a href="/sfall/ini-settings/" class="nav-list-link">INI settings</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/interface/" class="nav-list-link">Interface</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/cursor/" class="nav-list-link">Cursor</a></li><li class="nav-list-item "><a href="/sfall/inventory/" class="nav-list-link">Inventory</a></li><li class="nav-list-item "><a href="/sfall/main-interface/" class="nav-list-link">Main interface</a></li><li class="nav-list-item "><a href="/sfall/outline/" class="nav-list-link">Outline</a></li><li class="nav-list-item "><a href="/sfall/pip-boy/" class="nav-list-link">Pip-Boy</a></li><li class="nav-list-item "><a href="/sfall/tags/" class="nav-list-link">Tags</a></li><li class="nav-list-item "><a href="/sfall/windows-and-images/" class="nav-list-link">Windows and images</a></li></ul></li><li class="nav-list-item"><a href="/sfall/keyboard-and-mouse/" class="nav-list-link">Keyboard and mouse</a></li><li class="nav-list-item"><a href="/sfall/locks/" class="nav-list-link">Locks</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/maps-and-encounters/" class="nav-list-link">Maps and encounters</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/rest/" class="nav-list-link">Rest</a></li><li class="nav-list-item "><a href="/sfall/worldmap/" class="nav-list-link">Worldmap</a></li></ul></li><li class="nav-list-item"><a href="/sfall/objects-and-scripts/" class="nav-list-link">Objects and scripts</a></li><li class="nav-list-item"><a href="/sfall/other/" class="nav-list-link">Other</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/perks-and-traits/" class="nav-list-link">Perks and traits</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/npc-perks/" class="nav-list-link">NPC perks</a></li></ul></li><li class="nav-list-item"><a href="/sfall/sfall-funcx-macros/" class="nav-list-link">Sfall funcX macros</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/sfall/" class="nav-list-link">Sfall</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/funcx/" class="nav-list-link">funcX</a></li><li class="nav-list-item "><a href="/sfall/version/" class="nav-list-link">Version</a></li></ul></li><li class="nav-list-item"><a href="/sfall/skills/" class="nav-list-link">Skills</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/stats/" class="nav-list-link">Stats</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/alter-min-max/" class="nav-list-link">Alter min/max</a></li></ul></li><li class="nav-list-item"><a href="/sfall/tiles-and-paths/" class="nav-list-link">Tiles and paths</a></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/sfall/variables/" class="nav-list-link">Variables</a><ul class="nav-list "><li class="nav-list-item "><a href="/sfall/math/" class="nav-list-link">Math</a></li><li class="nav-list-item "><a href="/sfall/strings/" class="nav-list-link">Strings</a></li></ul></li><li class="nav-list-item"><a href="/sfall/virtual-file-system/" class="nav-list-link">Virtual file system</a></li></ul> </nav> <footer class="site-footer"> This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </footer> </div> <div class="main" id="top"> <div id="main-header" class="main-header"> <div class="search"> <div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search sfall" aria-label="Search sfall" autocomplete="off"> <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label> </div> <div id="search-results" class="search-results"></div> </div> <nav aria-label="Auxiliary" class="aux-nav"> <ul class="aux-nav-list"> <li class="aux-nav-list-item"> <a href="https://nma-fallout.com/threads/fo2-engine-tweaks-sfall.178390/" class="site-button" > Forum </a> </li> <li class="aux-nav-list-item"> <a href="https://github.com/phobos2077/sfall/" class="site-button" > GitHub </a> </li> </ul> </nav> </div> <div id="main-content-wrap" class="main-content-wrap"> <div id="main-content" class="main-content" role="main"> <h1 class="no_toc" id="arrays"> <a href="#arrays" class="anchor-heading" aria-labelledby="arrays"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Arrays </h1> <p>sfall introduces new method of storing variables - arrays.</p> <p>Array is basically a container which can store variable number of values (elements). Each element in array can be of any type. Arrays can be extremely useful for some more advanced scripting, in conjunction with loops. See array function reference <a href="/sfall/array-functions/">here</a>.</p> <ul id="markdown-toc"> <li><a href="#arrays-concept" id="markdown-toc-arrays-concept">Arrays concept</a></li> <li><a href="#arrays-syntax" id="markdown-toc-arrays-syntax">Arrays syntax</a></li> <li><a href="#storing-arrays" id="markdown-toc-storing-arrays">Storing arrays</a></li> <li><a href="#practical-examples" id="markdown-toc-practical-examples">Practical examples</a> <ul> <li><a href="#use-arrays-to-implement-variable-argument-procedures" id="markdown-toc-use-arrays-to-implement-variable-argument-procedures">Use arrays to implement variable-argument procedures</a></li> <li><a href="#create-arrays-of-objects-maps-for-advanced-scripting" id="markdown-toc-create-arrays-of-objects-maps-for-advanced-scripting">Create arrays of objects (maps) for advanced scripting</a></li> </ul> </li> <li><a href="#array-operators-reference" id="markdown-toc-array-operators-reference">Array operators reference</a></li> <li><a href="#backward-compatibility-notes" id="markdown-toc-backward-compatibility-notes">Backward compatibility notes</a></li> </ul> <h2 id="arrays-concept"> <a href="#arrays-concept" class="anchor-heading" aria-labelledby="arrays-concept"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Arrays concept </h2> <p>Array elements are accessed by index or key. For example:</p> <div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// this code puts some string in array "list" at index 5:
</span><span class="n">list</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span> <span class="o">:=</span> <span class="s">"Value"</span><span class="p">;</span>
</code></pre></div></div> <p>There are 2 different types of arrays currently available:</p> <ul> <li> <p><strong>Lists</strong> - a set of values with specific size (number of elements), where all elements have numeric indexes starting from zero (0) up to array length minus one.</p> <p>For example:</p> <div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// this creates list with 3 elements. Element "A" has index 0, element "B" has index 1, element "C" - 2
</span><span class="n">list</span> <span class="o">:=</span> <span class="p">[</span><span class="s">"A"</span><span class="p">,</span> <span class="s">"B"</span><span class="p">,</span> <span class="s">"C"</span><span class="p">];</span>
</code></pre></div> </div> <p>Limitations:</p> <ul> <li>all indexes are numeric, starting from 0;</li> <li>to assign value to a specific index, you must first resize array to contain this index (for example, if list is of size 3 (indexes from 0 to 2), you can’t assign value to index 4 unless you change list size to 5 first).</li> </ul> </li> <li> <p><strong>Maps</strong> (or associative arrays) - a set of key=&gt;value pairs, where all elements (values) are accessed by corresponding keys.</p> <p>Differences from list:</p> <ul> <li>maps don’t have specific size (to assign values, you don’t need to resize array first);</li> <li>keys, just like values, can be of any type (but avoid using -1 as array keys or you won’t be able to use some functions reliably).</li> </ul> </li> </ul> <p>Both array types have their pros and cons and are suited for different tasks.</p> <h2 id="arrays-syntax"> <a href="#arrays-syntax" class="anchor-heading" aria-labelledby="arrays-syntax"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Arrays syntax </h2> <p>Basically arrays are implemented using number of new operators (scripting functions). But for ease of use, there are some new syntax elements:</p> <ul> <li>Accessing elements. Use square brackets: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">display_msg</span><span class="p">(</span><span class="nx">arr</span><span class="p">[</span><span class="mi">5</span><span class="p">]);</span>
<span class="nx">mymap</span><span class="p">[</span><span class="s2">"price"</span><span class="p">]</span> <span class="p">:</span><span class="o">=</span> <span class="mf">515.23</span><span class="p">;</span>
</code></pre></div> </div> </li> <li>Alternative accessing for maps. Use dot: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">display_msg</span><span class="p">(</span><span class="nx">mymap</span><span class="p">.</span><span class="nx">name</span><span class="p">);</span>
<span class="nx">mymap</span><span class="p">.</span><span class="nx">price</span> <span class="p">:</span><span class="o">=</span> <span class="mf">232.23</span><span class="p">;</span>
</code></pre></div> </div> </li> <li>Array expressions. Create and fill arrays with just one expression: <div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// create list with 5 values
</span><span class="p">[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">777</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">3.14</span><span class="p">,</span> <span class="s">"Cool Value"</span><span class="p">]</span>
<span class="c1">// create map:
</span><span class="p">{</span><span class="mi">5</span><span class="o">:</span> <span class="s">"Five"</span><span class="p">,</span> <span class="s">"health"</span><span class="o">:</span> <span class="mi">50</span><span class="p">,</span> <span class="s">"speed"</span><span class="o">:</span> <span class="mf">0.252</span><span class="p">}</span>
</code></pre></div> </div> <p><strong>NOTES:</strong> Make sure to call <code class="highlighter-rouge">fix_array</code> if you want new array to be available in the next frame or <code class="highlighter-rouge">save_array</code> if you want to use it for a longer period (see next section for details).</p> </li> <li>Iterating in loop. Use <code class="highlighter-rouge">foreach</code> key word like this: <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">foreach</span> <span class="p">(</span><span class="nx">item</span> <span class="k">in</span> <span class="nx">myarray</span><span class="p">)</span> <span class="nx">begin</span>
<span class="c1">// this block is executed for each array element, where "item" contains current value on each step</span>
<span class="nx">end</span>
<span class="c1">// alternative syntax:</span>
<span class="nx">foreach</span> <span class="p">(</span><span class="nx">key</span><span class="p">:</span> <span class="nx">item</span> <span class="k">in</span> <span class="nx">myarray</span><span class="p">)</span> <span class="nx">begin</span>
<span class="c1">// "key" will contain current key (or numeric index, for lists)</span>
<span class="nx">end</span>
</code></pre></div> </div> </li> </ul> <p>See “scripting_docs\compiler\sslc_readme.txt” file for full information on new SSL syntax features.</p> <h2 id="storing-arrays"> <a href="#storing-arrays" class="anchor-heading" aria-labelledby="storing-arrays"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Storing arrays </h2> <p>Apart from lists/maps arrays are divided by how they are stored. There a 3 types of arrays:</p> <ul> <li> <p><strong>Temporary</strong>. They are created using <code class="highlighter-rouge">temp_array</code> function or when using array expressions. 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 temp_array, it will not be available next time your global script is executed.</p> </li> <li> <p><strong>Permanent</strong>. They are created using <code class="highlighter-rouge">create_array</code> function or <code class="highlighter-rouge">fix_array</code> (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).</p> </li> <li> <p><strong>Saved</strong>. If you want your array to really stay for a while, use function <code class="highlighter-rouge">save_array</code> 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 <code class="highlighter-rouge">load_array</code> whenever you want to use them.</p> <p>Example:</p> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">variable</span> <span class="nx">savedArray</span><span class="p">;</span>
<span class="nx">procedure</span> <span class="nx">start</span> <span class="nx">begin</span>
<span class="k">if</span> <span class="nx">game_loaded</span> <span class="nx">then</span> <span class="nx">begin</span>
<span class="nx">savedArray</span> <span class="p">:</span><span class="o">=</span> <span class="nx">load_array</span><span class="p">(</span><span class="s2">"traps"</span><span class="p">);</span>
<span class="nx">end</span> <span class="k">else</span> <span class="nx">begin</span>
<span class="nx">foreach</span> <span class="nx">trap</span> <span class="k">in</span> <span class="nx">traps</span> <span class="nx">begin</span>
<span class="p">....</span>
<span class="nx">end</span>
<span class="nx">end</span>
<span class="nx">end</span>
</code></pre></div> </div> </li> </ul> <h2 id="practical-examples"> <a href="#practical-examples" class="anchor-heading" aria-labelledby="practical-examples"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Practical examples </h2> <h3 id="use-arrays-to-implement-variable-argument-procedures"> <a href="#use-arrays-to-implement-variable-argument-procedures" class="anchor-heading" aria-labelledby="use-arrays-to-implement-variable-argument-procedures"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Use arrays to implement variable-argument procedures </h3> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// define it</span>
<span class="nx">procedure</span> <span class="nx">give_item</span><span class="p">(</span><span class="nx">variable</span> <span class="nx">critter</span><span class="p">,</span> <span class="nx">variable</span> <span class="nx">pidList</span><span class="p">)</span> <span class="nx">begin</span>
<span class="nx">foreach</span> <span class="p">(</span><span class="nx">pid</span><span class="p">:</span> <span class="nx">qty</span> <span class="k">in</span> <span class="nx">pidList</span><span class="p">)</span> <span class="nx">begin</span>
<span class="nx">give_pid_qty</span><span class="p">(</span><span class="nx">critter</span><span class="p">,</span> <span class="nx">pid</span><span class="p">,</span> <span class="nx">qty</span><span class="p">);</span>
<span class="nx">end</span>
<span class="nx">end</span>
<span class="c1">// call it:</span>
<span class="nx">call</span> <span class="nx">give_item</span><span class="p">(</span><span class="nx">dude_obj</span><span class="p">,</span> <span class="p">{</span><span class="na">PID_SHOTGUN</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="na">PID_SHOTGUN_SHELLS</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span> <span class="na">PID_STIMPAK</span><span class="p">:</span> <span class="mi">3</span><span class="p">});</span>
</code></pre></div></div> <h3 id="create-arrays-of-objects-maps-for-advanced-scripting"> <a href="#create-arrays-of-objects-maps-for-advanced-scripting" class="anchor-heading" aria-labelledby="create-arrays-of-objects-maps-for-advanced-scripting"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Create arrays of objects (maps) for advanced scripting </h3> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">variable</span> <span class="nx">traps</span><span class="p">;</span>
<span class="nx">procedure</span> <span class="nx">init_traps</span> <span class="nx">begin</span>
<span class="c1">// just a quick example, there is a better way of doing it...</span>
<span class="nx">traps</span> <span class="p">:</span><span class="o">=</span> <span class="nx">load_array</span><span class="p">(</span><span class="s2">"traps"</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">traps</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="nx">then</span> <span class="nx">begin</span>
<span class="nx">traps</span> <span class="p">:</span><span class="o">=</span> <span class="p">[];</span>
<span class="nx">save_array</span><span class="p">(</span><span class="s2">"traps"</span><span class="p">,</span> <span class="nx">traps</span><span class="p">);</span>
<span class="nx">end</span>
<span class="nx">foreach</span> <span class="nx">k</span><span class="p">:</span> <span class="nx">v</span> <span class="k">in</span> <span class="nx">traps</span> <span class="nx">begin</span>
<span class="nx">traps</span><span class="p">[</span><span class="nx">k</span><span class="p">]</span> <span class="p">:</span><span class="o">=</span> <span class="nx">load_array</span><span class="p">(</span><span class="s2">"trap_"</span><span class="o">+</span><span class="nx">k</span><span class="p">);</span> <span class="c1">// each object is stored separately</span>
<span class="nx">end</span>
<span class="nx">end</span>
<span class="nx">procedure</span> <span class="nx">add_trap</span><span class="p">(</span><span class="nx">variable</span> <span class="nx">trapArray</span><span class="p">)</span> <span class="nx">begin</span>
<span class="nx">variable</span> <span class="nx">index</span><span class="p">;</span>
<span class="nl">index</span> <span class="p">:</span><span class="o">=</span> <span class="nx">len_array</span><span class="p">(</span><span class="nx">traps</span><span class="p">);</span>
<span class="nx">save_array</span><span class="p">(</span><span class="s2">"trap_"</span><span class="o">+</span><span class="nx">k</span><span class="p">,</span> <span class="nx">trapArray</span><span class="p">);</span>
<span class="nx">array_push</span><span class="p">(</span><span class="nx">traps</span><span class="p">,</span> <span class="nx">trapArray</span><span class="p">);</span>
<span class="nx">end</span>
<span class="c1">// use them:</span>
<span class="nx">foreach</span> <span class="nx">trap</span> <span class="k">in</span> <span class="nx">traps</span> <span class="nx">begin</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">self_elevation</span> <span class="o">==</span> <span class="nx">trap</span><span class="p">[</span><span class="s2">"elev"</span><span class="p">]</span> <span class="nx">and</span> <span class="nx">tile_distance</span><span class="p">(</span><span class="nx">self_tile</span><span class="p">,</span> <span class="nx">trap</span><span class="p">[</span><span class="s2">"tile"</span><span class="p">])</span> <span class="o">&lt;</span> <span class="nx">trap</span><span class="p">[</span><span class="s2">"radius"</span><span class="p">])</span> <span class="nx">then</span>
<span class="c1">// kaboom!!!</span>
<span class="nx">end</span>
<span class="nx">end</span>
</code></pre></div></div> <h2 id="array-operators-reference"> <a href="#array-operators-reference" class="anchor-heading" aria-labelledby="array-operators-reference"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Array operators reference </h2> <p><em>*mixed means any type</em></p> <ul> <li><code class="highlighter-rouge">int create_array(int size, int flags)</code>: <ul> <li>creates permanent array (but not “saved”)</li> <li>if <code class="highlighter-rouge">size &gt;= 0</code>, creates list with given size</li> <li>if <code class="highlighter-rouge">size == -1</code>, creates map (associative array)</li> <li>if <code class="highlighter-rouge">size == -1</code> and <code class="highlighter-rouge">flags == 2</code>, 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 <ul> <li>NOTE: in earlier versions (up to 4.1.3/3.8.13) the second argument is not used, just use 0</li> </ul> </li> <li>returns arrayID (valid until array is deleted)</li> </ul> </li> <li><code class="highlighter-rouge">int temp_array(int size, int flags)</code>: <ul> <li>works exactly like <code class="highlighter-rouge">create_array</code>, only created array becomes “temporary”</li> </ul> </li> <li><code class="highlighter-rouge">void fix_array(int arrayID)</code>: <ul> <li>changes “temporary” array into “permanent” (“permanent” arrays are not automatically saved into savegames)</li> </ul> </li> <li><code class="highlighter-rouge">void set_array(int arrayID, mixed key, mixed value)</code>: <ul> <li>sets array value</li> <li>if used on list, “key” must be numeric and within valid index range (0..size-1)</li> <li>if used on map, key can be of any type</li> <li>to “unset” a value from map, just set it to zero (0) <ul> <li>NOTE: to add a value of 0 for the key, use the float value of 0.0</li> </ul> </li> <li>this works exactly like statement: <code class="highlighter-rouge">arrayID[key] := value;</code></li> </ul> </li> <li><code class="highlighter-rouge">mixed get_array(int arrayID, mixed key)</code>: <ul> <li>returns array value by key or index</li> <li>if key doesn’t exist or index is not in valid range, returns 0</li> <li>works exactly like expression: <code class="highlighter-rouge">(arrayID[key])</code></li> </ul> </li> <li><code class="highlighter-rouge">void resize_array(int arrayID, int size)</code>: <ul> <li>changes array size</li> <li>applicable to maps too, but only to reduce elements</li> <li>there are number of special negative values of “size” which perform various operations on the array, use macros <code class="highlighter-rouge">sort_array</code>, <code class="highlighter-rouge">sort_array_reverse</code>, <code class="highlighter-rouge">reverse_array</code>, <code class="highlighter-rouge">shuffle_array</code> from <strong>sfall.h</strong> header</li> </ul> </li> <li><code class="highlighter-rouge">void free_array(int arrayID)</code>: <ul> <li>deletes any array</li> <li>if array was “saved”, it will be removed from a savegame</li> </ul> </li> <li><code class="highlighter-rouge">mixed scan_array(int arrayID, mixed value)</code>: <ul> <li>searches for a first occurence of given value inside given array</li> <li>if value is found, returns it’s index (for lists) or key (for maps)</li> <li>if value is not found, returns -1 (be careful, as -1 can be a valid key for a map)</li> </ul> </li> <li><code class="highlighter-rouge">int len_array(int arrayID)</code>: <ul> <li>returns number of elements or key=&gt;value pairs in a given array</li> <li>if array is not found, returns -1 (can be used to check if given array exist)</li> </ul> </li> <li><code class="highlighter-rouge">mixed array_key(int arrayID, int index)</code>: <ul> <li>don’t use it directly; it is generated by the compiler in foreach loops</li> <li>for lists, returns index back (no change)</li> <li>for maps, returns a key at the specified numeric index (don’t rely on the order in which keys are stored though)</li> <li>can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map</li> </ul> </li> <li><code class="highlighter-rouge">int arrayexpr(mixed key, mixed value)</code>: <ul> <li>don’t use it directly; it is used by compiler to create array expressions</li> <li>assigns value to a given key in an array, created by last <code class="highlighter-rouge">create_array</code> or <code class="highlighter-rouge">temp_array</code> call</li> <li>always returns 0</li> </ul> </li> <li><code class="highlighter-rouge">void save_array(mixed key, int arrayID)</code>: <ul> <li>makes the array saveable; it will be saved in <strong>sfallgv.sav</strong> file when saving the game</li> <li>arrayID is associated with given “key”</li> <li>array becomes permanent (if it was temporary) and “saved”</li> <li>key can be of any type (int, float or string)</li> <li>if you specify 0 as the key for the array ID, it will make the array “unsaved”</li> </ul> </li> <li><code class="highlighter-rouge">int load_array(mixed key)</code>: <ul> <li>loads array from savegame data by the same key provided in <code class="highlighter-rouge">save_array</code></li> <li>returns array ID or zero (0) if none found</li> </ul> </li> </ul> <h2 id="backward-compatibility-notes"> <a href="#backward-compatibility-notes" class="anchor-heading" aria-labelledby="backward-compatibility-notes"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Backward compatibility notes </h2> <p>For those who used arrays in their mods before sfall 3.4:</p> <ul> <li> <p>There is an INI parameter <strong>arraysBehavior</strong> in <strong>Misc</strong> section of ddraw.ini. If set to 0, all scripts which used sfall arrays before should work. This basically changes that <code class="highlighter-rouge">create_array</code> will create permanent arrays which are “saved” by default and their ID is also permanent. It is 1 by default.</p> </li> <li> <p>If <code class="highlighter-rouge">arraysBehaviour=0</code>: Arrays are created and manipulated with the <code class="highlighter-rouge">xxx_array</code> functions. An array must first be created with <code class="highlighter-rouge">create_array</code> or <code class="highlighter-rouge">temp_array</code>, 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 <code class="highlighter-rouge">create/temp_array</code> can then be used with the other array functions. Arrays are shared between all scripts. (i.e. you can call <code class="highlighter-rouge">create_array</code> from one script, and then use the returned id from another script.) They are also saved across savegames. Arrays created with <code class="highlighter-rouge">temp_array</code> 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. <code class="highlighter-rouge">create_array</code> is the only function that returns a permanent array, all other functions which return arrays (<code class="highlighter-rouge">string_split</code>, <code class="highlighter-rouge">list_as_array</code> etc,) all return temp arrays. You can use <code class="highlighter-rouge">fix_array</code> to make a temp array permanent.</p> </li> <li> <p>How savegame compatibility is handled?<br /> Saved arrays are stored in <strong>sfallgv.sav</strong> 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.</p> </li> <li> <p>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.</p> </li> </ul> <hr> <h2 class="text-delta">Table of contents</h2> <ul> </ul> </div> </div> <div class="search-overlay"></div> </div> </body> </html>
Reference in New Issue View Git Blame Copy Permalink