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

2026-10-02T12:06:34Z

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

New page

{{shortPageTitle}}

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

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

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

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

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

<syntaxhighlight lang="cpp">
Sound_CreateAtEntity("ExitCaveSweet", "05_02/SFX/exit_cave_sweet", "Player");
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asSoundName</code> || <code>"ExitCaveSweet"</code>
|-
| <code>asSoundFile</code> || <code>"05_02/SFX/exit_cave_sweet"</code>
|-
| <code>asEntity</code> || <code>"Player"</code>
|}

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.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asSoundName</code> || name of the sounds that you would like to play. Wildcard(s) * are supported.
|-
| <code>afFadeTime</code> || fade in the sound during this many seconds, 0 = no fade.
|-
| <code>abResetVolMul</code> || reset the FadeVolumeMul set when using Sound_Fade.
|}

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

<syntaxhighlight lang="cpp">
Sound_Play("sparks_area_1", 1.0f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asSoundName</code> || <code>"sparks_area_1"</code>
|-
| <code>afFadeTime</code> || <code>1.0f</code>
|}

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

=== Voice_Play ===
Starts playing a voice

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asSubject</code> || The name of the subject to play.
|-
| <code>alSpecificLineIdx</code> || if 0 or higher then a specific line index will be played. Set as -1 to play as stated in the data.
|-
| <code>asCallback</code> || called when subject is done playing. Syntax: void Func(const tString&in asScene, const tString&in asSubject)
|-
| <code>alPrio</code> || 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 <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/Audio Helper - Revision history

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