Frictional Game Wiki

<h1>Variables</h1> <div class="level1"> </div> <h3>At a Glance</h3> <div class="level3"> <pre class="code =c++"><span class="kw4">int</span> x<span class="sy0">;</span> <span class="kw4">int</span> a<span class="sy0">,</span> b<span class="sy0">;</span> <span class="kw4">int</span> c <span class="sy0">=</span> <span class="nu0">2</span><span class="sy0">,</span> d<span class="sy0">;</span> <span class="kw4">float</span> pi <span class="sy0">=</span> <span class="nu17">3.14f</span><span class="sy0">;</span> bool isAmnesiaTheBest <span class="sy0">=</span> <span class="kw2">true</span><span class="sy0">;</span> string subtitle <span class="sy0">=</span> "The Dark Descent"<span class="sy0">;</span> </pre><p> </p> </div> <h3>Discussion</h3> <div class="level3"> <p> The concept of variables is pretty much the same as used in math – a variable is something that can take on a number of different values. To be more precise, variables represent a scripter-friendly way to access locations in computer's memory – because we scripters are humans, it is easier for us to declare a variable with a meaningful, human-readable name, than to poke around the internal workings of the system. You can use variables to store various types of data. </p> <p> In order for it to be used in your code, a variable must first be <em>declared</em>.<br/> A <em>variable declaration</em> is where you introduce the variable for the first time, thus making it "known" to the script engine.<br/> </p> <p> A declaration has the following format:<br/> <code><em>typeName variableName</em>;</code><br/> or<br/> <code><em>typeName variableName</em> = <em>initialValue</em>;</code><br/> </p> <p> For example:<br/> <code>int unlitCandlesLeft = 4;</code><br/> </p> <p> Here, the <em>type</em> of the variable is integer, which is denoted by the <code>int</code> keyword. The name of the variable is <code>unlitCandlesLeft</code>, and it's set to the initial value of 4. The scripter chooses the variable name; it should reflect the purpose of the variable. Using such descriptive names makes the code more readable. Here, for example, <code>unlitCandlesLeft</code> could be used to count how many candlesticks in a level the Player should light up before some gameplay event happens. Variable names <em>cannot start with a number</em>. </p> <p> The script language supports different <em>variable types</em>, but for the purposes of Amnesia map scripting, it is enough to get familiar with just four basic data types: </p> <ul> <li class="level1"> <code>int</code> – represents integer numbers (… -4, -3, -2, -1, 0, 1, 2, 3, 4…)</li> <li class="level1"> <code>float</code> – represents floating-point (real) numbers (like 3.14, 0.001, -12.0, 1.41)</li> <li class="level1"> <code>string</code> – represents text; string literals are always placed in quotes ("Amnesia", "HPL2 Engine")</li> <li class="level1"> <code>bool</code> – represents Boolean values (can be either <code>true</code> or <code>false</code>)</li> </ul> <p> You choose the type for your variable depending on what kind of data you want to store. You wouldn't choose <code>int</code> if you want to store text. The feature of the language that enforces type constraints on variables is called <em>type safety</em>. This is important for several reasons. First, it can help debug your code if problems arise. Next, implicit conversions are generally not allowed among all types. Also, operations on variables of different types yield different results. For example, if you add two <code>int</code> numbers, you get the mathematically correct result:<br/> 2 + 3 = 5<br/> </p> <p> If you add two <code>string</code>-s, each of which is a textual representation of a number, the operation results in a new string which is a combination of the original two (string <em>concatenation</em>):<br/> "2" + "3" = "23"<br/> "Amne" + "sia" = "Amnesia" </p> <p> Time to learn how to use variables in code. Building on the <a href="/doku.php?id=hpl2:amnesia:script_language_reference_and_guide:quick_start" class="wikilink1" title="hpl2:amnesia:script_language_reference_and_guide:quick_start">Quick Start</a> example, let's begin with the following code for our script: </p> <pre class="code =c++"><span class="kw4">void</span> OnEnter<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> FadeOut<span class="br0">(</span><span class="nu17">0.0f</span><span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Turns the screen black instantly</span>   <span class="co1">// Now that the screen is black, do a 5 second fade in</span> <span class="co1">// for dramatic effect.</span> FadeIn<span class="br0">(</span><span class="nu17">5.0f</span><span class="br0">)</span><span class="sy0">;</span> <span class="br0">}</span> </pre><p> </p> <p> Let us now add two global variables, and use them to represent the durations for the screen fade effects. We will pass these variables to the fading functions in place of the numerical constants: </p> <pre class="code =c++"><span class="kw4">float</span> fadeOutTime <span class="sy0">=</span> <span class="nu17">0.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span> <span class="kw4">float</span> fadeInTime<span class="sy0">;</span> <span class="co1">// (uninitialized)</span>   <span class="kw4">void</span> OnEnter<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> FadeOut<span class="br0">(</span>fadeOutTime<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Turns the screen black</span>   <span class="co1">// Now that the screen is black, do a 5 second fade in</span> <span class="co1">// for dramatic effect.</span>   <span class="co1">// Assign a value to the fadeInTime variable</span> fadeInTime <span class="sy0">=</span> <span class="nu17">5.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span> FadeIn<span class="br0">(</span>fadeInTime<span class="br0">)</span><span class="sy0">;</span> <span class="br0">}</span> </pre><p> </p> <p> First, two variables are declared. The variable <code>fadeOutTime</code> is also initialized to the value of <code>0.0f</code> (the 'f' suffix tells the compiler that the literal 0.0 should be treated as a <code>float</code>; without the suffix, such numerical values are considered a different type, <code>double</code>, which is similar to <code>float</code>, but it can be used to represent a wider range of values. If the 'f' suffix is omitted, an implicit conversion from <code>double</code> to <code>float</code> is made, if possible. It's a good practice to use the 'f' suffix, although it's often not required).<br/> The <code>fadeOutTime</code> variable is then passed in as a parameter to the FadeOut() function, in place of the hard-coded number from the original code. This is possible since variables contain values, assigned to them by the scripter. </p> <p> The second variable, named <code>fadeInTime</code>, is left uninitialized for demonstration purposes. The aim of the code is to show you how you can also (re)assign values to variables in other places in the script. The line<br/> <code>fadeInTime = 5.0f;</code><br/> assigns the value of <code>5.0f</code> to the variable. After that, the variable is used as a parameter to the FadeIn() function. </p> <p> What is the advantage of this?<br/> Variables can be declared and initialized in one place, and then be reused in several other places in the code. Changing the value of the variable will affect all the code that uses it. In programming, it is a good practice to avoid redundant repetitions; when the same thing is repeated many times in many places, it is easy to make an error, but it is hard to fix it. Variables offer one way of organizing your code to avoid such repetition.<br/> </p> </div> <h4>Global vs Local Scope</h4> <div class="level4"> <p> Another point of interest is <em>where</em> the variables are declared. In the previous example, they were declared <em>globally</em>, outside of any function. <em>Global variables</em> are accessible from every part of your script file (from every function). If a variable is declared <em>inside the body</em> of a function, it is called a <em>local</em> variable. <em>Local variables</em> are available for use only from within that same function (and only in lines that come after the one where the variable is declared). Trying to use such a variable from a different function would result in an error. </p> <pre class="code =c++"><span class="kw4">void</span> OnEnter<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="kw4">float</span> fadeOutTime <span class="sy0">=</span> <span class="nu17">0.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span> <span class="kw4">float</span> fadeInTime <span class="sy0">=</span> <span class="nu17">5.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span>   FadeOut<span class="br0">(</span>fadeOutTime<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Turns the screen black</span>   FadeIn<span class="br0">(</span>fadeInTime<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Fade in for dramatic effect.</span> <span class="br0">}</span> </pre><p> </p> <p> In the code above, the two variables from previous example are now made local to the OnEnter() function. They can be used in pretty much the same way as before, but <em>only from within</em> that function. If you attempt to use them from a different function, you'll get an error message – to test this, add the OnLeave() function listed below, and then quick-reload the map. </p> <pre class="code =c++"><span class="kw4">void</span> OnEnter<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="kw4">float</span> fadeOutTime <span class="sy0">=</span> <span class="nu17">0.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span> <span class="kw4">float</span> fadeInTime <span class="sy0">=</span> <span class="nu17">5.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span>   FadeOut<span class="br0">(</span>fadeOutTime<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Turns the screen black</span>   FadeIn<span class="br0">(</span>fadeInTime<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Fade in for dramatic effect.</span> <span class="br0">}</span>   <span class="kw4">void</span> OnLeave<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="co1">// The next line should result in a compilation ERROR!</span> fadeInTime <span class="sy0">=</span> <span class="nu17">1.0f</span><span class="sy0">;</span> <span class="br0">}</span> </pre><p> </p> <p> The error says: </p> <pre class="code">INFO: Compiling void OnLeave() ERR : 'fadeIn Time' is not declared </pre><p> </p> <p> This error is in the context of the OnLeave() function; the script compiler reached that function, and then the line where <code>fadeInTime</code> was used (where the attempt was made to assign the value of <code>1.0f</code> to it). However, since no global variable with that name exist in this script, and no local declaration was found either, the compiler issues an error. So, the meaning of the error message is: although <code>fadeInTime</code> was declared somewhere in the file, the variable is local to a different function – it was not declared <em>neither globally, nor inside OnLeave()</em>, where it was used. </p> <p> To fix the error, delete (or comment out) the problematic line of code. The script below compiles and works. </p> <pre class="code =c++"><span class="kw4">void</span> OnEnter<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="kw4">float</span> fadeOutTime <span class="sy0">=</span> <span class="nu17">0.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span> <span class="kw4">float</span> fadeInTime <span class="sy0">=</span> <span class="nu17">5.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span>   FadeOut<span class="br0">(</span>fadeOutTime<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Turns the screen black</span>   FadeIn<span class="br0">(</span>fadeInTime<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Fade in for dramatic effect.</span> <span class="br0">}</span>   <span class="kw4">void</span> OnLeave<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="br0">}</span> </pre><p> </p> <p> &lt;note tip>Since the engine exposes the SetGlobalVar<em>Typename</em>() & SetLocalVar<em>Typename</em>() functions (and their Add- and Get- counterparts) for seting <em>game variables</em>, where the terms global and local have a slightly different meaning then what was presented here for <em>script variables</em>, here's a table that explains how these predefined functions and script-declared variables compare:&lt;/note> </p> <p> <a href="/lib/exe/fetch.php?media=hpl2:amnesia:script_language_reference_and_guide:variablescope_table.jpg" class="media" title="hpl2:amnesia:script_language_reference_and_guide:variablescope_table.jpg"><img src="/lib/exe/fetch.php?media=hpl2:amnesia:script_language_reference_and_guide:variablescope_table.jpg" class="mediacenter" alt="" /></a> </p> <p> &lt;note tip>The functions which manipulate global game variables, SetGlobalVar<em>Typename</em>(), AddGlobalVar<em>Typename</em>() and GetGlobalVar<em>Typename</em>() [where <em>Typename</em> can be either Int, Float, or String], provide a way for you to store and use a value in a storage location which is maintained for the duration of your game (or custom story). It can be accessed from more than one map script, and any changes in one map will be visible from the others. They are global <em>relative to the maps</em>. </p> <p> Functions which manipulate local game variables, SetLocalVar<em>Typename</em>(), AddLocalVar<em>Typename</em>() and GetLocalVar<em>Typename</em>(), allow you to define and use storage locations for the current map script. They are visible from every part of the map script, once set for the first time. So they are <em>local to that particular map script</em> (cant use them from a different map), but are <em>global relative to functions</em> in that script. In this respect, they are similar to the script variables declared globally (outside any function, or code block).&lt;/note> </p> </div> <h4>Simultaneous Declarations</h4> <div class="level4"> <p> It is possible to declare more than one variable in a single line, by separating variable names with commas. For example, the code<br/> <code>float x, y;</code><br/> declares two variables of the same type, float, named x and y. </p> <p> You can also initialize some or all of them in such a declaration: </p> <pre class="code">int a = 1, b = 2; int x = 5, y; </pre><p> </p> </div> <h4>Using Variables to Help Others (And Yourself!)</h4> <div class="level4"> <p> Those of you who write code snippets, or even longer scripts, for your fellow forum members can use variables to make your code easier to use and understand. Often, the same name or value appears in several places. Also, the script usually contains a lot of placeholder values, and when the person you are helping takes over the code, a lot of these placeholder values need to be replaced by the ones which are adequate in the context of their custom story or full conversion. The replacement process can be tedious and error prone, but variables come to the rescue (although search & replace tools can mitigate the problem). </p> <p> Instead of hard coding the names and values, you can assign them to variables at the beginning of your script, and then use variables instead. This way, if any changes need to be made, it only needs to happen in <em>one place</em> - at the start, where the variable declarations are. This eliminates the need to dig through the code, trying to find every single appearance of some value. </p> <p> Also, remember to give your variables descriptive names, so that others (and you) can quickly figure out what are they used for! You can indicate where the placeholder values should be replaced with a comment or two. </p> <pre class="code c++"><span class="co1">// Example: Fictional Help-Script</span> <span class="co1">// -----------------------------------</span>   <span class="co1">// Replace these assignments to match the names in your map</span> string scriptArea_jumpScare1 <span class="sy0">=</span> "Area_JumpScare1"<span class="sy0">;</span> string scriptArea_jumpScare2 <span class="sy0">=</span> "Area_JumpScare2"<span class="sy0">;</span> string scriptArea_startMusic <span class="sy0">=</span> "Area_StartMusic"<span class="sy0">;</span> string scriptArea_lookAtTarget <span class="sy0">=</span> "Area_LookAt"<span class="sy0">;</span> string particleSys_Orbs <span class="sy0">=</span> "PS_Orbs"<span class="sy0">;</span>   <span class="co1">// You can adjust these values as well, if you want</span> <span class="kw4">float</span> screenFadeInTime <span class="sy0">=</span> <span class="nu17">6.0f</span><span class="sy0">;</span> <span class="kw4">float</span> musicFadeInTime <span class="sy0">=</span> <span class="nu17">3.5f</span><span class="sy0">;</span>   <span class="co1">// ...</span>   <span class="co1">// Script that uses the variables above (omitted).</span> <span class="co1">// Note: the script would use a variable wherever the corresponding value would appear. E.g.:</span> <span class="co1">// FadeIn(screenFadeInTime); // ---> instead of hard-coded FadeIn(6.0f);</span> </pre><p> </p> </div> <h3>Naming Convention Tips</h3> <div class="level3"> <p> Variable names should be meaningful – one should be able to infer from their name what are they used for. These are some examples of good variable names: </p> <pre class="code =c++"><span class="kw4">int</span> numTinderboxes<span class="sy0">;</span> <span class="kw4">int</span> jumpScaresLeft<span class="sy0">;</span> <span class="kw4">float</span> fadeOutDuration<span class="sy0">;</span> bool isDoorLocked <span class="sy0">=</span> <span class="kw2">true</span><span class="sy0">;</span> </pre><p> </p> <p> In contrast, bad names for the same variables would be: </p> <pre class="code =c++"><span class="kw4">int</span> tndrs<span class="sy0">;</span> <span class="kw4">int</span> jpsCnt<span class="sy0">;</span> <span class="kw4">float</span> fod<span class="sy0">;</span> bool lckd<span class="sy0">;</span> </pre><p> </p> <p> Most people start variable names with a lowercase letter. If a variable name is composed of more than one word, you can use the so called camelCasing-based notation to separate individual components of the name. This is what you'll encounter throughout this guide. Another option is to use an underscore, like this: </p> <pre class="code =c++"><span class="kw4">int</span> num_tinderboxes<span class="sy0">;</span> <span class="kw4">int</span> jump_scares_left<span class="sy0">;</span> </pre><p> </p> <p> You can also combine the two: </p> <pre class="code =c++">string area_jumpScare1<span class="sy0">;</span> string area_jumpScare2<span class="sy0">;</span> string area_playerStart<span class="sy0">;</span> </pre><p> </p> <p> Which approach to use is entirely your choice, but once you decide upon one, it is a good idea to be consistent and stick to it. This will make it easier for you and other people to read and understand your code. </p> <p> See Also: <a href="/doku.php?id=hpl2:amnesia:script_language_reference_and_guide:types" class="wikilink1" title="hpl2:amnesia:script_language_reference_and_guide:types">Types</a>. </p> </div>