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

2026-10-02T12:09:12Z

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

New page

{{shortPageTitle}}

The Effects helper file in SOMA is <code>script/helpers/helper_effects.hps</code>.

Effect helpers operate on screen, camera and gamepad effects. Shake creates an instance and returns its ID; the ID can be used to fade that instance out or assign a spatial source.

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

=== Effect_Shake_Start ===
Makes the screen shake for a certain amount of time. Returns id to the current shaking.
If several calls to shake has been made the largest one is used.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afAmount</code> || The strength of the shake.
|-
| <code>afTime</code> || The time it shakes at full intensity (fade in and fade out are added to this).
|-
| <code>afFadeInTime</code> || The time before it reaches full strength.
|-
| <code>afFadeOutTime</code> || The time, after afTime is up, that it will take for the shake to reach zero strength.
|-
| <code>avDirAmount</code> || The amount it will shake in each direction in camera space
|-
| <code>afFrequency</code> || Times per seconds the shake will change offset. 0=every update (ie max).
|}

In <code>maps/chapter02/02_04_theta_outside/02_04_theta_outside.hps</code>, SOMA calls <code>Effect_Shake_Start</code> as follows.

<syntaxhighlight lang="cpp">
Effect_Shake_Start(0.2, 2, 12, 0);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>afAmount</code> || <code>0.2</code>
|-
| <code>afTime</code> || <code>2</code>
|-
| <code>afFadeInTime</code> || <code>12</code>
|-
| <code>afFadeOutTime</code> || <code>0</code>
|}

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

=== Effect_Shake_FadeOut ===
Fades out one or all shake instances.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>alID</code> || The id of the shake (returned by Effect_Shake_Start). -1 = fade out all active shakes.
|-
| <code>afFadeOutTime</code> || the time it takes to fade out.
|}

In <code>maps/chapter04/04_01_tau_outside/04_01_tau_outside.hps</code>, SOMA calls <code>Effect_Shake_FadeOut</code> as follows.

<syntaxhighlight lang="cpp">
Effect_Shake_FadeOut(mlShakeID, 0.5f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>alID</code> || <code>mlShakeID</code>
|-
| <code>afFadeOutTime</code> || <code>0.5f</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.

== See also ==
* [[HPL3/SOMA/Scripting|SOMA scripting]]
* [[HPL3/SOMA/Scripting/Scripting Api|SOMA scripting API]]

[[Category:English]]

HPL3/SOMA/Scripting/Effects Helper - Revision history

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