TiMan: Add a sourced SOMA guide with explanations and stock-script examples.

2026-10-02T12:05:50Z

Add a sourced SOMA guide with explanations and stock-script examples.

New page

{{shortPageTitle}}

The Game helper file in SOMA is <code>script/helpers/helper_game.hps</code>.

Saving, checkpoint and achievement helpers connect map scripts to the corresponding game handlers. A checkpoint supplies the state to reload after the player dies; its optional callback receives the death count and death source.

== Before you start ==
# Open the map script inside your own mod. Keep its generated includes, <code>cScrMap : iScrMap</code> class and callback structure. See [[HPL3/SOMA/Getting Started/Add Your First Script|Add your first script]] if you have not edited a map script yet.
# Add the helper include shown below alongside the script’s other includes.
# Read the stock example before copying its calls: named entities, voice subjects, materials and callbacks must belong to the map or resources you are using.

== Follow the stock example ==
<syntaxhighlight lang="cpp">
#include "helpers/helper_game.hps"
</syntaxhighlight>

=== Game_AutoSave ===
Saves the current position of the game.

In <code>maps/chapter05/05_01_phi_inside/05_01_phi_inside.hps</code>, SOMA calls <code>Game_AutoSave</code> as follows.

<syntaxhighlight lang="cpp">
Game_AutoSave();
</syntaxhighlight>

This is an excerpt from that stock script; its referenced names and variables belong to that script.

=== CheckPoint_Setup ===
Sets a checkpoint for the player. If the player dies the game will be reloaded to the state it was when this was called.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asCallback</code> || Function called after player has died and just before he starts again. Syntax: void F(int alNumDeathsAtCheckPoint, const tString&in asDeathSource)
|}

In <code>maps/chapter04/04_03_tau_escape/04_03_tau_escape.hps</code>, SOMA calls <code>CheckPoint_Setup</code> as follows.

<syntaxhighlight lang="cpp">
CheckPoint_Setup();
</syntaxhighlight>

This is an excerpt from that stock script; its referenced names and variables belong to that script.

== Check your change ==
Save the script and restart the map in development mode with <code>F5</code>. If the script fails, open <code>F1</code> and use '''Show Error List''' or '''Show HPL Log'''. See [[HPL3/SOMA/Getting Started/Test Debug and Continue|the development loop]] for the launch and debugging steps.

== Read the example ==
The checkpoint callback signature is <code>void F(int alNumDeathsAtCheckPoint, const tString&in asDeathSource)</code>. Its string parameter is the death source; it is not a timer name. <code>Game_AutoSave</code> forwards its checkpoint and delayed-save flags to the save handler.

== See also ==
* [[HPL3/SOMA/Scripting|SOMA scripting]]
* [[HPL3/SOMA/Scripting/Scripting Api|SOMA scripting API]]

[[Category:English]]

HPL3/SOMA/Scripting/Game Helper - Revision history

TiMan: Add a sourced SOMA guide with explanations and stock-script examples.