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

2026-10-02T12:12:01Z

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

New page

{{shortPageTitle}}

This handler connects entities to a proximity-based distortion amount. AddInstance specifies where the effect starts, where it reaches maximum strength and the easing curve between those distances; RemoveInstance breaks the connection.

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

=== DistortionEffect_AddInstance ===
Adds the entity has an instance that will help create a distortion effect if the player is near enough.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>a_idEntity</code> || The entity who this will be connected to.
|-
| <code>afMaxDistance</code> || The distance at which the effect will start.
|-
| <code>afMinDistance</code> || The distance when the effect will be at max
|-
| <code>afMaxAmount</code> || The max amount the effect will have from this entity.
|-
| <code>aEasing</code> || The easing function used to fade between max and min
|}

In <code>script/custom_depth/agent_fixed_human.hps</code>, SOMA calls <code>DistortionEffect_AddInstance</code> as follows.

<syntaxhighlight lang="cpp">
DistortionEffect_AddInstance(mBaseObj.GetID(), 15, 3, 0.4);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>a_idEntity</code> || <code>mBaseObj.GetID()</code>
|-
| <code>afMaxDistance</code> || <code>15</code>
|-
| <code>afMinDistance</code> || <code>3</code>
|-
| <code>afMaxAmount</code> || <code>0.4</code>
|}

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

=== DistortionEffect_RemoveInstance ===
Removes an instance that will create the distortion effect.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>a_idEntity</code> || The entity to break the connection with
|}

In <code>script/custom_depth/agent_construct_worker.hps</code>, SOMA calls <code>DistortionEffect_RemoveInstance</code> as follows.

<syntaxhighlight lang="cpp">
DistortionEffect_RemoveInstance(mBaseObj.GetID());
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>a_idEntity</code> || <code>mBaseObj.GetID()</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/Scripting/User Modules Overview|User modules]]
* [[HPL3/SOMA/Scripting/Modules Helper|SOMA module helpers]]

[[Category:English]]

HPL3/SOMA/Scripting/Distortion Effect Handler - Revision history

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