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

2026-10-02T12:17:13Z

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

New page

{{shortPageTitle}}

The Player Hands Handler loads and animates the first-person hand model. Helpers select a hand entity, play its animation and optionally attach the camera to a model socket; human, diving and deep-sea model helpers supply stock entity paths.

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

=== PlayerHands_SetHandModel_Human ===

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

<syntaxhighlight lang="cpp">
PlayerHands_SetHandModel_Human();
</syntaxhighlight>

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

=== PlayerHands_PlayAnimation ===

In <code>maps/chapter02/02_05_theta_inside/02_05_theta_inside.hps</code>, SOMA calls <code>PlayerHands_PlayAnimation</code> as follows.

<syntaxhighlight lang="cpp">
PlayerHands_PlayAnimation(sAnim, false, true, 1.0f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asAnim</code> || <code>sAnim</code>
|-
| <code>abLoop</code> || <code>false</code>
|-
| <code>abFullScaleModel</code> || <code>true</code>
|-
| <code>afFadeTime</code> || <code>1.0f</code>
|}

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

=== PlayerHands_AttachCameraToSocket ===

In <code>maps/chapter03/03_02_omicron_inside/03_02_omicron_inside.hps</code>, SOMA calls <code>PlayerHands_AttachCameraToSocket</code> as follows.

<syntaxhighlight lang="cpp">
PlayerHands_AttachCameraToSocket("Socket_Camera", 1.0f, "", true,true,1.0f);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asBoneName</code> || <code>"Socket_Camera"</code>
|-
| <code>afFadeTime</code> || <code>1.0f</code>
|-
| <code>asFadeOverCallback</code> || <code>""</code>
|-
| <code>abDisablePlayer</code> || <code>true</code>
|-
| <code>abAutoDetach</code> || <code>true</code>
|-
| <code>afDetachTime</code> || <code>1.0f</code>
|}

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

== 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/Scripting/User Modules Overview|User modules]]
* [[HPL3/SOMA/Scripting/Modules Helper|SOMA module helpers]]

[[Category:English]]

HPL3/SOMA/Scripting/Player Hands Handler - Revision history

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