Frictional Game Wiki

<h1>Constants and Enumerations</h1> <div class="level1"> <hr /> </div> <h2>At a Glance</h2> <div class="level2"> <p> Constants and enumerations allow you to define names which refer to values that should never change during the execution of a script. </p> <p> <b>Constants</b> </p> <pre class="code c++"><span class="co1">// Some math constants:</span> <span class="kw4">const</span> <span class="kw4">float</span> PI <span class="sy0">=</span> <span class="nu17">3.1415926f</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">float</span> E <span class="sy0">=</span> <span class="nu17">2.7182818f</span><span class="sy0">;</span>     <span class="co1">// Integer constants: </span> <span class="co1">// The constants in this example define when should collision events take place;</span> <span class="co1">// intended to be used with the AddEntityCollideCallback() engine function</span>   <span class="kw4">const</span> <span class="kw4">int</span> COLLIDE_ON_ENTER <span class="sy0">=</span> <span class="nu0">1</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> COLLIDE_ON_LEAVE <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">1</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> COLLIDE_ON_BOTH <span class="sy0">=</span> <span class="nu0">0</span><span class="sy0">;</span>   <span class="co1">// Usage:</span> AddEntityCollideCallback<span class="br0">(</span>"Player"<span class="sy0">,</span> "Area_Example"<span class="sy0">,</span> "ExampleCallback"<span class="sy0">,</span> <span class="kw2">false</span><span class="sy0">,</span> COLLIDE_ON_BOTH<span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> <b>Enumerated Constants (Enumerations)</b> </p> <pre class="code c++"><span class="kw2">enum</span> Color <span class="co1">// Note: Enums are based on the int type.</span> <span class="br0">{</span> Red<span class="sy0">,</span> <span class="co1">// has the default value of: 0</span> Green<span class="sy0">,</span> <span class="co1">// value: (previous + 1) = 1</span> Blue <span class="co1">// value: (previous + 1) = 2, etc, if more added...</span> <span class="br0">}</span>     <span class="co1">// Usage:</span> Color col <span class="sy0">=</span> Color<span class="sy0">::</span><span class="me2">Blue</span><span class="sy0">;</span> <span class="co1">// emphasizes the containing enum, improves code clarity</span>   <span class="co1">// Or just:</span> Color col <span class="sy0">=</span> Blue<span class="sy0">;</span> <span class="co1">// same effect</span>   <span class="co1">// Assigning an integer value is not possible without an explicit conversion:</span> Color col <span class="sy0">=</span> <span class="nu0">2</span><span class="sy0">;</span> <span class="co1">// Causes compilation error! </span>   <span class="co1">// Converting from integers - should generally be avoided: </span> Color col <span class="sy0">=</span> Color<span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Assigns Blue to col, since 2 corresponds to Color::Blue</span>   <span class="co1">// However:</span> Color col <span class="sy0">=</span> Color<span class="br0">(</span><span class="sy0">-</span><span class="nu0">15</span><span class="br0">)</span><span class="sy0">;</span> <span class="co1">// Has a value of -15, which is not tied to any Color! Could be a problem!</span>   <span class="co1">// This is allowed:</span> <span class="kw4">int</span> colValue <span class="sy0">=</span> col<span class="sy0">;</span> <span class="co1">// so, enums can be passed to functions expecting ints --> see example below</span>       <span class="co1">// Enumerations - choosing your own values</span> <span class="kw2">enum</span> CollisionState <span class="br0">{</span> Leave <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">1</span><span class="sy0">,</span> <span class="co1">// = -1</span> Both<span class="sy0">,</span> <span class="co1">// = 0 (previous + 1)</span> Enter <span class="co1">// = 1 (previous + 1)</span> <span class="br0">}</span>   <span class="co1">// Used as parameters to a function:</span> AddEntityCollideCallback<span class="br0">(</span>"Player"<span class="sy0">,</span> "Area_Example"<span class="sy0">,</span> "ExampleCallback"<span class="sy0">,</span> <span class="kw2">false</span><span class="sy0">,</span> CollisionState<span class="sy0">::</span><span class="me2">Both</span><span class="br0">)</span><span class="sy0">;</span>     <span class="co1">// You can define all or some of the values; those left undefined will be </span> <span class="co1">// assigned the value of previous_constant + 1</span> <span class="kw2">enum</span> Ending <span class="br0">{</span> Good <span class="sy0">=</span> <span class="nu0">1</span><span class="sy0">,</span> <span class="co1">// = 1</span> ReallyGood<span class="sy0">,</span> <span class="co1">// = 2 (previous + 1)</span> Neutral <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">10</span><span class="sy0">,</span> <span class="co1">// = -10</span> ReallyBad <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">2</span><span class="sy0">,</span> <span class="co1">// = -2</span> Bad<span class="sy0">,</span> <span class="co1">// = -1 (previous + 1)</span> Default <span class="sy0">=</span> Neutral <span class="co1">// = -10 < -- You can use previously defined constants</span> <span class="br0">}</span>   <span class="co1">// Binary FLAGS:</span> <span class="kw2">enum</span> QuestState <span class="br0">{</span> FoundNote1 <span class="sy0">=</span> <span class="nu12">0x01</span><span class="sy0">,</span> <span class="co1">// HEX for 1, which is in binary: 0000 0001</span> FoundNote2 <span class="sy0">=</span> <span class="nu12">0x02</span><span class="sy0">,</span> <span class="co1">// HEX for 2, which is in binary: 0000 0010</span> FoundItem <span class="sy0">=</span> <span class="nu12">0x04</span><span class="sy0">,</span> <span class="co1">// HEX for 4, which is in binary: 0000 0100</span> FoundPassage <span class="sy0">=</span> <span class="nu12">0x08</span><span class="sy0">,</span> <span class="co1">// HEX for 8, which is in binary: 0000 1000</span> FoundAll <span class="sy0">=</span> <span class="nu12">0x0F</span> <span class="co1">// HEX for 15, which is in binary: 0000 1111</span> <span class="br0">}</span> </pre><p> </p> </div> <h2>Discussion</h2> <div class="level2"> <p> Often, you'll need to define some values which are supposed to remain unchanged (constant) throughout the script, for the entire duration of its execution. You could use variables for this, being very careful not to change them, but even the best of scripters can make a mistake. The script language provides several constructs which enable you to define such constants, so that you can let the compiler worry about keeping them safe from you accidentally changing them. If you by any chance make a mistake and try to reassign a constant, the compiler will greet you with an error message - which is a good thing, because this protects your script from some potentially sneaky bugs. </p> <p> Constants can be of any type, and are declared almost exactly the same way as variables; the only difference is that the declaration is preceded by the <code>const</code> keyword, and that the value has to be assigned immediately (because it cannot be changed later on).<br/> <b>const</b> <em>typeName</em> <em>constantName</em> = <em>value</em>; </p> <p> The names of the constants defined are often written using ALL_CAPS, and individual words are separated with an underscore <code>_</code>. This naming convention enables you to easily distinguish such constants from variables and other names, <em>but</em> it is a matter of preference, and is not required by the language. </p> <p> It is common to define consts for mathematical and scientific constants, such are the numbers <em>pi</em>, <em>e</em>, or the gravitational acceleration <em>g</em>, etc. Other uses of constants include defining minimum or maximum values for something (max items, max health, etc…), or passing them as special values to functions (more on that later on). </p> <pre class="code c++"><span class="kw4">const</span> <span class="kw4">float</span> PI <span class="sy0">=</span> <span class="nu17">3.1415926f</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">float</span> E <span class="sy0">=</span> <span class="nu17">2.7182818f</span><span class="sy0">;</span>   <span class="kw4">const</span> <span class="kw4">int</span> MIN_ITEMS_FOUND <span class="sy0">=</span> <span class="nu0">2</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> MAX_ITEMS_FOUND <span class="sy0">=</span> <span class="nu0">5</span><span class="sy0">;</span>   <span class="kw4">const</span> <span class="kw4">float</span> MAX_HEALTH <span class="sy0">=</span> <span class="nu17">100.0f</span><span class="sy0">;</span>   <span class="kw4">const</span> <span class="kw4">float</span> MAX_WAIT_TIME <span class="sy0">=</span> <span class="nu17">10.0f</span><span class="sy0">;</span> <span class="co1">// in seconds</span> </pre><p> </p> <p> You can use constants in various ways, for example, in conditions of <a href="/doku.php?id=hpl2:amnesia:script_language_reference_and_guide:control_flow_-_conditional_statements" class="wikilink1" title="hpl2:amnesia:script_language_reference_and_guide:control_flow_-_conditional_statements">conditional statements</a> and <a href="/doku.php?id=hpl2:amnesia:script_language_reference_and_guide:control_flow_-_loops" class="wikilink1" title="hpl2:amnesia:script_language_reference_and_guide:control_flow_-_loops">loops</a>, or in mathematical expressions, or you can assign them to variables (note: when assigning to a variable, the variable gets a copy of the value stored in the constant; the variable can then be manipulated without affecting the constant itself). For example: </p> <pre class="code c++"><span class="kw4">float</span> radius <span class="sy0">=</span> <span class="nu17">2.5f</span><span class="sy0">;</span> <span class="kw4">float</span> circleArea <span class="sy0">=</span> PI <span class="sy0">*</span> radius <span class="sy0">*</span> radius<span class="sy0">;</span>   <span class="co1">// OR</span> <span class="kw4">float</span> health <span class="sy0">=</span> MAX_HEALTH<span class="sy0">;</span>   <span class="co1">// later on...</span> health <span class="sy0">=</span> <span class="nu17">0.0f</span><span class="sy0">;</span> </pre><p> </p> </div> <h3>Constants As Function Parameters</h3> <div class="level3"> <p> A function can take a parameter to decide which way should it go about doing its job (see <a href="/doku.php?id=hpl2:amnesia:script_language_reference_and_guide:funcions_-_part_1" class="wikilink1" title="hpl2:amnesia:script_language_reference_and_guide:funcions_-_part_1">Functions - Part 1</a> to learn more about functions). If there are only two ways, the function might accept a <code>bool</code> parameter, and make a decision based on whether the value of that parameter is <code>true</code> or <code>false</code>. For example, the engine exposes this predefined function: <code>SetFogActive(bool abActive)</code>. It takes a single <code>bool</code> parameter, which it uses to decide if the fog should be activated or deactivated. </p> <p> Often, though, there's more than two options, and in that case integers can be used to represent each of them. This approach is versatile in that it can be used to represent a varying number of options, however, the drawback is that the user of the function needs to remember the meanings of these numbers (sometimes referred to as "magic numbers"), and their meanings cannot be inferred just by reading the code.<br/> Amnesia provides some functions which use special-meaning integer values as parameters. Such parameters often appear in callbacks as well. For example, this predefined function, which forces a lever to be stuck in a certain position, takes three parameters: </p> <pre class="code c++"><span class="kw4">void</span> SetLeverStuckState<span class="br0">(</span>string<span class="sy0">&</span> leverName<span class="sy0">,</span> <span class="kw4">int</span> stuckState<span class="sy0">,</span> bool useEffects<span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> The first parameter <code>leverName</code> tells it to which lever it should be applied to. The third parameter <code>useEffects</code> we can ignore in this discussion. The second parameter, <code>stuckState</code> is an <code>int</code> parameter, and it tells the function in which position the lever should be stuck. It can be either: </p> <ul> <li class="level1"> <code>-1</code> - stuck at "min" side</li> <li class="level1"> <code>1</code> - stuck at "max" side</li> <li class="level1"> <code>0</code> - not stuck, rests in the middle</li> </ul> <p> This is how the function is used: if you wanted a lever which, say, controls the supply of electricity, called "Lever_Power", to be stuck at the "max" position, which will mean that the power is on, you would write: </p> <pre class="code c++">SetLeverStuckState<span class="br0">(</span>"Lever_Power"<span class="sy0">,</span> <span class="nu0">1</span><span class="sy0">,</span> <span class="kw2">false</span><span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> As you can see, you can't tell, if you don't already know, what <code>1</code> means just by looking at that line of code - you have to consult the documentation. The number itself is essentially meaningless to a human reader. <em>Constants can help with this:</em> </p> <pre class="code c++"><span class="co1">// Globally declared constants (script-scope):</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_MIN <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">1</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_MAX <span class="sy0">=</span> <span class="nu0">1</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_FREE <span class="sy0">=</span> <span class="nu0">0</span><span class="sy0">;</span>   <span class="co1">//...</span>   <span class="co1">// Elsewhere in the program:</span> SetLeverStuckState<span class="br0">(</span>"Lever_Power"<span class="sy0">,</span> LEVER_MAX<span class="sy0">,</span> <span class="kw2">false</span><span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> Now it's clear that the the function makes the lever stuck in the "max" state. But, constants can do even better than that. It is still not obvious what this "max" state means in the context of the game (that is, your custom story or full conversion) itself. We assumed earlier that the lever is used to turn the power on or off. Thus, to convey this information, the code can be modified like this: </p> <pre class="code c++"><span class="co1">// Globally declared constants (script-scope):</span>   <span class="co1">// Leave these for any other, generic levers, which might </span> <span class="co1">// possibly exist on the map</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_MIN <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">1</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_MAX <span class="sy0">=</span> <span class="nu0">1</span><span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_FREE <span class="sy0">=</span> <span class="nu0">0</span><span class="sy0">;</span>     <span class="co1">// Specific constants for the power-on/off lever:</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_POWER_OFF <span class="sy0">=</span> LEVER_MIN<span class="sy0">;</span> <span class="kw4">const</span> <span class="kw4">int</span> LEVER_POWER_ON <span class="sy0">=</span> LEVER_MAX<span class="sy0">;</span>     <span class="co1">//...</span>   <span class="co1">// Elsewhere in the program:</span> SetLeverStuckState<span class="br0">(</span>"Lever_Power"<span class="sy0">,</span> LEVER_POWER_ON<span class="sy0">,</span> <span class="kw2">false</span><span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> Now it is fairly obvious what the call to SetLeverStuckState() function does. </p> </div> <h3>Enumerations</h3> <div class="level3"> <p> Often you need to define a set of constants that are somehow related to each other, especially when they are intended to be passed as function parameters, like in the examples above. <em>Enumerations</em> provide a convenient language mechanism which enables you to group related constants together under one name. The syntax is as follows (in pseudocode): </p> <pre class="code c++"><span class="kw2">enum</span> EnumName <span class="br0">{</span> EnumConstantNameA<span class="sy0">,</span> EnumConstantNameB<span class="sy0">,</span> EnumConstantNameC<span class="sy0">,</span> EnumConstantNameD<span class="sy0">,</span>   <span class="co1">// etc...</span>   <span class="co1">// Note: it is not an error for the last</span> <span class="co1">// EnumConstant to be followed by a ',' symbol,</span> <span class="co1">// but it's generally not written</span> <span class="br0">}</span> </pre><p> </p> <p> Use the <code>enum</code> keyword to declare an enumeration; then you give it a name, and simply list a bunch of constants between the <code>{</code> and <code>}</code>. As with variables, the names you chose for the enumeration and its constants should be meaningful to a human reader.<br/> Enumerations (sometimes simply called enums) are based on the <code>int</code> type; that is, the values of the defined constants are nothing but integers under the hood. By default, the value of the first constant is <code>0</code>, and all the other constants have the value of the previous constant incremented by one. So, using pseudocode from the code box above, the values are: </p> <pre class="code c++"><span class="kw2">enum</span> EnumName <span class="br0">{</span> EnumConstantNameA<span class="sy0">,</span> <span class="co1">// = 0</span> EnumConstantNameB<span class="sy0">,</span> <span class="co1">// = 1 (previous + 1)</span> EnumConstantNameC<span class="sy0">,</span> <span class="co1">// = 2 (previous + 1)</span> EnumConstantNameD <span class="co1">// = 3 (previous + 1)</span> <span class="br0">}</span> </pre><p> </p> <p> You are allowed to specify your own values for <em>some or all</em> of the enumerated constants. For those constants you didn't specify any value, the same (previous + 1) rule will be applied: </p> <pre class="code c++"><span class="kw2">enum</span> EnumName <span class="br0">{</span> EnumConstantNameA <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">2</span><span class="sy0">,</span> <span class="co1">// = -2</span> EnumConstantNameB<span class="sy0">,</span> <span class="co1">// = -1 (previous + 1)</span> EnumConstantNameC <span class="sy0">=</span> <span class="nu0">15</span><span class="sy0">,</span> <span class="co1">// = 15</span> EnumConstantNameD <span class="co1">// = 16 (previous + 1)</span> <span class="br0">}</span> </pre><p> </p> <p> Enumerations, even though based on integers, should be viewed as code constructs which define a <em>new data type</em>, along with a set of values valid for the variables of that type. This is not entirely true, since variables of an enumerated type can be forced to store a value which is not defined in the corresponding list of enumerated constants, but let's ignore that for the moment. To declare such a variable, the same rules apply as for any other variable type:<br/> </p> <p> <em>EnumName</em> <em>variableName</em>; </p> <p> Just like with normal constants (those defined using the <code>const</code> keyword) declared at global (script-level) scope, enumerated constants can be accessed by their name. For example, to initialize a enum-type variable, you can write:<br/> </p> <p> <em>EnumName</em> <em>variableName</em> = <em>EnumConstantName</em>; </p> <p> However, for the reasons of code readability and clarity, when accessing enumerated constants it is often a good idea to include the name of the enumeration (<em>EnumName</em>) itself (especially when passing these values as parameters to functions), since <em>EnumName</em> often explains what is the common property used to group all the constants together in the first place. For this, the so-called scope resolution operator <code>::</code> is used:<br/> </p> <p> <em>EnumName</em> <em>variableName</em> = <em>EnumName</em>::<em>EnumConstantName</em>; </p> <p> For example: </p> <pre class="code c++"><span class="kw2">enum</span> Direction <span class="br0">{</span> North<span class="sy0">,</span> West<span class="sy0">,</span> South<span class="sy0">,</span> East <span class="br0">}</span>   <span class="co1">// Later on:</span> Direction sideOfTheWorld <span class="sy0">=</span> Direction<span class="sy0">::</span><span class="me2">North</span><span class="sy0">;</span> </pre><p> </p> <p> Another example: </p> <pre class="code c++"><span class="co1">// Let's assume there are only two types of items in your game</span>   <span class="kw2">enum</span> HealingPotion <span class="br0">{</span> Small <span class="sy0">=</span> <span class="nu0">10</span><span class="sy0">,</span> Medium <span class="sy0">=</span> <span class="nu0">30</span><span class="sy0">,</span> Large <span class="sy0">=</span> <span class="nu0">60</span><span class="sy0">,</span> Mega <span class="sy0">=</span> <span class="nu0">100</span> <span class="br0">}</span>   <span class="kw2">enum</span> BodyArmor <span class="br0">{</span> Weak <span class="sy0">=</span> <span class="nu0">50</span><span class="sy0">,</span> Strong <span class="sy0">=</span> <span class="nu0">100</span> <span class="br0">}</span>   <span class="co1">// Later on:</span> HealingPotion vial <span class="sy0">=</span> HealingPotion<span class="sy0">::</span><span class="me2">Small</span><span class="sy0">;</span> HealingPotion leatherArmor <span class="sy0">=</span> BodyArmor<span class="sy0">::</span><span class="me2">Small</span><span class="sy0">;</span>     <span class="co1">// Or as a parameter to a hypothetical function</span> <span class="co1">// void GivePlayerItems(HealingPotion potion, BodyArmor armor);</span>   <span class="co1">// Use:</span> GivePlayerItems<span class="br0">(</span>HealingPotion<span class="sy0">::</span><span class="me2">Small</span><span class="sy0">,</span> BodyArmor<span class="sy0">::</span><span class="me2">Weak</span><span class="br0">)</span><span class="sy0">;</span>   <span class="co1">// Rather than:</span> GivePlayerItems<span class="br0">(</span>Small<span class="sy0">,</span> Weak<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// which is which?</span>   <span class="co1">// Alternatively:</span> GivePlayerItems<span class="br0">(</span>vial<span class="sy0">,</span> leatherArmor<span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> &lt;note important>Although enumerated constants are grouped together under a single name, and can be accessed through that name using the scope resolution operator (<code>::</code>), they actually have a global (script-level) scope, so two constants in two different enums cannot share a name. For example, this is not allowed by the language: </p> <pre class="code c++"><span class="kw2">enum</span> HealingPotion <span class="br0">{</span> Small <span class="sy0">=</span> <span class="nu0">10</span><span class="sy0">,</span> Medium <span class="sy0">=</span> <span class="nu0">30</span><span class="sy0">,</span> Large <span class="sy0">=</span> <span class="nu0">60</span><span class="sy0">,</span> Mega <span class="sy0">=</span> <span class="nu0">100</span> <span class="br0">}</span>   <span class="kw2">enum</span> BodyArmor <span class="br0">{</span> Small <span class="sy0">=</span> <span class="nu0">50</span><span class="sy0">,</span> <span class="co1">// compiler error</span> Large <span class="sy0">=</span> <span class="nu0">100</span> <span class="co1">// compiler error</span> <span class="br0">}</span> </pre><p> </p> <p> &lt;/note> </p> </div> <h4>Relation to the Integer Type</h4> <div class="level4"> <p> As discussed, enums are based on the <code>int</code> type. This allows them to be implicitly converted to integers if required, so they can be used in place of them. This is especially useful with functions that use "magic numbers". Implicit conversion <em>from</em> integers to enums, however, <em>is not allowed</em>. </p> <pre class="code c++"><span class="kw2">enum</span> PowerLeverState <span class="br0">{</span> Undefined<span class="sy0">,</span> <span class="co1">// = 0</span> On<span class="sy0">,</span> <span class="co1">// = 1</span> Off <span class="co1">// = 2</span> <span class="br0">}</span>   <span class="co1">// Later on:</span> <span class="co1">// Accepts a value of type PowerLeverState, even though it expects an int</span> SetLeverStuckState<span class="br0">(</span>"Lever_Power"<span class="sy0">,</span> PowerLeverState<span class="sy0">::</span><span class="me2">On</span><span class="sy0">,</span> <span class="kw2">false</span><span class="br0">)</span><span class="sy0">;</span>   <span class="co1">// Also:</span> <span class="kw4">int</span> stateValue <span class="sy0">=</span> PowerLeverState<span class="sy0">::</span><span class="me2">Off</span><span class="sy0">;</span> <span class="co1">// allowed; stateValue is now 2</span>   <span class="co1">// Wheres:</span> PowerLeverState state <span class="sy0">=</span> <span class="nu0">2</span><span class="sy0">;</span> <span class="co1">// NOT allowed!</span> </pre><p> </p> <p> If you want to assign an <code>int</code> value to a enum-type variable, you have to explicitly convert it: </p> <pre class="code c++">PowerLeverState state1 <span class="sy0">=</span> PowerLeverState<span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span><span class="sy0">;</span> <span class="co1">// now state1 = PowerLeverState::Off</span>   <span class="co1">// Also:</span> <span class="kw4">int</span> val <span class="sy0">=</span> RandomInt<span class="br0">(</span><span class="nu0">0</span><span class="sy0">,</span> <span class="nu0">2</span><span class="br0">)</span><span class="sy0">;</span> PowerLeverState state2 <span class="sy0">=</span> PowerLeverState<span class="br0">(</span>val<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// state2 takes a random value</span> </pre><p> </p> <p> However, conversions like this should be done with care; although there are legitimate uses for them, conversions of this sort often indicate that your script can be better structured. When converting from integers, you run a risk of making your enum-type variables contain values other than those that have been defined as acceptable for their type: </p> <pre class="code c++">PowerLeverState state1 <span class="sy0">=</span> PowerLeverState<span class="br0">(</span><span class="nu0">100</span><span class="br0">)</span><span class="sy0">;</span> <span class="co1">// state1 = 100. Now what? </span>     <span class="co1">// Also:</span> <span class="kw4">int</span> val <span class="sy0">=</span> <span class="sy0">-</span><span class="nu0">1</span><span class="sy0">;</span>   <span class="co1">// later on</span> PowerLeverState state2 <span class="sy0">=</span> PowerLeverState<span class="br0">(</span>val<span class="br0">)</span><span class="sy0">;</span> <span class="co1">// state2 = -1. Could this cause problems? </span> </pre><p> </p> <p> Although this compiles, and no error is displayed, depending on how your script is written, this may or may not cause problems. As conversions of this kind might happen accidentally, if your script relies on enums always having valid values, then there's a great chance that it will fail if a problematic enum-typed value comes along. So, always assume that such a value could be passed to your functions, and decide what to do if it happens. Often enough, you can simply ignore that case, and make your function do nothing and just silently end, but, if the underlying integer value is somehow used (for example, to cycle through all the possible values in a given enumeration), you need to check if the value provided is in the valid range first, and replace it with some acceptable value if it's not. </p> </div> <h4>Using Enums to Define Binary Flags</h4> <div class="level4"> <p> &lt;note>The following section discusses slightly more advanced concepts, and also assumes you have the basic understanding of <a href="/doku.php?id=hpl2:amnesia:script_language_reference_and_guide:control_flow_-_conditional_statements" class="wikilink1" title="hpl2:amnesia:script_language_reference_and_guide:control_flow_-_conditional_statements">conditional statements</a>. You can skip it and come back later if you find it too hard to follow.&lt;/note> </p> <p> As it was discussed on the <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> page, the computer stores data in the form of <em>bytes</em>. One byte contains 8 <em>bits</em>, each of which can be either 0 or 1. This means that the computer encodes <em>everything</em> as sequences of zeros and ones (from simple data like integer numbers, floating point numbers, to srings, vectors, player attributes, Amnesia monsters, the image on this screen, etc.). </p> <p> <a href="/lib/exe/fetch.php?tok=44e08b&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8467%2F8371332748_e001db2c28_n.jpg" class="media" title="http://farm9.staticflickr.com/8467/8371332748_e001db2c28_n.jpg"><img src="/lib/exe/fetch.php?tok=44e08b&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8467%2F8371332748_e001db2c28_n.jpg" class="mediacenter" title="8371332748_e001db2c28_n.jpg" alt="8371332748_e001db2c28_n.jpg" /></a> </p> <p> The binary system represents all numbers using only two symbols, 0 and 1. Each combination of zeros and ones encodes an integer number (for integer types) or maybe something else (for other types). For example, the binary number 00110101 depicted above represents the number 53. Now, we are not too concerned here with the details of <em>how</em> exactly all these are encoded (you can read about that elsewhere), but we are going to take a closer look at integer numbers, since this is what enum constants are under the hood. Let as first look at a single byte. </p> <p> Because there are 256 different combinations of ones and zeros for 8 binary places, a byte can encode 256 different values at <em>one time</em>. But, when used in a clever way, a byte can represent up to 8 different binary states <em>simultaneously</em>. Such binary states (like on/off, pressed/depressed, lit/unlit, locked/unlocked etc.), can be encoded by correlating them to a specific position (specific bit) in a byte. For example, in the image below, a single byte is used to encode 6 different states related to the progress of a player through a level. Two of the bits are not used. </p> <p> <a href="/lib/exe/fetch.php?tok=83da93&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8513%2F8371352462_ccf55f1631.jpg" class="media" title="http://farm9.staticflickr.com/8513/8371352462_ccf55f1631.jpg"><img src="/lib/exe/fetch.php?tok=83da93&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8513%2F8371352462_ccf55f1631.jpg" class="mediacenter" title="8371352462_ccf55f1631.jpg" alt="8371352462_ccf55f1631.jpg" /></a> </p> <p> In this example, knowing what is represented by each of the bits, you can read the value 0011 1010 to mean: </p> <ul> <li class="level1"> 0 - (not used)</li> <li class="level1"> 0 - (not used)</li> <li class="level1"> 1 - the monster was slain by the player</li> <li class="level1"> 1 - the key was found</li> <li class="level1"> 1 - the light is lit</li> <li class="level1"> 0 - the note was not found</li> <li class="level1"> 1 - the switch is in the "on" state</li> <li class="level1"> 0 - the lock is left unlocked</li> </ul> <p> All of that information is encoded in <em>a single byte</em>. This is one of the reasons to use flags - using them saves memory (a single byte vs several state variables). The other reason is that flags can be (and usually are) passed as parameters to functions, whereby several indicators of simple binary states are passed to the function simultaneously, through one variable. Flags often encode "settings"-like data, but should be used with care, as they can affect code readability and clarity. </p> <p> <em>How to manipulate individual bits then?</em> Well, by assigning integer numbers to variables, and by using binary logical operators, described below. However, manipulating bits while working with numbers in the decimal system is not very convenient. This is why programmers often use <em>hexadecimal</em> (HEX) numbers for such tasks. The reason is: there's a direct correspondence between HEX and binary numbers, as the table below shows, which makes it easy to deal with binary representations. </p> <p> <a href="/lib/exe/fetch.php?tok=c1eba1&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8365%2F8371351734_f2f2795a54.jpg" class="media" title="http://farm9.staticflickr.com/8365/8371351734_f2f2795a54.jpg"><img src="/lib/exe/fetch.php?tok=c1eba1&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8365%2F8371351734_f2f2795a54.jpg" class="mediacenter" title="8371351734_f2f2795a54.jpg" alt="8371351734_f2f2795a54.jpg" /></a> </p> <p> As you can see, unlike the decimal number system, which represents all numbers using 10 different symbols (0-9), the HEX number system represents those same numbers using 16 different symbols (0-F). It just so happens that each of the HEX digits perfectly corresponds to one of all possible 4-bit combinations. Any one byte can thus be represented by 2 HEX digits - all you need to do is to refer to the table above, pick two hexadecimal digits, and write them together. To get the corresponding binary number, just replace the HEX digit with its binary equivalent from the table. </p> <p> Representing bytes using HEX system - some examples: </p> <pre class="code">HEX binary ---------------------- 00 0000 0000 40 0100 0000 02 0000 0010 88 1000 1000 3A 0011 1010 FC 1111 1100 </pre><p> </p> <p> Note that to be able to do this, you <em>don't have to</em> understand the internal workings of the decimal, binary and hexadecimal number systems (although I encourage you to learn more on the web), nor do you have to know how to convert binary and HEX representations to and from decimal; all you need to know is which HEX digit corresponds to which binary sequence (and you can get that from the table). </p> <p> Since HEX digits include both numerals and characters, the script language needs a way to distinguish HEX numerical literals from other numbers and variable names. So, the language provides the <code>0x</code> prefix - when you want to express a number in the HEX format, start by typing <code>0x</code> and then immediately (with no spaces in between) follow with your hex digits: </p> <pre class="code c++"><span class="nu12">0x51</span> <span class="co1">// A HEX number.</span> <span class="nu0">51</span> <span class="co1">// A decimal number.</span>   <span class="nu12">0x03</span> <span class="co1">// A HEX number.</span> <span class="nu8">03</span> <span class="co1">// A decimal integer 3.</span>   <span class="nu12">0x5A</span> <span class="co1">// A HEX number.</span> 5A <span class="co1">// A compiler error?</span>   <span class="nu12">0xD6</span> <span class="co1">// A HEX number.</span> D6 <span class="co1">// A variable? A function? A type name?</span> </pre><p> </p> <p> On the <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> page, it was said that the <code>int</code> type takes up 4 bytes of memory. This means that a single integer can be used to represent 32 different binary states, of "flags", simultaneously. As with a single byte before, you don't have to use all of them. Also, since a 2-digit HEX number represents one byte, an 8-digit HEX number can be used to represent any 4-byte integer. You don't have to use all of the 8 digits, either – if you use less than 8, the compiler will assume that the missing digits are all 0. </p> <p> Finally, this can all be applied when specifying values for the enumerated constants, so that they can be used as binary flags. For the purpose of being flags, only binary values which contain a single bit set to 1 are used. In the table above, such values are highlighted in blue. There are only four of them, and they are all different representations for the numbers which are powers of two (just like, in decimal system, numbers like 1, 10, 100, 1000, etc., are all various powers of 10). </p> <p> This way, each enum constant corresponds to a single bit in the binary number. </p> <pre class="code c++"><span class="co1">// Note: Although the constants are 4-byte integers, since only a single byte </span> <span class="co1">// is used, all values will be represented as bytes</span>   <span class="kw2">enum</span> QuestCompletedFlags <span class="br0">{</span> None <span class="sy0">=</span> <span class="nu12">0x00</span><span class="sy0">,</span> <span class="co1">// = 0000 0000</span> DoorLocked <span class="sy0">=</span> <span class="nu12">0x01</span><span class="sy0">,</span> <span class="co1">// = 0000 0001</span> SwitchTurnedOn <span class="sy0">=</span> <span class="nu12">0x02</span><span class="sy0">,</span> <span class="co1">// = 0000 0010</span> NoteFound <span class="sy0">=</span> <span class="nu12">0x04</span><span class="sy0">,</span> <span class="co1">// = 0000 0100</span> LightsLit <span class="sy0">=</span> <span class="nu12">0x08</span><span class="sy0">,</span> <span class="co1">// = 0000 1000</span> KeyFound <span class="sy0">=</span> <span class="nu12">0x10</span><span class="sy0">,</span> <span class="co1">// = 0001 0000</span> MonsterSlain <span class="sy0">=</span> <span class="nu12">0x20</span> <span class="co1">// = 0010 0000</span> <span class="br0">}</span> </pre><p> </p> <p> The enum flags defined in the code box above correspond to the possible states depicted earlier. Once the flags (constants) themselves are defined, they can be combined using the binary OR operator <code>|</code>: </p> <pre class="code c++"><span class="kw4">int</span> questState <span class="sy0">=</span> QuestCompletedFlags<span class="sy0">::</span><span class="me2">DoorLocked</span> <span class="sy0">|</span> QuestCompletedFlags<span class="sy0">::</span><span class="me2">LightsLit</span><span class="sy0">;</span>   <span class="coMULTI">/* The value of questState is now (in binary): ------------------------------------------------- DoorLocked: 0000 0001 | LightsLit: 0000 1000 = questState: 0000 1001 (the door is locked and the lights are lit) */</span> </pre><p> </p> <p> The next code box shows how to represent the state which corresponds to the image below: <a href="/lib/exe/fetch.php?tok=83da93&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8513%2F8371352462_ccf55f1631.jpg" class="media" title="http://farm9.staticflickr.com/8513/8371352462_ccf55f1631.jpg"><img src="/lib/exe/fetch.php?tok=83da93&media=http%3A%2F%2Ffarm9.staticflickr.com%2F8513%2F8371352462_ccf55f1631.jpg" class="mediacenter" title="8371352462_ccf55f1631.jpg" alt="8371352462_ccf55f1631.jpg" /></a> </p> <pre class="code c++"><span class="co1">// NOTE: "QuestCompletedFlags::" qualifiers ommitted for brevity.</span>   <span class="kw4">int</span> questState <span class="sy0">=</span> SwitchTurnedOn <span class="sy0">|</span> LightsLit <span class="sy0">|</span> KeyFound <span class="sy0">|</span> MonsterSlain<span class="sy0">;</span>   <span class="coMULTI">/* The value of questState is now (in binary): ------------------------------------------------- SwitchTurnedOn: 0000 0010 | LightsLit: 0000 1000 | KeyFound: 0001 0000 | MonsterSlain: 0010 0000 = questState: 0011 1010 */</span> </pre><p> </p> <p> If you are familiar with the <a href="/doku.php?id=hpl2:amnesia:script_language_reference_and_guide:control_flow_-_conditional_statements#using_logical_operators" class="wikilink1" title="hpl2:amnesia:script_language_reference_and_guide:control_flow_-_conditional_statements">boolean logical operators</a>, you'll be pleased to learn that the binary logical operators work pretty much the same way, only on individual bits. They take two numbers as input, and produce a third number based on the bits of the inputs provided. </p> <p> <b>The binary OR operator</b> (<code>|</code>) sets a bit to <code>1</code> in the output if <em>any</em> of the corresponding bits in the inputs is <code>1</code>. This is why it can be used to combine flags.<br/> 0011 | 1100 = 1111 </p> <p> <b>The binary AND operator</b> (<code>&</code>) sets a bit to <code>1</code> in the output <em>only if both</em> of the corresponding input bits are <code>1</code>. For this reason, it can be used to check if a certain bit is set or not.<br/> 1110 & 0100 = 0100 → if the result equals to the value of the tested flag, the bit was set<br/> 1110 & 0001 = 0000 → if the result is 0 (zero), the bit was not set </p> <p> <b>The binary XOR operator</b> (<code>^</code>), a.k.a exclusive-OR, sets a bit to <code>1</code> only if the corresponding input bits <em>are different</em>. It can be used to invert all the bits.<br/> 0101 ^ 0000 = 0101 → (nothing happens)<br/> 0101 ^ 1111 = 1010 → inversion </p> <p> So, how it all looks like in code? You've already seen how to set flags using the binary OR (<code>|</code>) operator. The following code snippet demonstrates, continuing from the previous examples, how to check if the flag <code>MonsterSlain</code> was set in the <code>questState</code> variable: </p> <pre class="code c++"><span class="kw1">if</span> <span class="br0">(</span><span class="br0">(</span>questState <span class="sy0">&</span> QuestCompletedFlags<span class="sy0">::</span><span class="me2">MonsterSlain</span><span class="br0">)</span> <span class="sy0">==</span> QuestCompletedFlags<span class="sy0">::</span><span class="me2">MonsterSlain</span><span class="br0">)</span> <span class="br0">{</span> <span class="co1">// the monster was slain by the Player...</span> <span class="br0">}</span> <span class="kw1">else</span> <span class="br0">{</span> <span class="co1">// the monster lives!</span> <span class="br0">}</span>   <span class="co1">// questState: 0011 1010</span> <span class="co1">// & MonsterSlain: 0010 0000</span> <span class="co1">// = 0010 0000</span> </pre><p> </p> <p> You can also check for several flags at once, by using AND (<code>&</code>) with binary numbers with multiple bits set to <code>1</code>. </p> <pre class="code c++"><span class="co1">// the value of: 0x30 = 0011 0000</span> <span class="kw4">int</span> checkState <span class="sy0">=</span> QuestCompletedFlags<span class="sy0">::</span><span class="me2">MonsterSlain</span> <span class="sy0">|</span> QuestCompletedFlags<span class="sy0">::</span><span class="me2">KeyFound</span><span class="sy0">;</span>   <span class="kw1">if</span> <span class="br0">(</span><span class="br0">(</span>questState <span class="sy0">&</span> checkState<span class="br0">)</span> <span class="sy0">==</span> checkState<span class="br0">)</span> <span class="br0">{</span> <span class="co1">// both flags set</span> <span class="br0">}</span> </pre><p> </p> <p> Or, you can check all at once: </p> <pre class="code c++"><span class="kw4">int</span> checkState <span class="sy0">=</span> <span class="nu12">0x3F</span><span class="sy0">;</span> <span class="co1">// = 0011 1111</span>   <span class="kw1">if</span> <span class="br0">(</span><span class="br0">(</span>questState <span class="sy0">&</span> checkState<span class="br0">)</span> <span class="sy0">==</span> checkState<span class="br0">)</span> <span class="br0">{</span> <span class="co1">// all quests completed</span> <span class="br0">}</span> </pre><p> </p> <p> It is often convenient to include the "all flags set" value into the enumeration: </p> <pre class="code c++"><span class="kw2">enum</span> QuestCompletedFlags <span class="br0">{</span> None <span class="sy0">=</span> <span class="nu12">0x00</span><span class="sy0">,</span> <span class="co1">// = 0000 0000</span> DoorLocked <span class="sy0">=</span> <span class="nu12">0x01</span><span class="sy0">,</span> <span class="co1">// = 0000 0001</span> SwitchTurnedOn <span class="sy0">=</span> <span class="nu12">0x02</span><span class="sy0">,</span> <span class="co1">// = 0000 0010</span> NoteFound <span class="sy0">=</span> <span class="nu12">0x04</span><span class="sy0">,</span> <span class="co1">// = 0000 0100</span> LightsLit <span class="sy0">=</span> <span class="nu12">0x08</span><span class="sy0">,</span> <span class="co1">// = 0000 1000</span> KeyFound <span class="sy0">=</span> <span class="nu12">0x10</span><span class="sy0">,</span> <span class="co1">// = 0001 0000</span> MonsterSlain <span class="sy0">=</span> <span class="nu12">0x20</span><span class="sy0">,</span> <span class="co1">// = 0010 0000</span> AllDone <span class="sy0">=</span> <span class="nu12">0x3F</span> <span class="co1">// = 0011 1111</span> <span class="br0">}</span>     <span class="co1">//later on:</span> <span class="kw4">int</span> checkState <span class="sy0">=</span> QuestCompletedFlags<span class="sy0">::</span><span class="me2">AllDone</span><span class="sy0">;</span>   <span class="kw1">if</span> <span class="br0">(</span><span class="br0">(</span>questState <span class="sy0">&</span> checkState<span class="br0">)</span> <span class="sy0">==</span> checkState<span class="br0">)</span> <span class="br0">{</span> <span class="co1">// all quests completed</span> <span class="br0">}</span> </pre><p> </p> <p> &lt;note important>Do not confuse binary logical operators (<code>|</code>, <code>&</code>, and <code>^</code>), which return a <em>number</em> as a result, with their boolean equivalents (<code>||</code>, <code>&&</code>, and <code>^^</code>), which return a <em>boolean value</em> (either <code>true</code> or <code>false</code>).&lt;/note> </p> </div>