HPL3/SOMA/Scripting/Sequences Helper - Revision history

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

2026-10-02T12:24:11Z

Clarify the worked example using verified stock-script values.

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

2026-10-02T12:09:57Z

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

New page

{{shortPageTitle}}

The Sequences helper file in SOMA is <code>script/helpers/helper_sequences.hps</code>.

Sequence helpers divide an event function into ordered steps using a cSequenceStatesData object. Sequence_Begin prepares the state check, Sequence_DoStepAndWait runs one step and schedules the next, and Sequence_End resets a sequence after its steps finish. The source warns that the whole sequence function runs again for each step.

== Follow the wake-up sequence ==
The Tau Escape map stores one <code>cSequenceStatesData</code> object for this sequence and uses the sequence function’s own name in <code>Sequence_Begin</code>. Each <code>if / else if</code> condition selects a step. The delay belongs to the step that just ran: 0.25 before the sound step, then 6 before the fade-in step, then 5 before the timer step. <code>Sequence_End</code> completes the state check.

<syntaxhighlight lang="cpp">
cSequenceStatesData mSeqWakeUp;
void Seq_WakeUp(const tString &in asX)
{
Sequence_Begin("Seq_WakeUp", mSeqWakeUp);

if (Sequence_DoStepAndWait(0.25))
{
Effect_Fade_Out(0);
Map_SetUnderwater(true);

Sound_SetGlobalVolume(0.0f, eSoundEntryType_WorldAll);
Sound_SetGlobalVolume(0.0f, eSoundEntryType_GuiWorld);
}
else if (Sequence_DoStepAndWait(6.0))
{
Sound_CreateAtEntity("WakeUp", "04_03_tau_escape/SFX/wake_up_sweet", "Player");
}
else if (Sequence_DoStepAndWait(5))
{
Effect_Fade_In(5);

Sound_FadeGlobalVolume(1.0f, 6.0f, eSoundEntryType_WorldAll);
Sound_FadeGlobalVolume(1.0f, 6.0f, eSoundEntryType_GuiWorld);

Emotion_StartBackgroundBreath(eBreathType_Normal, 06,1, 6,3, 5);

Effect_ImageTrail_Start(0.5, 0.1f, 6, 2);
CameraAnimation_Begin("WakeupAnim", "", true);
}
else if (Sequence_DoStepAndWait(5))
{
Map_AddTimer("SetupTravelTowardsTau", 0.3, "TimerSetupTravelTowardsTau");
}

Sequence_End();
}
</syntaxhighlight>

This is the stock Tau Escape sequence, including its sound, camera-animation and timer dependencies. The whole function is called again for each step, so code outside the step conditions also runs again.

== Include and adapt ==
# Include <code>helpers/helper_sequences.hps</code> alongside the helpers needed by the actions in your sequence.
# Keep a separate <code>cSequenceStatesData</code> object for the sequence and pass it to <code>Sequence_Begin</code>.
# Put each action inside a <code>Sequence_DoStepAndWait</code> condition, keeping the <code>if / else if</code> chain and the final <code>Sequence_End()</code>.

== See also ==
* [[HPL3/SOMA/Scripting/Map Helper|Timers and map helpers]]
* [[HPL3/SOMA/Getting Started/Test Debug and Continue|Test and debug your script]]

[[Category:English]]

@@ Line 6: / Line 6: @@
 == Follow the wake-up sequence ==
-The Tau Escape map stores one <code>cSequenceStatesData</code> object for this sequence and uses the sequence function’s own name in <code>Sequence_Begin</code>. Each <code>if / else if</code> condition selects a step. The delay belongs to the step that just ran: 0.25 before the sound step, then 6 before the fade-in step, then 5 before the timer step. <code>Sequence_End</code> completes the state check.
+The Tau Escape map stores one <code>cSequenceStatesData</code> object for this sequence and uses the sequence function’s own name in <code>Sequence_Begin</code>. Each <code>if / else if</code> condition selects a step. The delay belongs to the step that just ran: 0.25 before the sound step, then 6 before the sequence finishes. <code>Sequence_End</code> completes the state check.
 <syntaxhighlight lang="cpp">
@@ Line 17: / Line 17: @@
+			{
 				Effect_Fade_Out(0);
+			}
 			else if (Sequence_DoStepAndWait(6.0))
+			{
 				Sound_CreateAtEntity("WakeUp", "04_03_tau_escape/SFX/wake_up_sweet", "Player");
+			}
 			Sequence_End();
+		}
 </syntaxhighlight>
-This is the stock Tau Escape sequence, including its sound, camera-animation and timer dependencies. The whole function is called again for each step, so code outside the step conditions also runs again.
+This example is shortened from the stock Tau Escape sequence to demonstrate a fade-out followed by a sound and fade-in. Its wake-up sound must be available in the mod. The whole function is called again for each step, so code outside the step conditions also runs again.
 == Include and adapt ==