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

2026-10-02T12:05:56Z

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

New page

{{shortPageTitle}}

The Map helper file in SOMA is <code>script/helpers/helper_map.hps</code>.

Map helpers control the current world’s settings, timers, entity lookup and map transitions. Timers call a named script function after a delay; the helper documentation specifies that delay in seconds.

== 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_map.hps"
</syntaxhighlight>

=== Map_AddTimer ===
Trigger a callback function in X seconds. The timer is added to the front of a list, so in case there are many timers with the same name, this one will be used for any funcion calls.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || name of the timer that will trigger a callback function.
|-
| <code>afTime</code> || time in seconds for when to trigger the callback function.
|-
| <code>asFunction</code> || name of the callback function. Syntax for callback function, void FunctionName(const tString &in asTimer).
|}

In <code>maps/chapter02/02_01_ms_curie_outside/02_01_ms_curie_outside.hps</code>, SOMA calls <code>Map_AddTimer</code> as follows.

<syntaxhighlight lang="cpp">
Map_AddTimer("", 2, "TimerOpenAirLock");
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asName</code> || <code>""</code>
|-
| <code>afTime</code> || <code>2</code>
|-
| <code>asFunction</code> || <code>"TimerOpenAirLock"</code>
|}

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

=== Map_GetEntity ===
Returns the entity with the given name.

<syntaxhighlight lang="cpp">
iLuxEntity@ Map_GetEntity(const tString &in asName, eLuxEntityType aType = eLuxEntityType_LastEnum, const tString &in asClass = "");
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || the name of the entity.
|-
| <code>aType</code> || (optional), the type of entity (as an enum).
|-
| <code>asClass</code> || (optional), the class of the entity.
|}

In <code>maps/chapter00/00_03_laboratory/00_03_laboratory.hps</code>, SOMA calls <code>Map_GetEntity</code> as follows.

<syntaxhighlight lang="cpp">
iLuxEntity@ pPropEntity = Map_GetEntity("David");
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asName</code> || <code>"David"</code>
|}

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

=== Map_ChangeMap ===
Changes the active map to the one specified.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asMapName</code> || map to change to.
|-
| <code>asStartPos</code> || name of the player start node that the player should begin at.
|-
| <code>asStartSound</code> || sound that plays before loading the map.
|-
| <code>asEndSound</code> || sound that plays as the new map starts.
|}

== 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.

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

[[Category:English]]

HPL3/SOMA/Scripting/Map Helper - Revision history

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