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

2026-10-02T12:09:16Z

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

New page

{{shortPageTitle}}

The Areas helper file in SOMA is <code>script/helpers/helper_areas.hps</code>.

Area helpers move areas and operate on specialized area behavior such as doorway groups, liquids, sticky attachments and camera-animation nodes. Ordinary area movement excludes liquid areas, which have their own movement helper.

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

=== Area_MoveLinearTo ===
Moves the specified area to the current position of the target entity.
!Does not work on Liquid Areas, instead use LiquidArea_MoveLinearTo!

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || name of the area to move, wildcard(s) * are supported.
|-
| <code>asTargetEntity</code> || name of the entity to move the area to.
|-
| <code>afAcceleration</code> || acceleration .in m/s^2
|-
| <code>afMaxSpeed</code> || the maximum speed of movement.
|-
| <code>afSlowDownDist</code> || the distance at which movement slows down.
|-
| <code>abResetSpeed</code> || if all static movement for the area should be stopped before starting this movement.
|-
| <code>asCallback</code> || callback when movement is done: void asCallback(const tString& in asAreaName)
|}

In <code>maps/_e3/_e3_01_01/_e3_01_01.hps</code>, SOMA calls <code>Area_MoveLinearTo</code> as follows.

<syntaxhighlight lang="cpp">
Area_MoveLinearTo("RunningSoundSource","RunningSoundSource_Target",2.2f,5.0f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asName</code> || <code>"RunningSoundSource"</code>
|-
| <code>asTargetEntity</code> || <code>"RunningSoundSource_Target"</code>
|-
| <code>afAcceleration</code> || <code>2.2f</code>
|-
| <code>afMaxSpeed</code> || <code>5.0f</code>
|}

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

=== LiquidArea_MoveLinearTo ===
Moves the specified liquid area to the current position of the target entity.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || name of the liquid area to move, wildcard(s) * are supported.
|-
| <code>asTargetEntity</code> || name of the entity to move the liquid area to.
|-
| <code>afAcceleration</code> || acceleration .in m/s^2
|-
| <code>afMaxSpeed</code> || the maximum speed of movement.
|-
| <code>afSlowDownDist</code> || the distance at which movement slows down.
|-
| <code>abResetSpeed</code> || if all static movement for the liquid area should be stopped before starting this movement.
|-
| <code>asCallback</code> || callback when movement is done: void asCallback(const tString& in asAreaName)
|}

In <code>maps/chapter02/02_04_theta_outside/02_04_theta_outside.hps</code>, SOMA calls <code>LiquidArea_MoveLinearTo</code> as follows.

<syntaxhighlight lang="cpp">
LiquidArea_MoveLinearTo("LiquidArea_1", "LiquidArea_1_Target", 1, 1, 0.25);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asName</code> || <code>"LiquidArea_1"</code>
|-
| <code>asTargetEntity</code> || <code>"LiquidArea_1_Target"</code>
|-
| <code>afAcceleration</code> || <code>1</code>
|-
| <code>afMaxSpeed</code> || <code>1</code>
|-
| <code>afSlowDownDist</code> || <code>0.25</code>
|}

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

=== StickyArea_AttachEntity ===
Attaches an entity to a sticky area. The entity must have a physics body.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asArea</code> || name of sticky area.
|-
| <code>asEntity</code> || name of entity.
|-
| <code>asBody</code> || name of specific body on entity, if left as an emtpy string, the main body will be used.
|}

== 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|SOMA scripting]]
* [[HPL3/SOMA/Scripting/Scripting Api|SOMA scripting API]]

[[Category:English]]

HPL3/SOMA/Scripting/Areas Helper - Revision history

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