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

2026-10-02T12:12:45Z

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

New page

{{shortPageTitle}}

This handler creates temporary point lights that fade in, hold their brightness and fade out before being destroyed. LightFlash_Add accepts either a named entity or a world position; its radius is fixed during the flash.

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

=== LightFlash_Add ===
Creates a flash of light at the position of an entity. Returns id of the flash.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afTime</code> || The time that light stays at full intensity
|-
| <code>afFadeInTime</code> || How long it takes to fade in
|-
| <code>afFadeOutTime</code> || How long it takes to fade out
|-
| <code>asTargetEntity</code> || Entity at which it will be created.
|-
| <code>aColor</code> || The color of the light.
|-
| <code>afRadius</code> || The radius of the light (this will NOT be faded, it starts with this radius, and then just color fades in)
|-
| <code>afBrightness</code> || The brightness of the light.
|}

In <code>maps/chapter02/02_01_ms_curie_outside/02_01_ms_curie_outside.hps</code>, SOMA calls <code>LightFlash_Add</code> as follows.

<syntaxhighlight lang="cpp">
LightFlash_Add(0.25f,0.1f,0.2f,"CortexChipTool", cColor_White, 0.15f, 2.0f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>afTime</code> || <code>0.25f</code>
|-
| <code>afFadeInTime</code> || <code>0.1f</code>
|-
| <code>afFadeOutTime</code> || <code>0.2f</code>
|-
| <code>asTargetEntity</code> || <code>"CortexChipTool"</code>
|-
| <code>aColor</code> || <code>cColor_White</code>
|-
| <code>afRadius</code> || <code>0.15f</code>
|-
| <code>afBrightness</code> || <code>2.0f</code>
|}

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

=== LightFlash_Add ===
Creates a flash of light at the position of an entity. Returns id of the flash.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afTime</code> || The time that light stays at full intensity
|-
| <code>afFadeInTime</code> || How long it takes to fade in
|-
| <code>afFadeOutTime</code> || How long it takes to fade out
|-
| <code>avTargetPos</code> || Position at which it will be created.
|-
| <code>aColor</code> || The color of the light.
|-
| <code>afRadius</code> || The radius of the light (this will NOT be faded, it starts with this radius, and then just color fades in)
|-
| <code>afBrightness</code> || The brightness of the light.
|}

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

== Read the example ==
The Curie example makes a white point-light flash at <code>CortexChipTool</code>. Its fade-in takes 0.1 seconds, the full-brightness hold takes 0.25 seconds and the fade-out takes 0.2 seconds. The light starts with radius 0.15 and brightness 2; the handler changes brightness during the fade, then destroys the light.

== See also ==
* [[HPL3/Scripting/User Modules Overview|User modules]]
* [[HPL3/SOMA/Scripting/Modules Helper|SOMA module helpers]]

[[Category:English]]

HPL3/SOMA/Scripting/Light Flash Handler - Revision history

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