Frictional Game Wiki

<h1>Custom User Modules</h1> <div class="level1"> <p> This is a tutorial that aims to teach you, the prospective HPL3 modder, on how to use a user module. It assumes that you have a general grasp of programming in AngelScript and are more or less comfortable with HPL3's scripting process. Basically, by the time you start this tutorial, you should already have some map scripting experience under your belt. </p> </div> <h2>What is a User Module?</h2> <div class="level2"> <p> A user module is basically a self-contained bundle of code that is active at all times. This is contrary to a map script that is only active when that particular map is loaded. </p> <p> Many of the systems you see in SOMA are handled with the use of user modules (which I am going to hence forth just shorten to "modules"). Default player behavior, the game over screen, the main game menu, and even the credits are all controlled with modules. You can check out the <a href="/doku.php?id=hpl3:game:scripting:user_modules" class="wikilink1" title="hpl3:game:scripting:user_modules">User Module Page</a> for a more complete list on the existing modules that come default with the game. </p> <p> In addition to containing behavior and storing data that persists across maps, you can also use a module to draw graphics and widgets using ImGui directly onto the player's view, much like you can onto a terminal entity. You can even have the cursor appear for an interactive experience right on the screen. </p> <p> As you can guess, modules can be used for a variety of things that cannot be done with a map script alone. These can be such cases like: </p> <ul> <li class="level1"> A global inventory system</li> <li class="level1"> An oxygen monitoring system</li> <li class="level1"> A secret message viewer</li> <li class="level1"> Contextual visuals and sounds</li> <li class="level1"> An AI-like monitoring system (think Left 4 Dead's AI Director)</li> </ul> </div> <h2>Getting Started</h2> <div class="level2"> <p> The first thing you need when creating a module is the script file itself. The script file is named using the convention "——Handler.hps". Module scripts consist of a primary class, with the naming scheme of "cScr——Module" that inherits from <code>iScrUserModule</code> and <code>iScrUserModule_Interface</code>. In addition, you must include both <code>"interfaces/UserModule_Interface.hps"</code> and <code>"modules/ModuleInterfaces.hps"</code>. There are a number of built-in functions, and while not all of them are required to exist in your script, it's generally a good idea to have them in there just in case. </p> <p> You can save the file more or less wherever you want (as long as the place is added to your resources.cfg), but the convention used by SOMA is to store module code files in a "modules" folder that is inside the "script" folder. </p> <p> As a baseline, you can copy the following code: </p> <pre class="code c++"><span class="co2">#include "interfaces/UserModule_Interface.hps"</span> <span class="co2">#include "modules/ModuleInterfaces.hps"</span>   class cScrBaseHandler <span class="sy0">:</span> iScrUserModule<span class="sy0">,</span> iScrUserModule_Interface <span class="br0">{</span> <span class="co1">//////////////////////////////////////////////////////////////////////////////////////////</span> <span class="co1">// ==============</span> <span class="co1">// MAIN CALLBACKS</span> <span class="co1">// ==============</span> <span class="co1">//{///////////////////////////////////////////////////////////////////////////////////////</span>   <span class="co1">//-------------------------------------------------------</span>   <span class="kw4">void</span> Init<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> Update<span class="br0">(</span><span class="kw4">float</span> afTimeStep<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> PostUpdate<span class="br0">(</span><span class="kw4">float</span> afTimeStep<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> VariableUpdate<span class="br0">(</span><span class="kw4">float</span> afDeltaTime<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> Reset<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnDraw<span class="br0">(</span><span class="kw4">float</span> afFrameTime<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnPostRender<span class="br0">(</span><span class="kw4">float</span> afFrameTime<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> LoadUserConfig<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> SaveUserConfig<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnMapEnter<span class="br0">(</span>cLuxMap @apMap<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnMapLeave<span class="br0">(</span>cLuxMap @apMap<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> CreateWorldEntities<span class="br0">(</span>cLuxMap @apMap<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> DestroyWorldEntities<span class="br0">(</span>cLuxMap @apMap<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> PreloadData<span class="br0">(</span>cLuxMap @apMap<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnEnterContainer<span class="br0">(</span><span class="kw4">const</span> tString<span class="sy0">&</span>in asOldContainer<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnLeaveContainer<span class="br0">(</span><span class="kw4">const</span> tString<span class="sy0">&</span>in asNewContainer<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnExitPressed<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnAction<span class="br0">(</span><span class="kw4">int</span> alAction<span class="sy0">,</span> bool abPressed<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> OnAnalogInput<span class="br0">(</span><span class="kw4">int</span> alAnalogId<span class="sy0">,</span> <span class="kw4">const</span> cVector3f <span class="sy0">&</span>in avAmount<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> AppGotInputFocus<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span> <span class="kw4">void</span> AppLostInputFocus<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span>   <span class="co1">//-------------------------------------------------------</span>   <span class="co1">//} END MAIN CALLBACKS</span>   <span class="co1">//////////////////////////////////////////////////////////////////////////////////////////</span> <span class="co1">// ================</span> <span class="co1">// GLOBAL FUNCTIONS</span> <span class="co1">// ================</span> <span class="co1">//{///////////////////////////////////////////////////////////////////////////////////////</span>   <span class="co1">//-------------------------------------------------------</span>   <span class="co1">//-------------------------------------------------------</span>   <span class="co1">//} END GLOBAL FUNCTIONS</span>   <span class="co1">//////////////////////////////////////////////////////////////////////////////////////////</span> <span class="co1">// =============</span> <span class="co1">// GUI CALLBACKS</span> <span class="co1">// =============</span> <span class="co1">//{///////////////////////////////////////////////////////////////////////////////////////</span>   <span class="co1">//-------------------------------------------------------</span>   <span class="kw4">void</span> OnGui<span class="br0">(</span><span class="kw4">float</span> afTimeStep<span class="br0">)</span> <span class="br0">{</span><span class="br0">}</span>   <span class="co1">//-------------------------------------------------------</span>   <span class="co1">//} END GUI CALLBACKS</span> <span class="br0">}</span> </pre><p> </p> <p> Next, you need to add your module to your mod's "Modules.cfg" file. That file is an XML file that lists every module loaded when the game starts. (If your mod doesn't have a "Modules.xml" file, you can copy the one from SOMA's config folder to use as a starting point.) </p> <p> There are several attributes that need to be set for your module's entry. An entry looks like this: </p> <pre class="code xml">< Module Name = "MenuHandler" ScriptFile = "modules/MenuHandler.hps" ScriptClass = "cScrMenuHandler" ID = "13" IsGlobal = "false" Container = "Default" UseInputCallbacks = "true" /> </pre><p> </p> <ul> <li class="level1"> <b>Name:</b> The name of the module. This name will be used in various places of a script to call functions within your module.</li> <li class="level1"> <b>ScriptFile:</b> The path/name of the script file for your module.</li> <li class="level1"> <b>ScriptClass:</b> The name of the class for your module script.</li> <li class="level1"> <b>ID</b>: The ID of the module for the in-engine module list. This ID must be unique and should be sequential among every declared module. (0-19 is used by SOMA's built-in modules, so I recommend that any custom modules start at 20.)</li> <li class="level1"> <b>IsGlobal:</b> <em>&lt;Unknown effect>*</em></li> <li class="level1"> <b>Container:</b> <em>&lt;Unknown effect>*</em></li> <li class="level1"> <b>UseInputCallbacks:</b> Whether the game's input actions should be rerouted to the module's <code>OnAction</code> function. (If false, the <code>OnAction</code> function will never get called.)</li> </ul> <p> _{<em>* The IsGlobal and Container attributes are unknown in what effect they have on the module, but every default SOMA module uses the same value for both of them - "false" and "Default", respectively.</em>} </p> </div> <h2>Scripting</h2> <div class="level2"> <p> There are four general categories of of modules that you can make: Always-On, Toggled, Heads Up Display, and Input-Based. Many modules will fall into one or more of these categories, but I'll boil the basics of each one, and how they are generally handled. </p> </div> <h3>Always-On</h3> <div class="level3"> <p> As you may have guessed, these modules are always running. Whether that means they are always monitoring something, or always playing a sound, or always draws something to the screen. The <code>PlayerToolHandler</code> module is a good example of this, as it is constantly checking if the player is looking at an entity that can be interacted with. </p> <p> The Always-On modules make heavy use of the <code>Update</code> function. This function runs on every frame, so anything you do that needs to be updated constantly can be placed in this function. It looks like this: </p> <pre class="code c++"><span class="kw4">void</span> Update<span class="br0">(</span><span class="kw4">float</span> afTimeStep<span class="br0">)</span> <span class="br0">{</span>   <span class="br0">}</span> </pre><p> </p> <ul> <li class="level1"> <b>afTimeStep:</b> The amount of time in seconds that have passed since the last time Update was called.</li> </ul> </div> <h3>Toggled</h3> <div class="level3"> <p> The Toggled modules are modules that run continuously like Always-On modules, but they are turned on and off at different times. They can be toggled manually via a script, or it can be a condition that is met or unmet that the module checks through use of the <code>Update</code> function. The <code>PlayerHandsHandler</code> does this a lot, as it is only activated when something happens that causes the player's hand models to become visible. </p> <p> Like the Always-On modules, the Toggled modules generally make use of the <code>Update</code> function, but they are also heavily affected by the use of global functions (discussed below) that other scripts can call in order to toggle the module on or off, or to hand it important information. </p> </div> <h3>Heads Up Display</h3> <div class="level3"> <p> Heads Up Displays differ from other modules in that they draw information onto the screen, and optionally allows for interaction. As the name suggests, this screen layer is called the heads-up display, or the HUD. <code>MenuHandler</code> is a great example of this; as the module responsible for displaying the title and pause menus, it makes ample use of graphics and interactivity. </p> <p> The bulk of the work in Heads Up Display modules take place in the <code>OnGui</code> function. This function will look familiar, as it's identical to the <code>OnGui</code> functions that are used for terminals: </p> <pre class="code c++"><span class="kw4">void</span> OnGui<span class="br0">(</span><span class="kw4">float</span> afTimeStep<span class="br0">)</span> <span class="br0">{</span>   <span class="br0">}</span> </pre><p> </p> <ul> <li class="level1"> <b>afTimeStep:</b> The amount of time in seconds that have passed since the last time OnGui was called.</li> </ul> </div> <h3>Input-Based</h3> <div class="level3"> <p> Input-Based modules are modules that derive much of their function as a direct response to player actions. Actions are just the mapped keys that the player could press, such as jump, walk, or interact. <code>InventoryHandler</code>, though a small module, makes use of player input in order to display the player's inventory. </p> <p> Input-Based modules make use of the <code>OnAction</code> function to capture and respond to player input. (Since it uses that function, if you make an Input-Based module, you will need to set the "UseInputCallbacks" attribute in the "Modules.cfg" to <em>true</em>.) </p> <pre class="code c++"><span class="kw4">void</span> OnAction<span class="br0">(</span><span class="kw4">int</span> alAction<span class="sy0">,</span> bool abPressed<span class="br0">)</span> <span class="br0">{</span>   <span class="br0">}</span> </pre><p> </p> <ul> <li class="level1"> <b>alAction:</b> An integer that represents what action was fired. Check against various <code>eAction</code> values (such as <code>eAction_Interact</code>).</li> <li class="level1"> <b>abPressed:</b> Whether the action is the result of a button/key getting pressed (<em>true</em>) or released (<em>false</em>).</li> </ul> <p> <em>(When making an Input-Based module, you can also use the OnAnalogInput function to receive player actions from controllers.)</em> </p> </div> <h2>Global Functions</h2> <div class="level2"> <p> Many times when you create a module, you want to be able to interact with or control the module from elsewhere in your mod. In cases like this, you are going to want to create a few functions that are designed to interoperate with external scripts. These functions are the global functions. </p> <p> You can make the global functions do whatever you want, but their use has to follow a few rules. The first is strict - the function has to have no parameters, and it has to have a return value of void. The second is less important, but still recommended - the function name should have the naming convention of _ckgedit_QUOT<u>Global_———". A global function can look like this: <code c++>void _Global_DoSomeWork() { } </code> <span class='np_break'> </span> Now you might notice that, since the function must return nothing and have no parameters, there is no obvious way to pass information in or get information out of these functions. For this purpose, HPL3 has a series of <code>cScript_X</code> functions. These functions fall into a number of classes: * <b>GetGlobalVarX/SetGlobalVarX:</b> Gets or sets a value for a global variable. * <b>GetGlobalArgX/SetGlobalArgX:</b> Gets or sets an argument (parameter) for a global function call. * <b>GetGlobalReturnX/SetGlobalReturnX:</b> Gets or sets a return value for a global function call. Since the "GlobalArg" and "GlobalReturn" families of functions deal primarily with global function use, they will be the ones that you use the most. The "GlobalVar" family of functions are better suited for manipulating global variables, you won't necessarily be using them much with global functions. In addition to knowing the families, you should also know about the types you are able to work with. These types will replace the "X" in the above family names: * String * Bool * Int * ID * Float * Vector2f * Vector3f * Vector4f * Matrix * Color The last piece of these functions are the parameters. The parameters are as follows: * <b>GetGlobalArgX:</b> (int alIdx) * <b>alIdx:</b> The index of the global argument to retrieve. * <b>SetGlobalArgX:</b> (int alIdx, X aX) * <b>alIdx:</b> The index of the global argument to set. * <b>aX:</b> The value to store as an argument. (The type will depend on which type of function you are using.) * <b>GetGlobalReturnX:</b> () * <em>No parameters</em> * <b>SetGlobalReturnX:</b> (X aX) * <b>aX:</b> The value to store as a return value. (The type will depend on which type of function you are using.) The "GlobalArg" functions deal with an index. This index mirrors which position you are trying to reference (i.e. first argument, second argument, third argument, etc.). The "GlobalReturn" functions don't require an index, as they only need to deal with the one return value. Now that you know all the pieces, you know how these functions are structured. The complete signature of a script function is <code>cScript_FunctionNameFunctionType(Parameters)</code>. For example, the signature for setting a string argument is <code>cScript_SetGlobalArgInt(0, "string")</code>. Now, we've reached this point where we can pass information to and from the global functions, but we still need a way to actually call the function. This is done with one additional "cScript" function: <code c++>cScript_RunGlobalFunc(tString asObjName, tString asClassName, tString asFuncName) </code> <span class='np_break'> </span> * <b>asObjName:</b> The name of the module for which to execute the function. (The name that you gave in the "Modules.cfg" file.) * <b>asClassName:</b> The name of the class object to call the function on. (Pass _ckgedit_QUOT</u>ckgedit> to use the default module loaded by the game.) </p> <ul> <li class="level1"> <b>asFuncName:</b> The name of the function to call.</li> </ul> <p> Now that we've got all these parts, I can show you an example of how to use them in practice: </p> <p> <em>(In your map script)</em> </p> <pre class="code c++"><span class="kw4">void</span> DoSomeWork<span class="br0">(</span><span class="kw4">int</span> alSomeInt<span class="sy0">,</span> tString asSomeString<span class="br0">)</span> <span class="br0">{</span> cScript_SetGlobalArgInt<span class="br0">(</span><span class="nu0">0</span><span class="sy0">,</span> alSomeInt<span class="br0">)</span><span class="sy0">;</span> cScript_SetGlobalArgString<span class="br0">(</span><span class="nu0">1</span><span class="sy0">,</span> asSomeString<span class="br0">)</span><span class="sy0">;</span> cScript_RunGlobalFunc<span class="br0">(</span>"SomeHandler"<span class="sy0">,</span> ""<span class="sy0">,</span> "_Global_DoSomeWork"<span class="br0">)</span><span class="sy0">;</span>   bool abResult <span class="sy0">=</span> cScript_GetGlobalResultBool<span class="br0">(</span><span class="br0">)</span><span class="sy0">;</span>   <span class="co1">// Do some nonsense with the result</span> <span class="br0">}</span> </pre><p> </p> <p> <em>(In your module script)</em> </p> <pre class="code c++"><span class="kw4">void</span> _Global_DoSomeWork<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> <span class="kw4">int</span> lSomeInt <span class="sy0">=</span> cScript_GetGlobalArgInt<span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span><span class="sy0">;</span> string sSomeString <span class="sy0">=</span> cScript_GetGlobalArgString<span class="br0">(</span><span class="nu0">1</span><span class="br0">)</span><span class="sy0">;</span>   <span class="co1">// Do whatever module wizardry here...</span>   cScript_SetGlobalReturnBool<span class="br0">(</span><span class="kw2">true</span><span class="br0">)</span><span class="sy0">;</span> <span class="br0">}</span> </pre><p> </p> <p> So the process of this script is as follows. In the map script, it sets the global arguments at indices 0 and 1 to an integer and string value, respectively. It then launches the function <code>_Global_DoSomeWork</code> from the module <code>SomeHandler</code>. In the function, the module retrieves the arguments that the map script set and does… whatever… with them. Once the work is done, the module assigns the return value to a boolean value and exits. Back in the map script, the return value is retrieved, and the map script continues. </p> </div> <h2>Helper Script</h2> <div class="level2"> <p> In the previous section, I covered how you can use global functions in your map script to call functions set in your modules. In practice, you generally don't want to call the "cScript" functions directly from within your map scripts - the script is bulky and verbose, not to mention difficult to easily read and understand. Also, if it's a module function you will need to call multiple times, it's cumbersome to maintain that bulky code in more than one place. Instead, what you'll want to do is create another script file that handles all the heavy lifting and provides an easy-to-understand interface between the map script and the module. </p> <p> While a helper script necessitates creating a new script file, the good news is the only measure you need to take is to make sure the script loaded via the "resources.cfg" file. There are no classes or includes that you need to add to the script file (other than the ones you need depending on what you're trying to do). In fact, the only things you need to do is add the functions themselves to the script file. A couple convention things to keep in mind is that the files typically go in a "script/helpers" folder and take the name "helper_——.hps", and the functions themselves generally take the name of <code>ModuleName_FunctionName</code>. </p> <p> To take the example from the previous section, you might set up the helper script like so: </p> <p> <em>(In your helper script)</em> </p> <pre class="code c++">bool SomeModule_DoSomeWork<span class="br0">(</span><span class="kw4">int</span> alSomeString<span class="sy0">,</span> tString asSomeString<span class="br0">)</span> <span class="br0">{</span> cScript_SetGlobalArgInt<span class="br0">(</span><span class="nu0">0</span><span class="sy0">,</span> alSomeInt<span class="br0">)</span><span class="sy0">;</span> cScript_SetGlobalArgString<span class="br0">(</span><span class="nu0">1</span><span class="sy0">,</span> asSomeString<span class="br0">)</span><span class="sy0">;</span> cScript_RunGlobalFunc<span class="br0">(</span>"SomeHandler"<span class="sy0">,</span> ""<span class="sy0">,</span> "_Global_DoSomeWork"<span class="br0">)</span><span class="sy0">;</span>   <span class="kw1">return</span> cScript_GetGlobalResultBool<span class="br0">(</span><span class="br0">)</span><span class="sy0">;</span> <span class="br0">}</span> </pre><p> </p> <p> As you can see, the logic is generally the same from the map script from the previous example - it takes the parameters and passes them as arguments to the global function, then takes what the global function returns and passes it along to whatever script called the helper. Speaking of which, your map script should now look like this: </p> <p> <em>(In your map script)</em> </p> <pre class="code c++"><span class="co1">// Make sure to include the helper script file</span> <span class="co2">#include "helpers/helper_somehandler"</span>   <span class="kw4">void</span> DoSomeWork<span class="br0">(</span><span class="kw4">int</span> alSomeInt<span class="sy0">,</span> tString asSomeString<span class="br0">)</span> <span class="br0">{</span> bool abResult <span class="sy0">=</span> SomeModule_DoSomeWork<span class="br0">(</span>alSomeInt<span class="sy0">,</span> asSomeString<span class="br0">)</span><span class="sy0">;</span>   <span class="co1">// Do some nonsense with the result</span> <span class="br0">}</span> </pre><p> </p> </div> <h2>Conclusion</h2> <div class="level2"> <p> That's pretty much it for the general explanation of modules. The rest is entirely dependent on what kind of module you want to write. </p> </div>