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

2026-10-02T12:09:52Z

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

New page

{{shortPageTitle}}

The Props helper file in SOMA is <code>script/helpers/helper_props.hps</code>.

Prop helpers include opening swing doors with impulses, querying the grabbed prop and setting selected entities’ interaction icons. Grab_GetGrabbedProp returns null when no prop is grabbed.

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

=== SwingDoor_PushOpen ===
Pushes a door open using one or many impulses

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || name of the door.
|-
| <code>afImpulseAmount</code> || Amount of impulse that will be applied to the door.
|-
| <code>alNumOfTimes</code> || Number of times the impulse will be applied.
|-
| <code>afTimeBetweenPushes</code> || Pause interval between two impulses.
|}

In <code>maps/chapter04/04_02_tau_inside/04_02_tau_inside.hps</code>, SOMA calls <code>SwingDoor_PushOpen</code> as follows.

<syntaxhighlight lang="cpp">
SwingDoor_PushOpen(asTimer, 0.02, 90,0.2);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asName</code> || <code>asTimer</code>
|-
| <code>afImpulseAmount</code> || <code>0.02</code>
|-
| <code>alNumOfTimes</code> || <code>90</code>
|-
| <code>afTimeBetweenPushes</code> || <code>0.2</code>
|}

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

=== Grab_GetGrabbedProp ===
Returns the currently grabbed prop, or null if there isn't one.

In <code>script/props/Prop_Grab.hps</code>, SOMA calls <code>Grab_GetGrabbedProp</code> as follows.

<syntaxhighlight lang="cpp">
cLuxProp@ pProp = Grab_GetGrabbedProp();
</syntaxhighlight>

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

=== Entity_SetCustomInteractIcon ===
Sets the interaction icon for an entity. Currently only works for MoveBody,
MoveableButton, Lever, Rigid and Triggers.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asName</code> || name of the entity.
|-
| <code>aIcon</code> || The interaction icon.
|}

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

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