User Tools

Site Tools


hpl2:amnesia:script_language_reference_and_guide:funcions_-_part_1

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
hpl2:amnesia:script_language_reference_and_guide:funcions_-_part_1 [2012/12/29 02:48]
thegreatcthulhu created
hpl2:amnesia:script_language_reference_and_guide:funcions_-_part_1 [2013/01/14 20:16] (current)
thegreatcthulhu Func_ions --> LOL
Line 1: Line 1:
-====== ​Funcions ​- Part 1: The Basics ======+====== ​Functions ​- Part 1: The Basics ======
  
 ---- ----
Line 8: Line 8:
 <code c++>​returnType FunctionName(parameter_list) <code c++>​returnType FunctionName(parameter_list)
 { {
- // function body goes here+    ​// function body goes here
 }</​code>​ }</​code>​
  
Line 22: Line 22:
 bool RandBool() bool RandBool()
 { {
- int temp = RandInt(0, 1); // a call to another function +    ​int temp = RandInt(0, 1);    // a call to another function 
- bool result = (temp == 1); +    bool result = (temp == 1); 
-  +     
- return result; // <--- The RETURN statement+    return result; ​       // <--- The RETURN statement
 } }
  
Line 36: Line 36:
 void SetLampStates(bool lit, bool useFadingEffect) void SetLampStates(bool lit, bool useFadingEffect)
 { {
- SetLampLit("​lamp1",​ lit, useFadingEffect);​ +    ​SetLampLit("​lamp1",​ lit, useFadingEffect);​ 
- SetLampLit("​lamp2",​ lit, useFadingEffect);​ +    SetLampLit("​lamp2",​ lit, useFadingEffect);​ 
- SetLampLit("​lamp3",​ lit, useFadingEffect);​+    SetLampLit("​lamp3",​ lit, useFadingEffect);​
 } }
  
Line 65: Line 65:
 <code c++>​returnType FunctionName(parameter_list) <code c++>​returnType FunctionName(parameter_list)
 { {
- // function body goes here+    ​// function body goes here
 }</​code>​ }</​code>​
  
Line 72: Line 72:
 <code c++>​returnType FunctionName(parameter_list) <code c++>​returnType FunctionName(parameter_list)
 { {
- return return_value;​+    ​return return_value;​
 }</​code>​ }</​code>​
  
Line 95: Line 95:
 float Calculate(float x1, float x2, float offset) float Calculate(float x1, float x2, float offset)
 { {
- return (x1 * (1.0f - offset)) + (x2 * offset);+    ​return (x1 * (1.0f - offset)) + (x2 * offset);
 } }
 </​code>​ </​code>​
Line 101: Line 101:
 This is both the declaration and the definition. Often, when talking about functions, we are not so much interested in what the function does (definition),​ as we are interested in how to //use// the function (which is visible from the declaration.) If we omit the body of the function, we get the //​declaration//​ of the function, which we can show to other people who might need to use it: This is both the declaration and the definition. Often, when talking about functions, we are not so much interested in what the function does (definition),​ as we are interested in how to //use// the function (which is visible from the declaration.) If we omit the body of the function, we get the //​declaration//​ of the function, which we can show to other people who might need to use it:
 <code c++> <code c++>
-float Calculate(float x1, float x2, float offset); // declaration+float Calculate(float x1, float x2, float offset); ​   // declaration
 </​code>​ </​code>​
  
Line 109: Line 109:
  
 If you visit the [[hpl2:​amnesia:​script_functions|Engine Scripts]] page, you'll see that all the predefined functions over there are listed as function declarations. If you visit the [[hpl2:​amnesia:​script_functions|Engine Scripts]] page, you'll see that all the predefined functions over there are listed as function declarations.
 +
 +<note tip>​Function parameters are also called //function arguments//​.</​note>​
  
 === Calling a Function === === Calling a Function ===
