Variables

[FlawlessHappiness]

Variables

I was asked how variables work, and I'm in the mood for creating a little tutorial, so here you are ^_^

(Also, I hope this hasn't already been covered)


1. What is a variable?

Before I start, if there's some clever guy out there, who thinks I'm saying something wrong, do correct me.


In Amnesia we work with 4 different variable-types.

• Integer (Referred to as int)
  
• Float
  
• Boolean (Referred to as bool)
  
• String
  

Integers
Integers are numbers without decimals. Whole numbers.

It's simple:
1 is an int.
1.5 is not an int.

Integers don't often appear in the script-lines used in Amnesia. They use floats instead.

Floats
Floats are the opposite.

Floats are numbers with decimals, but you can still use whole numbers.

1.5 is a float.
1 is also a float, but will (I assume) be seen as 1.0

A line you've probably used is:

PHP Code: (Select All)

FadeOut(float afTime); 


Note that 'float' is for how long it takes for the screen to go black.
You probably only write 1 or 2, but the game will see it as 1.0 or 2.0.

So, in fact, you could actually have the game fade to black in 1.5 seconds.

Booleans
Bools are not numbers, but will either be true or false.

You have probably used the following script-line.

PHP Code: (Select All)

SetPlayerActive(bool abActive); 


Note that 'bool' here refers to either be true or false

Strings
A string is a word. Can consist of letters, but also be numbers.

"Hello" is a string.
"Over9000" is also a string.
"9000" is also a string (I assume). But cannot be transferred into an int or float directly. You'd need something else first.

Maybe you've tried to remove a timer before.

PHP Code: (Select All)

RemoveTimer(string& asName); 


Note that 'string' here refers to the name of a timer.


2. So how do I use a variable?
Good question.

For integers and floats we'll just go through some simple steps.

1. Give the variable a name
   
2. Give the variable a number
   
3. Set it in a script-line
   

When you've thought about the first two steps, lets finish it by doing the third.
In this tutorial name will be "NAME" and number will be 1.

To set a variable

• for ints use
  

PHP Code: (Select All)

SetLocalVarInt("NAME", 1); 


• for floats use
  

PHP Code: (Select All)

SetLocalVarFloat("NAME", 1.0); 


That wasn't so hard, was it?

We can do the same with strings. Just instead of using a number, we will be using a word.

PHP Code: (Select All)

SetLocalVarString("NAME", "WORD"); 


Notice, how this works the exact same way? Awesome!


3. What can I do with them?
For ints and floats, you can do, what numbers do best!
Add, subtract, multiply and divide. It's basic math.

Say you want the int, "NAME", to be 1 higher. You simply write:

PHP Code: (Select All)

AddLocalVarInt("NAME", 1); 


The int, "NAME", is now 2.

To make it 1 lower write:

PHP Code: (Select All)

AddLocalVarInt("NAME", -1); 


The int, "NAME", is now 1, again.

QUESTION: Yea, yea, those are all nice things, but how can I use it in my scripts?

Very good question, indeed!
Let's look at some basic things.

4. Variables and script-lines

What's so awesome about variables is that you can have them stand instead of numbers and words.

Before we start!
I need you to know a thing that we'll be using all the time!

• for ints
  

PHP Code: (Select All)

GetLocalVarInt("NAME") 


• for floats
  

PHP Code: (Select All)

GetLocalVarFloat("NAME") 


These lines are important, as they give all the information.
We use them in, if-statements.

Look at this:

PHP Code: (Select All)

if(GetLocalVarInt("NAME") == 1)
{
//DO SOMETHING
} 


We're simply saying: If the variable, "NAME", is 1, then do something!


Now, this can also be used differently. Instead of asking if the variable, "NAME", is something, we can use it in a script-line.

In this example we'll be using it in SetEntityActive("ENTITY", false);

Look at this:

PHP Code: (Select All)

SetEntityActive("Door_"+GetLocalVarInt("NAME"), false); 


What we're doing here is, where taking the name "Door_" and then we're adding the variable, "NAME", to the name.

If the variable, "NAME", is 1 then the name of the door will be "Door_1".
If the variable, "NAME", is 2 then the name of the door will be "Door_2".

This way you only have to write the line once. Then you can just change the variable, as you like.

I'm just gonna jump right into the first example now. I hope you follow.

1st example
What we're trying to create is that when you touch a script-area it'll show a message.
But when you click on a button, it'll show another message.

TIP: If you haven't specified an int or float, it'll always be 0

PHP Code: (Select All)

void ClickOnArea(string &in asEntity)
{
if(GetLocalVarInt("MessageVariable") == 0) //If variable is 0, show first message
{
SetMessage("Messages", "Message_1", 0);
}

if(GetLocalVarInt("MessageVariable") == 1) //If variable is 1, show second message
{
SetMessage("Messages", "Message_2", 0);
}
}

void ClickOnButton(string &in asEntity)
{
if(GetLocalVarInt("MessageVariable") == 0) //If the variable is 0, set it to 1.
{
SetLocalVarInt("MessageVariable", 1);
}
} 


When you start the script, it should look like this.
https://www.youtube.com/watch?v=59qyY9c0...e=youtu.be

2nd example
For the next example, we'll be using AddLocalVarInt, to keep changing messages, when we have more than 2.

What's gonna happen:
Click on area => Message 1 appears
Click on button.
Click on area => Message 2 appears
Click on button
Click on area => Message 3 appears
...
etc.

the script is almost the same.
It looks like this.

TIP: You can use GetLocalVarInt("NAME"), to make the script look for the number of the variable. It's a great way to make everything easier for you, just like it's written above this

PHP Code: (Select All)

void ClickOnArea(string &in asEntity)
{
SetMessage("Messages", "Message_"+GetLocalVarInt("MessageVariable"), 0);
}

void ClickOnButton(string &in asEntity)
{
AddLocalVarInt("MessageVariable", 1); //This adds 1 to MessageVariable

if(GetLocalVarInt("MessageVariable") == 6) //Check, if the variable is 6. If it is, then set it to 0
{
SetLocalVarInt("MessageVariable", 0);
}
} 


When you start the script, it should look like this:
https://www.youtube.com/watch?v=ILuRnqzS...e=youtu.be

3rd example
Let's go on to the hardcore stuff.

What we want to do, is have a screen-effect go from 0 to a high number, over time.
We will be using timers and variables for this one.
Please, make sure you know about how timers work, before reading further.

How it'll work:
When clicking an area, the timer starts.
Each time the timer calls, the screen effect will increase it's grip on the player.
Here's how the script looks.

PHP Code: (Select All)

void ClickOnArea(string &in asEntity)
{
AddTimer("EffectTimer_1", 1, "EffectTimer");
}

void EffectTimer(string &in asTimer)
{
AddLocalVarInt("ScreenEffectVariable", 1); //Add 1 to the variable

if(GetLocalVarInt("ScreenEffectVariable") == 30) //if the variable is 30, stop!
{
return;
}

FadeImageTrailTo(GetLocalVarFloat("ScreenEffectVariable")/10, 10); 
//Set screen effect to the number of the variable, divided by 10, because we need a small number.

AddTimer("EffectTimer_1", 0.1, "EffectTimer"); //Loop the timer, by calling itself in 0.1 seconds
} 


When you start the script, it should look something like this:
https://www.youtube.com/watch?v=7-yBFa9q...e=youtu.be


Thank you!
For viewing this, so far.

If you have any questions, need me to explain something further, or something else, do ask!

I might not be able to answer everything. But hey, it's always great to ask.

[Mudbill]

I like using booleans in the script, but there are no dedicated functions (like SetLocalVarBool) because it's unnecessary. An int with 0/1 does the same. But bools are still pretty cool.

Now, for a beginner, they probably don't need to worry about it though. Seeing as this is, by the looks of it, a beginners guide to variables, it's fairly good the way you've put it up. On the more technical side, I just wanna mention a few things

There are a few other variables that can be used, such as a Double. They're used just like floats, pretty much, but they have a greater range (not that it's needed in 99% of cases).

