Modules Helper

The Modules helper file in SOMA is script/helpers/helper_modules.hps.

Module helpers expose script-module behavior to map and entity scripts. For example, LightFlash_Add resolves the named entity and forwards its position to the Light Flash Handler; a missing named entity produces an error and returns -1.

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_modules.hps"

LightFlash_Add

Creates a flash of light at the position of an entity. Returns id of the flash.

Parameter	Meaning
afTime	The time that light stays at full intensity
afFadeInTime	How long it takes to fade in
afFadeOutTime	How long it takes to fade out
asTargetEntity	Entity at which it will be created.
aColor	The color of the light.
afRadius	The radius of the light (this will NOT be faded, it starts with this radius, and then just color fades in)
afBrightness	The brightness of the light.

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

LightFlash_Add(0.25f,0.1f,0.2f,"CortexChipTool", cColor_White, 0.15f, 2.0f);

Parameter	Value in this stock call
afTime	0.25f
afFadeInTime	0.1f
afFadeOutTime	0.2f
asTargetEntity	"CortexChipTool"
aColor	cColor_White
afRadius	0.15f
afBrightness	2.0f

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

LightFlash_Add

Creates a flash of light at the position of an entity. Returns id of the flash.

Parameter	Meaning
afTime	The time that light stays at full intensity
afFadeInTime	How long it takes to fade in
afFadeOutTime	How long it takes to fade out
avTargetPos	Position at which it will be created.
aColor	The color of the light.
afRadius	The radius of the light (this will NOT be faded, it starts with this radius, and then just color fades in)
afBrightness	The brightness of the light.

Description_Add

Use this helper for displayed text: it forwards the language category, entry, display-time multiplier and queue flag to the Description Handler. See the description example for text lookup, duration and queuing behavior.

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