Audio Helper

The Audio helper file in SOMA is script/helpers/helper_audio.hps.

Audio helpers create world-positioned sounds, play GUI sounds, control music and start named voice subjects. Sound_CreateAtEntity creates a sound at an entity or the player; Sound_Play is for an existing placed or previously created sound.

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

Sound_CreateAtEntity

Create and play a sound (.snt) file at the position of an entity or player.

Parameter	Meaning
asSoundName	name of the sound that is used when you like to, for example, stop it.
asSoundFile	name of the FMOD event or .snt sound file to play. FMOD always needs to be full path ie "project/event_group(s)/event".
asEntity	name of the entity to play the sound at, can also be "player".
afFadeTime	fade in the sound during this many seconds, 0 = no fade.
abSaveSound	if the sound should be saved, ie if sound loops and the sound should play on exit and enter of the level.
afTargetVolume	the volume (0.0 - 1.0) the sound should be played at. Defaults to 1.0f.

In maps/chapter05/05_02_ARK_inside/05_02_ARK_inside.hps, SOMA calls Sound_CreateAtEntity as follows.

Sound_CreateAtEntity("ExitCaveSweet", "05_02/SFX/exit_cave_sweet", "Player");

Parameter	Value in this stock call
asSoundName	"ExitCaveSweet"
asSoundFile	"05_02/SFX/exit_cave_sweet"
asEntity	"Player"

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

Sound_Play

Play a sound that exists in the level editor, attached to an entity, or previously created that has been stopped and now should be played again.

Parameter	Meaning
asSoundName	name of the sounds that you would like to play. Wildcard(s) * are supported.
afFadeTime	fade in the sound during this many seconds, 0 = no fade.
abResetVolMul	reset the FadeVolumeMul set when using Sound_Fade.

In maps/_e3/_e3_01_01/_e3_01_01.hps, SOMA calls Sound_Play as follows.

Sound_Play("sparks_area_1", 1.0f);

Parameter	Value in this stock call
asSoundName	"sparks_area_1"
afFadeTime	1.0f

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

Voice_Play

Starts playing a voice

Parameter	Meaning
asSubject	The name of the subject to play.
alSpecificLineIdx	if 0 or higher then a specific line index will be played. Set as -1 to play as stated in the data.
asCallback	called when subject is done playing. Syntax: void Func(const tString&in asScene, const tString&in asSubject)
alPrio	The priority of the voice, if higher than the currently playing, the current gets stopped and replaced, else this voice is not played.

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