Using the primitive versions is often easier (in my opinion).

PHP Code: (Select All)

int intName = 0;
float floatName = 1.0f;
double doubleName = 1.0d;
string stringName = "Hello World";
bool boolName = true; 


So like

PHP Code: (Select All)

int number = 1;
if(number == 1) DoSomething(); 


does the same as

PHP Code: (Select All)

SetLocalVarInt("number", 1);
if(GetLocalVarInt("number") == 1) DoSomething(); 


so it's mostly down to preference. Mind that they don't work interchangeably though.

PHP Code: (Select All)

SetLocalVarInt("number", 1);
if(number == 1) DoSomething(); 


This does not work.

There are more primitives, but the ones above (except the double) are the important ones. They work the same as how you've explained though. Notice the f and d at the end of the float and double values. They simply state that this value is a float or a double. If you do

PHP Code: (Select All)

float f = 1.0; 


Then the game will assume 1.0 is a double, and will therefore convert it to a float. It doesn't really matter since the value was never actually a double, so you won't lose any precision, but it's something to note. It will probably give you a warning in the log file if you do not add the f. The d on the double value is not as important though, since it will already assume it's a double.

Just some extra info for the curious ones

PS: Your (assumptions) seem correct to me.

[FlawlessHappiness]

What is a double?
I've never heard of it ^_^


