Difference between revisions of "Hpl2:Tutorials:script:localandglobalvariables"

From Frictional Wiki
Jump to navigation Jump to search
(Blurb test)
(Structuring)
 
Line 1: Line 1:
 
A variable is letter or word used to represent a value that can be altered in code. Variables are used in script to represent a certain value (e.g. a number) so that it can be changed by the game, instead of putting a set value in the script. An example of a variable would be a counter for collected items, which increases each time an item is picked up.
 
A variable is letter or word used to represent a value that can be altered in code. Variables are used in script to represent a certain value (e.g. a number) so that it can be changed by the game, instead of putting a set value in the script. An example of a variable would be a counter for collected items, which increases each time an item is picked up.
  
=Variables=
+
==Data types==
  
The main types of variables are bool, string, int, and float. Bool (boolean) is when the variable can only be true or false. A string is a group of signs, so it can be a letter, a word, or a phrase. Int is an integer (whole number). Float is a number with a decimal (can also be a whole number). Examples:<syntaxhighlight lang="cpp">
+
The main types of variables are bool, string, int, and float. These data types are also referred to as "primitives".
 +
 
 +
* bool (boolean) is when the variable can only be true or false.  
 +
* string is a group of signs, so it can be a letter, a word, or a phrase.  
 +
* int is an integer (whole number).  
 +
* float is a number with a decimal (can also be a whole number).  
 +
 
 +
Examples:<syntaxhighlight lang="cpp">
 
int x = 1;
 
int x = 1;
 
int k = 73;
 
int k = 73;
Line 14: Line 21:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==Local and Global Variables==
+
===Local and global - variable scope===
  
 
Local and global variables are variables that have a certain scope compared to the script in which it is located in.  
 
Local and global variables are variables that have a certain scope compared to the script in which it is located in.  
Line 47: Line 54:
 
   //global variables can be used in any function
 
   //global variables can be used in any function
 
}
 
}
</syntaxhighlight><blockquote>
+
</syntaxhighlight>
'''WARNING:''' ''The regular variables (as described above) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the following:''</blockquote>
+
 
HPL also has wrappers for all those types (except the boolean; instead, the devs just used an integer). Those are the LocalVar- and GlobalVar- types. Their scope is different than the traditional scope used in programming (described above). Their values are also saved in the game progress save files.
+
=== Usage ===
 +
<blockquote>'''WARNING:'''''The primitive variables (as described above) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save.'' </blockquote>In HPL, primitives should only be used for disposable values and counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers, which are described below.
 +
 
 +
== Variable wrappers - LocalVar and GlobalVar ==
 +
HPL has wrappers for most primitives (except the boolean; instead, the devs just used an integer with values 0 and 1). Those are the LocalVar- and GlobalVar- types. Their scope is different than the traditional scope used in programming (described above). Their values are also saved in the game progress save files.
  
A LocalVar's scope is the entire script, so if you made a LocalVar, then you wouldn't have to worry about having to carry it over from function to function. A GlobalVar can be used in a similar manner in many maps.
+
A LocalVar's scope is the entire script, so if you made a LocalVar, then you wouldn't have to worry about having to carry it over from function to function. A GlobalVar can be used in a similar manner in many maps, rather than a single one.
  
 
Here is an excerpt from the [[Hpl2:Amnesia:script functions|Script Functions]] page about the variable wrappers:
 
Here is an excerpt from the [[Hpl2:Amnesia:script functions|Script Functions]] page about the variable wrappers:
Line 97: Line 108:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The Set-Var- is used to set the variable's value. The Add-Var- is used to add the given number or letter(s) to the value of the existing variable. The GetVar is used when checking the value of the variable.
+
The Set functions are used to set the variable's value. The Add functions are used to add the given number or letter(s) to the value of the existing variable. The Get functions are used when checking the value of the variable.
  
 +
=== Usage ===
 
The variable wrappers are mostly used to check if the player has done certain things within the map or the entire game. Such things are often:
 
The variable wrappers are mostly used to check if the player has done certain things within the map or the entire game. Such things are often:
  
Line 131: Line 143:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
GlobalVars are used in a similar manner, but, as mentioned earlier, will work in several map scripts.
+
GlobalVars are used in a similar manner, but, as mentioned earlier, will save its value between several map scripts.
  
  
 
'''This wiki entry has been made by Kyle S. If you have any comments or need help with this, send me a private message on the Frictional Games Forum (My name on there is Kyle). Redux by Darkfire'''
 
