> For the complete documentation index, see [llms.txt](https://guide.cronuszen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.cronuszen.com/gpcscripting/gpc-script-guide/gpc-developer-guide/user-created-functions.md). # User Created Functions As well as having a significant number of built-in functions, GPC allows a user to create their own custom functions. A function can run any code valid in the `main` section and code is also executed in the order it is written. ```gpc main { if(get_val(PS4_CROSS)) { // if PS4 Cross is held if(myfunction(10, 20) == 30) { // if myfunction returns a value of 30 combo_run(mycombo); // run combo mycombo } else if(myfunction(10, 20) == 10) { // if myfunction returns a value of 10 combo_stop(mycombo); // stop mycombo if it is running } } } combo mycombo { set_val(PS4_TRIANGLE, 100); wait(1000); wait(1000); } function myfunction(_1stvalue, _2ndvalue) { // myfunction start if(get_val(PS4_CIRCLE)) { // if PS4 Circle is held return _1stvalue + _2ndvalue; // return _1stvalue plus _2ndvalue } return _1stvalue - _2ndvalue; // return _1stvalue minus _2ndvalue } ``` *** ### Calling a Function ```gpc myfunction(10, 20); ``` To call (or run) a function, you simply type its name and put any parameters it requires in between `(` and `)`. When a function is called, the code within it is executed and the return value is sent back to where it was called from. User functions are what is known as global scope, this means they can be called from the `init`, `main` and `combo` sections. They can even be called from within another function, however, GPC does not support recursive calls of functions. This means a function cannot be called from within itself. *** ### Function Name and Declaration ```gpc function myfunction() {} ``` To declare a function type `function` followed by a name and `()`. Within the parenthesis `()` you place the names of any parameters you would like the function to have, if any. Function names and parameters follow the same rules as a variable, they can start with either an underscore (`_`) or a letter and can be followed by any combination of letters, digits or underscores. #### Syntax ``` function (); ``` #### Parameters | Parameter | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | `` | The name of the function | | `` | Optional parameters. You can use as many as you wish or none at all. Each one must be separated with a comma (`,`) | *** ### Function Parameters ```gpc function myfunction() {} ``` Function parameters can be thought of as local variables as they cannot be accessed outside of the function they are defined within. A value can be passed to them and they can be used within the function just like a variable could. As GPC only supports one data type (16bit integers) you do not need to specify the data type of parameters within a function and the name of a parameter follows the same rules as a function or variable, they can start with either an underscore (`_`) or a letter and can be followed by any combination of letters, digits or underscores. Function parameters are optional. You are not required to have any at all, the example above is perfectly valid. *** ### Returning from a Function `return` is a command unique to functions. It is not mandatory for each user function to have a return value though, if there is no `return` in a function, then 0 (zero) will be automatically returned. You can have multiple return points within a function. Once the first `return` command is executed, the function returns a value to where it was called and the function is terminated. The code beyond that point in the function will not be run. Returning a value is one of the single most useful commands within a function as it can be used as a boolean value to enable or disable sections of code, to set parameters in other functions, or to set a variable to the desired value. In the following example, you will see a couple of uses for the `return` command: ```gpc int rf_hold = 40; int rf_null = 30; main { if(myfunction()) { if(get_val(XB1_RT)) { combo_run(rapid_fire); } } } combo rapid_fire { set_val(XB1_RT, 100); wait(rf_hold); set_val(XB1_RT, 0); wait(rf_null); set_val(XB1_RT, 0); } function myfunction() { if(get_val(XB1_VIEW)) { if(get_val(XB1_A)) rf_hold = adjust_speed(rf_hold, 10, 1000, 10); if(get_val(XB1_B)) rf_null = adjust_speed(rf_null, 10, 1000, 10); set_val(XB1_A, 0); set_val(XB1_B, 0); set_val(XB1_LB, 0); set_val(XB1_RB, 0); set_val(XB1_VIEW, 0); set_val(TRACE_1, rf_hold / 10); set_val(TRACE_2, rf_null / 10); return 0; //return a value of 0 } return 1; //return a value of 1 } function adjust_speed(var, min_value, max_value, adjustment_increment) { if(event_press(XB1_RB) && var < max_value) var = var + adjustment_increment; if(event_press(XB1_LB) && var > min_value) var = var - adjustment_increment; return var; } ``` *** ### Putting it All Together When the GPC script is first loaded, the two variables `rf_hold` and `rf_null` are created with a value of 40 and 30 respectively. The `main` section then starts its first iteration (run). When it gets to the line below the `myfunction()` function is executed: ```gpc if(myfunction()) { ``` The code in `myfunction()` is then run. If `XB1_VIEW` is not being pressed, the code nested in the statement: ```gpc if(get_val(XB1_VIEW)) { //if we get a value from VIEW other than 0 ``` is ignored as the `if` statement is false. So the next line executed in the function is: ```gpc return 1; //if we do not get a value from VIEW, return 1 ``` At which point the value of 1 is returned to the statement: ```gpc if(myfunction()) { ``` Thus making the above statement true and the code: ```gpc if(get_val(XB1_RT)) { //if we get a value from RT / R2 other than 0 combo_run(rapid_fire); //run combo rapid_fire } ``` which is nested within that statement is executed. If RT/R2 is not being pressed, the nested code is ignored and not executed. *** If `XB1_VIEW` and `XB1_A` are both held when `myfunction()` is executed, then the following lines of code are reached and run: ```gpc if(get_val(XB1_A)) rf_hold = adjust_speed(rf_hold, 10, 1000, 10); if(get_val(XB1_B)) rf_null = adjust_speed(rf_null, 10, 1000, 10); set_val(XB1_A, 0); set_val(XB1_B, 0); set_val(XB1_LB, 0); set_val(XB1_RB, 0); set_val(XB1_VIEW, 0); set_val(TRACE_1, rf_hold / 10); set_val(TRACE_2, rf_null / 10); return 0; //return 0 ``` As you can see, if `XB1_A` or `XB1_B` is not also held down, the code sets a few buttons to 0, writes the value of our two variables to trace values, and then most importantly, reaches the line: ```gpc return 0; //return 0 ``` At which point a value of 0 is returned to the statement: ```gpc if(myfunction()) { ``` Making it **false**, so the code: ```gpc if(get_val(XB1_RT)) { //if we get a value from RT / R2 other than 0 combo_run(rapid_fire); //run combo rapid_fire } ``` which is nested within that statement is ignored and not executed. *** If `XB1_VIEW` and `XB1_A` are both held when `myfunction()` is executed, then the following line of code is reached and run: ```gpc rf_hold = adjust_speed(rf_hold, 10, 1000, 10); ``` What the above line means is: the variable `rf_hold` equals the return value of the function `adjust_speed` or you could say the return value from `adjust_speed` is stored in `rf_hold`. So let's take a look at how that function returns a value. As you can see above, four values are being sent to the function `adjust_speed`: the value of `rf_hold`, 10, 1000, and 10. So let's take a look at the declaration of the function `adjust_speed`: ```gpc function adjust_speed(var, min_value, max_value, adjustment_increment) { ``` Function `adjust_speed` requires 4 arguments: the variable to be adjusted, the minimum value you want it to be, the maximum value you wish for it to be and how much to adjust it by each increment. To manipulate the variable, the function executes the following code: ```gpc if(event_press(XB1_RB) && var < max_value) var = var + adjustment_increment; if(event_press(XB1_LB) && var > min_value) var = var - adjustment_increment; return var; ``` In the first part of this code, if `XB1_RB` is pressed and the variable value passed to the function is less than the maximum value allowed, the value passed in the fourth parameter (10 in this case) is added to the value of `var`. The value of `var` is returned to where the function is called — therefore making `rf_hold` equal 10 more than it did before. If `XB1_LB` is pressed and the variable value passed to the function is greater than the minimum value allowed, the value passed in the fourth parameter is subtracted from the value of `var`. The value of `var` is returned to where the function is called, therefore making `rf_hold` equal 10 less than it did before. An identical process is carried out if `XB1_VIEW` and `XB1_B` are pressed when `myfunction()` is executed, with the exception being that `rf_null` is adjusted rather than `rf_hold`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://guide.cronuszen.com/gpcscripting/gpc-script-guide/gpc-developer-guide/user-created-functions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.