Also, the primitive way works, yes, but when scripting in HPL it'll only work inside the brackets you're in.

If you suddenly want to use the same variable as you used in a previous function, then you can't because you used the primitive way, which is now erased from the memory of the script.

[Mudbill]

What is a double?
I've never heard of it ^_^


Also, the primitive way works, yes, but when scripting in HPL it'll only work inside the brackets you're in.

If you suddenly want to use the same variable as you used in a previous function, then you can't because you used the primitive way, which is now erased from the memory of the script.

It depends where you declare it. If you add it outside all your blocks, it can be accessed anywhere.

PHP Code: (Select All)

int value = 1;
void OnStart()
{
    int value2 = 2;
    AddDebugMessage("value == " + value, false); //prints 1
    AddDebugMessage("value == " + value2, false); //prints 2
}

void Callback(string &in asParam)
{
    AddDebugMessage("value == " + value, false); //also prints 1
    AddDebugMessage("value == " + value2, false); //crashes because value2 is not found
} 


If the primitive is declared inside a block, the scope only allows it to be used within that block. Once it's finished, it's erased from memory.

I believe the values are static within the file, so changing the value in one block will affect the overall value of the primitive throughout the file. The original value is only initial.

PHP Code: (Select All)

int value = 1;
void OnStart()
{
    value = 2;
    AddDebugMessage("value == " + value, false); //prints 2
}

void Callback(string &in asParam)
{
    AddDebugMessage("value == " + value, false); //still prints 2
    value = 4;
    AddDebugMessage("value == " + value, false); //prints 4
} 


Primitives can also be declared as null (no value). If you know you set the variable to a value before you use it, it can help make the code more stable.

PHP Code: (Select All)

int value; //declared without a value

void Callback(string &in asParam)
{
    if(value == null) return; //checks if variable has no value, and if so, cancels this block.
    value = 4;
    AddDebugMessage("value == " + value, false); //prints 4
} 


Null isn't very important to use in your script as a beginner or even intermediate. I don't think I've used it much myself except no value declarations. Any variable can be assigned null if nothing else is specified. Null is often a crash cause if you expect to get a value. Important to note that null is not the same as 0.

Null isn't directly present in HPL's script variables though. You can probably lure it in there by doing something like

PHP Code: (Select All)

SetLocalVarInt("number", value); 


where value is currently null. But I think I'll stop digging deeper here
Most of this is unnecessary in most cases of HPL scripting.

[Romulator]

"9000" is also a string (I assume).

9000 is a string by itself if declared that way (as a String, not an Integer). A String itself is simply a collection of chars (characters). A char is a single unicode character, and there are over 107,000 of them.

Typically, anything you declare can be declared as a string, but String variables are often used for later referencing in code rather than use in-game. For example, in Justine, a String variable keeps track of which suitor and prisoner is currently in the level and plays the corresponding sound. I would search for the code, but I cannot be bothered The syntax and code example can be found searching for StartCharacterSpeak

[FlawlessHappiness]

Thank you guys ^^
Great clarifications!


I still didn't get an answer to what a double is...

[Romulator]

Thank you guys ^^
Great clarifications!


I still didn't get an answer to what a double is...

In short:
A big float number of an extremely large range, consisting of 64-bit allowance of digits.

In long:

Spoiler below!

A Double is a float, which consists of 64-bit sizing. What that gibberish means is that it can handle a greater range than, for example, a float.

A float, as we know, is a number which allows decimal point usage. The range of a float is between -9,223,372,036,854,775,808 to 9,223,372,036,854,775,808 (including 0). To calculate this, we use (2^x)/2, where x is the suitable data type size in bytes. We divide by two to get the maximum and minimum, as floats allow negative and positive numbers. Without dividing by two, we get the count - that is, 1.8446744e+19 possible numbers.

A double is pretty much the same thing, except it is 2^64 numbers. I cannot calculate that, nor can google, but it is a pretty large range which accepts some pretty big numbers. However, apparently it is 4.94065645841246544e-324d to 1.79769313486231570e+308d digits long as a positive and negative range.

[FlawlessHappiness]

Aha! So it won't matter much whether we use floats or doubles, since we're never gonna get into such specific numbers.

Thank you!