HPL3/Scripting/Scripting Guide/Helper Files

This article explains what helper files are and how to use them.

Introduction

When you're writing your script, you can find yourself ending up with a lot of code. If all this code is inside a single file, that can make things difficult to manage - whenever you want to add or change something, you have to pour through hundreds or thousands of lines of code looking for that one spot.

Also, what if you want to use some code that was written by someone else? Do you just copy their code and paste it into your own? What if they update their code, forcing you to find everywhere in your code that was updated and perform the update yourself?

There is an easier way. There's a special keyword that references a script file and “pastes” it on top of another file. This allows functions and other things to be called from that other file without requiring that the code is in the same place - the #include keyword.

Workflow

As the name suggests, we include external script files in our code, which allows us to call other functions from other files. There are several includes at the top of our map script file. Each include points to another script file, which are labeled as helpers, because they help us with performing common scripts and actions.

For example, if we want to use player related functions, we need to include helper_player.hps:

#include "interfaces/Map_Interface.hps"
#include "base/Inputhandler_Types.hps"

#include "helpers/helper_map.hps"
#include "helpers/helper_props.hps"
#include "helpers/helper_effects.hps"
#include "helpers/helper_audio.hps"
#include "helpers/helper_imgui.hps"
#include "helpers/helper_sequences.hps"
#include "helpers/helper_game.hps"
#include "helpers/helper_modules.hps"
#include "helpers/helper_ai.hps"

// Required helper file for player related functions
#include "helpers/helper_player.hps"

//...Somewhere in your code:

////////////////////////////
// Run first time starting map
void OnStart()
{
	Player_SetMoveSpeedMul(5.0f); // Here we use a function from the player helper file. 
}

As you can see, the helper file helper_player.hps is included in the script file. If this file wasn't included, the game will display an error message and our map won't run.

Creating Helper Files

You can create custom helper files for your mod in addition to using the game helper files:

1. In your mod folder create a scripts folder.
2. Inside that folder, create a helpers folder.
3. Inside that folder, create a file called MyHelper.hps (Or any other name).
4. Add /script to the mod's resources.cfg file, so the game will search for script files in that folder.

Your mod folder structure may look like this now:

MinimalCustomMapMod/
├── config/
│   ├── lang/
│   │   ├── english.lang
│   ├── main_init.cfg
├── maps/
├── script/
│   ├── helpers/
│       ├── MyHelper.hps
├── entry.hpc
├── resources.cfg

This is how your resources file may look like:

<Resources>
	<Directory Path="/config" AddSubDirs="true" />
	<Directory Path="/maps" AddSubDirs="true" />
	<Directory Path="/script" AddSubDirs="true" />
</Resources>

Now we need to fill our helper file with a custom function. Paste the following code:

#include "helpers/helper_player.hps"

/**
 * Sends the player to the clouds.
 */
void MyHelper_MakeThePlayerJumpVeryHigh()
{
	Player_AddBodyForce(cVector3f(0, 50000, 0), true);
}

Using Helper Files

In our map script file, make sure to #include our helper files:

#include "helpers/MyHelper.hps"

Paste the following line of code inside OnStart:

MyHelper_MakeThePlayerJumpVeryHigh(); // This calls the function from the helper file.

Now just run the game and see the result.

Summary

• We created a new helper files under the scripts -> helpers folder.
• We added our own function to the helper file which makes the player jump very high.
• We included our helper file in the map script file, and called the function from the helper file which will be called after the map is loaded.

See Also

• Include Files - AngelScript
• Resource Configuration - Modding

---

HPL3 Scripting Guide

← Calling Functions and Function Callbacks

The OnAction method →