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

2026-10-02T12:19:15Z

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

New page

{{shortPageTitle}}

SOMA provides the Video Distortion script in <code>script/effects/Effect_VideoDistortion.hps</code>.

Video distortion has direct and timed-instance controls. The largest amount is used when several instances are active; helpers can change an instance’s maximum amount or disable distortion sounds.

== 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_VideoDistortion_Start ===
Starts the video distortion effect. If many have been started the max amount is used. Returns ID to this instance.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afAmount</code> || The amount of effect, 0 - 1 are valid values. (0 turns off)
|-
| <code>afTime</code> || The length the effect (after fade in) the effect should last. -1 means it lasts forever.
|-
| <code>afFadeInTime</code> || The time it takes for the effect to fade in.
|-
| <code>afFadeOutTime</code> || The time it takes for the effect to fade out.
|-
| <code>afVolume</code> || Volume of gui sound (will override previous instances. Only one sound at a time)
|}

In <code>maps/_e3/_e3_01_02/_e3_01_02.hps</code>, SOMA calls <code>Effect_VideoDistortion_Start</code> as follows.

<syntaxhighlight lang="cpp">
Effect_VideoDistortion_Start(0.6, 1,0.5,5);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>afAmount</code> || <code>0.6</code>
|-
| <code>afTime</code> || <code>1</code>
|-
| <code>afFadeInTime</code> || <code>0.5</code>
|-
| <code>afFadeOutTime</code> || <code>5</code>
|}

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

=== Effect_VideoDistortion_FadeOut ===
Fades out a video distortion effect instance.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>alID</code> || id to the instance to fade out. If -1, all instances will be faded.
|-
| <code>afFadeOutTime</code> || The time it takes for the effect to fade out.
|}

In <code>maps/chapter02/02_02_ms_curie_inside/02_02_ms_curie_inside.hps</code>, SOMA calls <code>Effect_VideoDistortion_FadeOut</code> as follows.

<syntaxhighlight lang="cpp">
Effect_VideoDistortion_FadeOut(-1,1.0);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>alID</code> || <code>-1</code>
|-
| <code>afFadeOutTime</code> || <code>1.0</code>
|}

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

=== Effect_VideoDistortion_SetSoundEffectsDisabled ===
Set if video distortion sounds should be disabled.

== 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|SOMA effects helpers]]

[[Category:English]]

HPL3/SOMA/Scripting/Video Distortion - Revision history

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