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

2026-10-02T12:22:52Z

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

New page

{{shortPageTitle}}

This page describes SOMA’s Depth of Field effect.

Depth of field creates a focus range and blurs outside it. The helper returns an instance ID so its focus range and falloff can be faded or the instance removed.

== 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_DoF_Start ===
Starts an instance of depth of field and returns the id

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afFocusStart</code> || near plane of the instance
|-
| <code>afFocusEnd</code> || far plane of the instance
|-
| <code>afFalloff</code> || how smooth the transition from sharp to blurr should be
|-
| <code>afTime</code> || time to fade to this value
|}

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

<syntaxhighlight lang="cpp">
Effect_DoF_Start(0, 6, 0.5, 0);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>afFocusStart</code> || <code>0</code>
|-
| <code>afFocusEnd</code> || <code>6</code>
|-
| <code>afFalloff</code> || <code>0.5</code>
|-
| <code>afTime</code> || <code>0</code>
|}

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

=== Effect_DoF_FadeFocus ===
Fade the start and end of the focus plane

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>alID</code> || id of the instance
|-
| <code>afFocusStart</code> || near plane of the instance
|-
| <code>afFocusEnd</code> || far plane of the instance
|-
| <code>afTime</code> || time to fade to this value
|}

In <code>maps/chapter04/04_03_tau_escape/04_03_tau_escape.hps</code>, SOMA calls <code>Effect_DoF_FadeFocus</code> as follows.

<syntaxhighlight lang="cpp">
Effect_DoF_FadeFocus(mlDoFId, 0.05, 10, 2);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>alID</code> || <code>mlDoFId</code>
|-
| <code>afFocusStart</code> || <code>0.05</code>
|-
| <code>afFocusEnd</code> || <code>10</code>
|-
| <code>afTime</code> || <code>2</code>
|}

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

=== Effect_DoF_FadeOut ===
Fade out the instance of depth of field, the instance is removed after fading out

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>alID</code> || id of the instance
|-
| <code>afTime</code> || time to fade out
|}

== 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/Depth of Field - Revision history

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