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

2026-10-02T12:06:28Z

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

New page

{{shortPageTitle}}

The Player helper file in SOMA is <code>script/helpers/helper_player.hps</code>.

Player helpers control the player’s movement, camera, interactions, tools and health. For scripted camera attention, StartLookAt turns toward a named entity and StopLookAt ends that turn.

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

=== Player_StartLookAt ===
Rotate the player camera towards the positon of an entity/area.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asEntityName</code> || name of the entity/area to rotate camera towards.
|-
| <code>afAcc</code> || acceleration of the camera movement.
|-
| <code>afSpeedMul</code> || distance towards camera multiplied with this value sets the camera speed.
|-
| <code>afMaxSpeed</code> || maximum speed of camera movement.
|}

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

<syntaxhighlight lang="cpp">
Player_StartLookAt("ARK", 1, 1, 3);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asEntityName</code> || <code>"ARK"</code>
|-
| <code>afAcc</code> || <code>1</code>
|-
| <code>afSpeedMul</code> || <code>1</code>
|-
| <code>afMaxSpeed</code> || <code>3</code>
|}

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

=== Player_StopLookAt ===
Stop rotating the camera towards a target specified with Player_StartLookAt()

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afDeacc</code> || deacceleration of the camera movement. 0 means 'stop now'
|}

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

<syntaxhighlight lang="cpp">
Player_StopLookAt(2);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>afDeacc</code> || <code>2</code>
|}

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

=== Player_SetInteractionAllowed ===
Turn on or off the player's ability to interact with the world.

== 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 ARK example points the camera toward the <code>ARK</code> entity. The helper first resolves that name: a missing entity returns without turning the camera, and an entity without a physics body or mesh produces an error. Use <code>Player_StopLookAt</code> to stop the scripted turn.

== See also ==
* [[HPL3/SOMA/Scripting|SOMA scripting]]
* [[HPL3/SOMA/Scripting/Scripting Api|SOMA scripting API]]

[[Category:English]]

HPL3/SOMA/Scripting/Player Helper - Revision history

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