HPL3/SOMA/Scripting/Emotion Handler

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

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"

Emotion_StartHeartbeat

Starts a new instance of heart beats

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

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

Emotion_StartHeartbeat(0.6,1.0f,1, 15);

Parameter	Value in this stock call
afTimeBetweenBeats	0.6
afVolume	1.0f
alPrio	1
afDuration	15

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.

Parameter	Meaning
aType	The type of breath.
afStrength	The strength of the breaths. Must be 0 - 1.
alPrio	The prio of this instance. Higher is played over lower.
afDuration	How long the breathing lasts, -1 means until stopped.
afFadeInSpeed	the speed (note NOT time) that used when fading to this instance. If <0, the FadeOut from a previous instance is used.
afFadeOutSpeed	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 maps/chapter02/02_05_theta_inside/02_05_theta_inside.hps, the landing-breathing callback starts normal background breathing at strength 0.6f, priority 3 and duration 8. The final arguments are fade speeds: 0 for fading in and 3 for fading out.

Emotion_StartBackgroundBreath(eBreathType_Normal, 0.6f, 3, 8, 0, 3);

Emotion_StopHeartbeat

Stops an instance of heart beats.

Parameter	Meaning
alId	The ID of the instance

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

Emotion_StopHeartbeat(mlHeartbeatID);

Parameter	Value in this stock call
alId	mlHeartbeatID

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

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 afFadeInSpeed and afFadeOutSpeed are speeds; they are not interchangeable.

See also

• User modules
• SOMA module helpers