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

2026-10-02T12:12:50Z

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

New page

{{shortPageTitle}}

The Map Effects Handler fades world settings and stores named environment presets. Map_Preset_SetupFog defines the fog portion of a preset; Map_Preset_Fade applies a named preset over a fade duration.

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

=== Map_Preset_SetupFog ===
Setup fog for the specified preset

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || Name of the preset
|-
| <code>abActive</code> || If fog should be active
|-
| <code>afStart</code> || Where fog starts showing
|-
| <code>afEnd</code> || Where fog has full effect
|-
| <code>afFalloffExp</code> || How fast the fog fades to full effect, lower is faster
|-
| <code>aColor</code> || Color of the fog
|-
| <code>afBrightness</code> || Brightness of the fog
|-
| <code>abUnderwater</code> || If underwater fog should be used
|-
| <code>abSkybox</code> || If fog color should be taken from skybox
|}

In <code>maps/chapter02/02_03_delta/02_03_delta.hps</code>, SOMA calls <code>Map_Preset_SetupFog</code> as follows.

<syntaxhighlight lang="cpp">
Map_Preset_SetupFog("Outside2.4", true, 0, 25, 0.3, cColor(0.047,0.086,0.098,1), 1, true, true);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asName</code> || <code>"Outside2.4"</code>
|-
| <code>abActive</code> || <code>true</code>
|-
| <code>afStart</code> || <code>0</code>
|-
| <code>afEnd</code> || <code>25</code>
|-
| <code>afFalloffExp</code> || <code>0.3</code>
|-
| <code>aColor</code> || <code>cColor(0.047,0.086,0.098,1)</code>
|-
| <code>afBrightness</code> || <code>1</code>
|-
| <code>abUnderwater</code> || <code>true</code>
|-
| <code>abSkybox</code> || <code>true</code>
|}

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

=== Map_Preset_Fade ===
Fade in the preset

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || Name of the preset
|-
| <code>afFadeTime</code> || How long it should take to fade in
|}

In <code>maps/chapter03/03_01_omicron_outside/03_01_omicron_outside.hps</code>, SOMA calls <code>Map_Preset_Fade</code> as follows.

<syntaxhighlight lang="cpp">
Map_Preset_Fade("Dome", 0.5);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asName</code> || <code>"Dome"</code>
|-
| <code>afFadeTime</code> || <code>0.5</code>
|}

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

=== Map_FadeFogColor ===

In <code>maps/chapter05/05_01_phi_inside/05_01_phi_inside.hps</code>, SOMA calls <code>Map_FadeFogColor</code> as follows.

<syntaxhighlight lang="cpp">
Map_FadeFogColor(cColor(0),8.0f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>aTarget</code> || <code>cColor(0)</code>
|-
| <code>afTime</code> || <code>8.0f</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/Map Effects Handler - Revision history

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