'''This wiki entry has been made by Kyle S. If you have any comments or need help with this, send me a private message on the Frictional Games Forum (My name on there is Kyle). Redux by Darkfire'''

Latest revision as of 18:49, 14 July 2020

A variable is letter or word used to represent a value that can be altered in code. Variables are used in script to represent a certain value (e.g. a number) so that it can be changed by the game, instead of putting a set value in the script. An example of a variable would be a counter for collected items, which increases each time an item is picked up.

Data types

The main types of variables are bool, string, int, and float. These data types are also referred to as "primitives".

  • bool (boolean) is when the variable can only be true or false.
  • string is a group of signs, so it can be a letter, a word, or a phrase.
  • int is an integer (whole number).
  • float is a number with a decimal (can also be a whole number).

Examples:

int x = 1;
int k = 73;
float r = 5;
float pi = 3.1415;
bool tf = false;
bool w = true;
string h = "h";
string aa = "lava";

Local and global - variable scope

Local and global variables are variables that have a certain scope compared to the script in which it is located in.

There are certain levels of scope to a script, there is the function's scope, then there is the local scope, then there is the global scope. A function's scope consists of everything within its braces ({ }), except for global variables, which are put outside any braces; those are usually kept at the top of the file. Normal variables as shown above will only work in a function unless carried over to another function or unless they are a global variable. Here's an example:

//Keep in mind that this code is partially incorrect for educational purposes

int global = 4; //A declaration of a global variable

void OnStart()
{
   int local = 2; //A declaration of a local variable
   local = global; //The function can see the global variable; this is valid
   if(global > 2)
   {
      local = local + 1; //This variable was declared in the broader scope, so this is valid
      int new_local = 7; //Another local variable
   }
  local = global + new_local; //new_local was declared in a previously closed scope, so it's invalid
  MyFuncA();
  MyFuncB(local);
}

void MyFuncA()
{
   local = local + 3; //Local was declared in a different scope, so this is invalid
}

void MyFuncB(int argument)
{
   global = argument + 3; //The value of local was passed as the argument, so it can be accessed
   //global variables can be used in any function
}

Usage

WARNING:The primitive variables (as described above) are not saved by the game. Using them in important parts of yor script will break it upon loading a game save.

In HPL, primitives should only be used for disposable values and counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers, which are described below.

Variable wrappers - LocalVar and GlobalVar

HPL has wrappers for most primitives (except the boolean; instead, the devs just used an integer with values 0 and 1). Those are the LocalVar- and GlobalVar- types. Their scope is different than the traditional scope used in programming (described above). Their values are also saved in the game progress save files.

A LocalVar's scope is the entire script, so if you made a LocalVar, then you wouldn't have to worry about having to carry it over from function to function. A GlobalVar can be used in a similar manner in many maps, rather than a single one.

Here is an excerpt from the Script Functions page about the variable wrappers:

Local

LocalVar can be used throughout the same script file.

Integer:

void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);

Float:

void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);

String:

void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);

Global

Global variables can be used throughout several maps and can be accessed by several script files.

Integer:

void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);

Float:

void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);

String:

void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);

The Set functions are used to set the variable's value. The Add functions are used to add the given number or letter(s) to the value of the existing variable. The Get functions are used when checking the value of the variable.

Usage

The variable wrappers are mostly used to check if the player has done certain things within the map or the entire game. Such things are often:

  • Collecting a set number of objects
  • Doing a certain action a set number of times
  • Done some particular thing

Here is an example usage of a LocalVar integer (LocalVarInt):

void OnStart()
{
	SetLocalVarInt("Var01", 0);
	AddEntityCollideCallback("Player", "ScriptArea_1", "Func01", true, 1);
	SetEntityPlayerInteractCallback("Object_1", "Func02", true, 1);
}
void Func01(string &in asParent, string &in asChild, int alState)
{
	AddLocalVarInt("Var01", 1);
	Func03();
}
void Func02(string &in asEntity)
{
	AddLocalVarInt("Var01", 1);
	Func03();
}
void Func03()
{
	if(GetLocalVarInt("Var01") == 2)
	{		
		AddDebugMessage("Run!", false);
	}	
}

GlobalVars are used in a similar manner, but, as mentioned earlier, will save its value between several map scripts.


This wiki entry has been made by Kyle S. If you have any comments or need help with this, send me a private message on the Frictional Games Forum (My name on there is Kyle). Redux by Darkfire