TiMan: Clarify the worked example using verified stock-script values.

2026-10-02T12:24:06Z

Clarify the worked example using verified stock-script values.

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

2026-10-02T12:13:24Z

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

New page

{{shortPageTitle}}

The Emotion Handler plays player heartbeats and breathing. Heartbeat and background-breath instances have priorities and returned IDs for later changes or stopping; background-breath fade parameters are speeds, rather than fade durations.

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

=== Emotion_StartHeartbeat ===
Starts a new instance of heart beats

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afTimeBetweenBeats</code> || The time between the beats
|-
| <code>afVolume</code> || Volume of the heart beats (0-1)
|-
| <code>alPrio</code> || The prio of instance. Higher is played over low.er
|-
| <code>afDuration</code> || How long the heart beats lasts, -1 means until stopped.
|-
| <code>afFadeInTime</code> || The time it takes for this instance to fade in.
|-
| <code>afFadeOutTime</code> || The time it takes to fade out, only used if no instance is active.
|}

In <code>maps/_e3/_e3_01_03/_e3_01_03.hps</code>, SOMA calls <code>Emotion_StartHeartbeat</code> as follows.

<syntaxhighlight lang="cpp">
Emotion_StartHeartbeat(0.6,1.0f,1, 15);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>afTimeBetweenBeats</code> || <code>0.6</code>
|-
| <code>afVolume</code> || <code>1.0f</code>
|-
| <code>alPrio</code> || <code>1</code>
|-
| <code>afDuration</code> || <code>15</code>
|}

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

=== Emotion_StartBackgroundBreath ===
Starts a new instance of background breathing. Returns ID of the instance.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>aType</code> || The type of breath.
|-
| <code>afStrength</code> || The strength of the breaths. Must be 0 - 1.
|-
| <code>alPrio</code> || The prio of this instance. Higher is played over lower.
|-
| <code>afDuration</code> || How long the breathing lasts, -1 means until stopped.
|-
| <code>afFadeInSpeed</code> || the speed (note NOT time) that used when fading to this instance. If <0, the FadeOut from a previous instance is used.
|-
| <code>afFadeOutSpeed</code> || if going back to default breathing or the upcoming has<0 as FadeInSpeed, this it the speed (NOT time) used. Note that if another instance is taking over, its FadeInSpeed will be used instead.
|}

In <code>maps/chapter04/04_03_tau_escape/04_03_tau_escape.hps</code>, SOMA calls <code>Emotion_StartBackgroundBreath</code> as follows.

<syntaxhighlight lang="cpp">
Emotion_StartBackgroundBreath(eBreathType_Normal, 06,1, 6,3, 5);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>aType</code> || <code>eBreathType_Normal</code>
|-
| <code>afStrength</code> || <code>06</code>
|-
| <code>alPrio</code> || <code>1</code>
|-
| <code>afDuration</code> || <code>6</code>
|-
| <code>afFadeInSpeed</code> || <code>3</code>
|-
| <code>afFadeOutSpeed</code> || <code>5</code>
|}

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

=== Emotion_StopHeartbeat ===
Stops an instance of heart beats.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>alId</code> || The ID of the instance
|}

In <code>maps/chapter02/02_07_theta_exit/02_07_theta_exit.hps</code>, SOMA calls <code>Emotion_StopHeartbeat</code> as follows.

<syntaxhighlight lang="cpp">
Emotion_StopHeartbeat(mlHeartbeatID);
</syntaxhighlight>

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

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

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

== Read the example ==
Keep the ID returned by a heartbeat or breathing start call if you want to stop that particular instance later. A duration of -1 keeps the instance going until it is stopped. Heartbeat fade arguments are durations, while background-breath <code>afFadeInSpeed</code> and <code>afFadeOutSpeed</code> are speeds; they are not interchangeable.

== See also ==
* [[HPL3/Scripting/User Modules Overview|User modules]]
* [[HPL3/SOMA/Scripting/Modules Helper|SOMA module helpers]]

[[Category:English]]

@@ Line 71: / Line 71: @@
 |}
-In <code>maps/chapter04/04_03_tau_escape/04_03_tau_escape.hps</code>, SOMA calls <code>Emotion_StartBackgroundBreath</code> as follows.
+In <code>maps/chapter02/02_05_theta_inside/02_05_theta_inside.hps</code>, the landing-breathing callback starts normal background breathing at strength <code>0.6f</code>, priority <code>3</code> and duration <code>8</code>. The final arguments are fade speeds: <code>0</code> for fading in and <code>3</code> for fading out.
 <syntaxhighlight lang="cpp">
-Emotion_StartBackgroundBreath(eBreathType_Normal, 06,1, 6,3, 5);
+Emotion_StartBackgroundBreath(eBreathType_Normal, 0.6f, 3, 8, 0, 3);
 </syntaxhighlight>
 === Emotion_StopHeartbeat ===

HPL3/SOMA/Scripting/Emotion Handler - Revision history

TiMan: Clarify the worked example using verified stock-script values.

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