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

2026-10-02T12:23:00Z

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

New page

{{shortPageTitle}}

This page describes SOMA’s Screen effect.

Screen effects draw a material over the screen. One Start overload leaves the image active for manual fading; the other gives it fade-in, hold and fade-out times. The source explicitly requires images that work at both 4:3 and 16:9 aspect ratios.

== 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_Screen_Start: manual fading ===
Creates a images that shows up on the screen, it must be faded manually
Remember that these must work on both 4:3 and 16:9 aspect ratio

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asMaterial</code> || material to use
|-
| <code>avPosition</code> || position on the screen, values between [0,1]
|-
| <code>avSize</code> || size of the texture
|}

=== Effect_Screen_Start: timed image ===
Creates a images that fade in and then out
Remember that these must work on both 4:3 and 16:9 aspect ratio

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asMaterial</code> || material to use
|-
| <code>avPosition</code> || position on the screen, values between [0,1]
|-
| <code>avSize</code> || size of the texture
|-
| <code>afTargetAlpha</code> || alpha it should stop fading at
|-
| <code>afFadeInTime</code> || how fast it should fade in
|-
| <code>afStayTime</code> || how long it should stay after fading in
|-
| <code>afFadeOutTime</code> || how fast it should fade out again
|}

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

<syntaxhighlight lang="cpp">
Effect_Screen_Start("water_splash_screen.mat", cVector2f(0.5, 0.5), cVector2f(1.8, 1.8), 1, 0.4f, 0.2f, 0.6f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asMaterial</code> || <code>"water_splash_screen.mat"</code>
|-
| <code>avPosition</code> || <code>cVector2f(0.5, 0.5)</code>
|-
| <code>avSize</code> || <code>cVector2f(1.8, 1.8)</code>
|-
| <code>afTargetAlpha</code> || <code>1</code>
|-
| <code>afFadeInTime</code> || <code>0.4f</code>
|-
| <code>afStayTime</code> || <code>0.2f</code>
|-
| <code>afFadeOutTime</code> || <code>0.6f</code>
|}

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

=== Effect_Screen_FadeAlpha ===
Fades the transparency of a material

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>alID</code> || id of the screen material
|-
| <code>afAlpha</code> || transparency of the material value between [0,1]
|-
| <code>afFadeTime</code> || time to fade over
|}

== 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/Screen - Revision history

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