TiMan: Expand the practical source walkthrough and clarify how to use the handler.

2026-10-02T12:32:10Z

Expand the practical source walkthrough and clarify how to use the handler.

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

2026-10-02T12:22:29Z

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

New page

{{shortPageTitle}}

== Registered effects ==
{| class="wikitable"
! Name !! ScriptFile !! ScriptClass
|-
| <code>Shake</code> || <code>effects/Effect_Shake.hps</code> || <code>cScrEffect_Shake</code>
|-
| <code>DoF</code> || <code>effects/Effect_DoF.hps</code> || <code>cScrEffect_DoF</code>
|-
| <code>ToneMapping</code> || <code>effects/Effect_ToneMapping.hps</code> || <code>cScrEffect_ToneMapping</code>
|-
| <code>ImageTrail</code> || <code>effects/Effect_ImageTrail.hps</code> || <code>cScrEffect_ImageTrail</code>
|-
| <code>Flash</code> || <code>effects/Effect_Flash.hps</code> || <code>cScrEffect_Flash</code>
|-
| <code>Screen</code> || <code>effects/Effect_Screen.hps</code> || <code>cScrEffect_Screen</code>
|-
| <code>ChromaticAberration</code> || <code>effects/Effect_ChromaticAberration.hps</code> || <code>cScrEffect_ChromaticAberration</code>
|-
| <code>RadialBlur</code> || <code>effects/Effect_RadialBlur.hps</code> || <code>cScrEffect_RadialBlur</code>
|-
| <code>VideoDistortion</code> || <code>effects/Effect_VideoDistortion.hps</code> || <code>cScrEffect_VideoDistortion</code>
|-
| <code>TimeGlitch</code> || <code>effects/Effect_TimeGlitch.hps</code> || <code>cScrEffect_TimeGlitch</code>
|-
| <code>Sway</code> || <code>effects/Effect_Sway.hps</code> || <code>cScrEffect_Sway</code>
|-
| <code>ImageFadeFX</code> || <code>effects/Effect_ImageFadeFX.hps</code> || <code>cScrEffect_ImageFadeFX</code>
|-
| <code>Gamepad</code> || <code>effects/Effect_Gamepad.hps</code> || <code>cScrEffect_Gamepad</code>
|}

SOMA registers effect classes by name, script file and numeric ID. Effect helpers retrieve them through the Effect Handler and call a typed interface. Screen and post-processing effects include shake, depth of field, tone mapping and video distortion; the Gamepad effect instead handles controller rumble.

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

== 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/Effects Helper|Effect helpers]]
* [[HPL3/SOMA/Scripting/Effects Interfaces|Effect interface]]

[[Category:English]]

@@ Line 1: / Line 1: @@
 {{shortPageTitle}}
 == Registered effects ==
@@ Line 32: / Line 34: @@
 |}
-SOMA registers effect classes by name, script file and numeric ID. Effect helpers retrieve them through the Effect Handler and call a typed interface. Screen and post-processing effects include shake, depth of field, tone mapping and video distortion; the Gamepad effect instead handles controller rumble.
 == Before you start ==

HPL3/SOMA/Scripting/Effects Overview - Revision history

TiMan: Expand the practical source walkthrough and clarify how to use the handler.

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