hpl2:amnesia:script_language_reference_and_guide:funcions_-_part_1
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
hpl2:amnesia:script_language_reference_and_guide:funcions_-_part_1 [2012/12/30 01:25] thegreatcthulhu [Discussion] |
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 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? === | ||
| Line 158: | Line 168: | ||
| 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 === | + | === 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).\\ | 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. | 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//.\\ | + | 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: | + | 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++> | <code c++> | ||
| void OnCollideArea_DramaticEvent(string &in entity1, string &in entity2, int collisionDescription) | void OnCollideArea_DramaticEvent(string &in entity1, string &in entity2, int collisionDescription) | ||
| Line 177: | Line 187: | ||
| // are custom, and are omitted from this snippet. | // are custom, and are omitted from this snippet. | ||
| </code> | </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.) | 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.) | ||
hpl2/amnesia/script_language_reference_and_guide/funcions_-_part_1.1356830714.txt.gz · Last modified: 2012/12/30 01:25 by thegreatcthulhu