Line 153: Line 155:
 float calculationResult = Calculate(min,​ max, RandFloat(0.0f,​ 1.0f)); float calculationResult = Calculate(min,​ max, RandFloat(0.0f,​ 1.0f));
 </​code>​ </​code>​
 +
 +<note tip>
 +**The Scope of Function Parameters**
 +
 +Function parameters are associated with the function body, as if they were variables declared inside it. Thus, function parameters - the variables in the declaration - are local in scope, that is, they are visible (usable) only from within the function itself.
 +
 +When variables are used in a //function call// as input parameters, these input variables, and their names, are external to the function (and are generally not visible to it); it is //the data// they contain that gets passed in, not their names. The data values, upon entering the function they were passed to, //become assigned// to the corresponding names in the parameter list.
 +</​note>​
  
 === Where to Make the Call From? === === Where to Make the Call From? ===
  
 Once defined, a function is visible from the entire script, so it can be called from any other function. It can even call itself - this is called //​recursion//​! Be careful, though. If a function calls itself, it has to have a way to stop doing that, or bad things will happen (more on that in part 2). Similarly, if two functions call each other, this will go on "​forever"​ unless certain preventive measures are taken (more on this also in part 2). Once defined, a function is visible from the entire script, so it can be called from any other function. It can even call itself - this is called //​recursion//​! Be careful, though. If a function calls itself, it has to have a way to stop doing that, or bad things will happen (more on that in part 2). Similarly, if two functions call each other, this will go on "​forever"​ unless certain preventive measures are taken (more on this also in part 2).
 +
 +=== Why Use Functions? ===
 +
 +Generally speaking, it is possible to write a map script that consists only of a single function. However, there are benefits to breaking your code down in several smaller peaces, organized as funcions. What's more, sometimes you don't have a choice, due to the design of the script engine - a script has 3 basic entry points all of which are separate functions (OnStart(), OnEnter() and OnLeave() - see [[hpl2:​amnesia:​script_language_reference_and_guide:​execution_flow|Execution Flow]]). Also, when you use timers, or want to respond to interactions among entities in the game world, you must use //​callbacks//,​ which are functions that are called timer ticks, or object collisions and such, functions that you write yourself (more on this in Part 2).\\
 +So, the HPL2 engine encourages you to split your code into functions anyway.
 +
 +However, the benefit of using functions is that it allows you to organize your code into self-contained functional parts, which are easier to //maintain, debug and reuse//. For example, you'll often need to perform the same set of operations several times, at several places in your script. Without functions, this leads to code duplication,​ difficulties when it comes to making changes, hard-to-track errors, and an ugly looking wall of text. With functions all of this is avoided: duplicated code is elegantly replaced with function calls, which, as you know, can accept context-specific variables. If any changes to the way the function works need to be made, all of the relevant code is //in one place//.\\
 +Provided that functions use descriptive names, the practice also makes your code more readable, and easier to understand. It's a difference between facing a wall of difficult-to-track text, and a short list of descriptive function calls. For example, if I present you with a completely unfamiliar peace of code, you'll probably be able to guess what it does just by examining the names of the functions called, without ever knowing //how// those functions actually work:
 +<code c++>
 +void OnCollideArea_DramaticEvent(string &in entity1, string &in entity2, int collisionDescription)
 +{
 +    SetPlayerActive(false);​
 +    StartPlayerHeadAnimation();​
 +    StartDramaSoundFXsAndMusic();​
 +    RemoveAllItems();​
 +}
 +
 +// SetPlayerActive() is exposed by the game, other functions
 +// are custom, and are omitted from this snippet.
 +</​code>​
 +
 +<note tip>If you haven'​t read Part 2, ignore the strange "&​in"​ qualifiers for now.</​note>​
 +
 +Just by looking, you can tell, judging by the name OnCollideArea_DramaticEvent(),​ that this function is called when the Player collides with a specific script area, and that this function initiates some in-game dramatic event: first it takes control from the player, then it calls another function that animates the camera, and another to start music, and yet another to make the player loose all of the items. (Maybe the ground gave way, and the Player fell into a river! The exact details are not relevant, the important thing is that you can get a pretty good idea of what is the function supposed to do just by looking at it.)
  
 ==== Sandbox Map Exercise ==== ==== Sandbox Map Exercise ====
hpl2/amnesia/script_language_reference_and_guide/funcions_-_part_1.1356749303.txt.gz · Last modified: 2012/12/29 02:48 by thegreatcthulhu