Map Helper

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

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

1. Open the map script inside your own mod. Keep its generated includes, cScrMap : iScrMap class and callback structure. See Add your first script if you have not edited a map script yet.
2. Add the helper include shown below alongside the script’s other includes.
3. 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

#include "helpers/helper_map.hps"

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.

Parameter	Meaning
asName	name of the timer that will trigger a callback function.
afTime	time in seconds for when to trigger the callback function.
asFunction	name of the callback function. Syntax for callback function, void FunctionName(const tString &in asTimer).

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

Map_AddTimer("", 2, "TimerOpenAirLock");

Parameter	Value in this stock call
asName	""
afTime	2
asFunction	"TimerOpenAirLock"

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.

iLuxEntity@ Map_GetEntity(const tString &in asName, eLuxEntityType aType = eLuxEntityType_LastEnum, const tString &in asClass = "");

Parameter	Meaning
asName	the name of the entity.
aType	(optional), the type of entity (as an enum).
asClass	(optional), the class of the entity.

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

iLuxEntity@ pPropEntity = Map_GetEntity("David");

Parameter	Value in this stock call
asName	"David"

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.

Parameter	Meaning
asMapName	map to change to.
asStartPos	name of the player start node that the player should begin at.
asStartSound	sound that plays before loading the map.
asEndSound	sound that plays as the new map starts.

Check your change

Save the script and restart the map in development mode with F5. If the script fails, open F1 and use Show Error List or Show HPL Log. See the development loop for the launch and debugging steps.

See also

• SOMA scripting
• SOMA scripting API