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

2026-10-02T12:22:25Z

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

New page

{{shortPageTitle}}

Player states select the current player interaction or control mode. SOMA registers normal control, grab, push, terminal interaction, conversation and custom-controls states, among others. The custom-controls helper installs named callbacks for look, movement, actions and leaning before changing the player state.

== States ==
{| class="wikitable"
! Name !! ScriptFile !! ScriptClass
|-
| <code>State_Normal</code> || <code>player/PlayerState_Normal.hps</code> || <code>cScrPlayerState_Normal</code>
|-
| <code>State_Interact_Grab</code> || <code>player/PlayerState_Interact_Grab.hps</code> || <code>cScrPlayerState_Interact_Grab</code>
|-
| <code>State_Interact_Push</code> || <code>player/PlayerState_Interact_Push.hps</code> || <code>cScrPlayerState_Interact_Push</code>
|-
| <code>State_Interact_Wheel</code> || <code>player/PlayerState_Interact_Wheel.hps</code> || <code>cScrPlayerState_Interact_Wheel</code>
|-
| <code>State_Interact_Slide</code> || <code>player/PlayerState_Interact_Slide.hps</code> || <code>cScrPlayerState_Interact_Slide</code>
|-
| <code>State_Interact_SwingDoor</code> || <code>player/PlayerState_Interact_SwingDoor.hps</code> || <code>cScrPlayerState_Interact_SwingDoor</code>
|-
| <code>State_Interact_Lever</code> || <code>player/PlayerState_Interact_Lever.hps</code> || <code>cScrPlayerState_Interact_Lever</code>
|-
| <code>State_Interact_Tear</code> || <code>player/PlayerState_Interact_Tear.hps</code> || <code>cScrPlayerState_Interact_Tear</code>
|-
| <code>State_Interact_Terminal</code> || <code>player/PlayerState_Interact_Terminal.hps</code> || <code>cScrPlayerState_Interact_Terminal</code>
|-
| <code>State_Interact_HandheldTerminal</code> || <code>player/PlayerState_Interact_HandheldTerminal.hps</code> || <code>cScrPlayerState_Interact_HandheldTerminal</code>
|-
| <code>State_Interact_Read</code> || <code>player/PlayerState_Interact_Read.hps</code> || <code>cScrPlayerState_Interact_Read</code>
|-
| <code>State_Interact_MovingButton</code> || <code>player/PlayerState_Interact_MovingButton.hps</code> || <code>cScrPlayerState_Interact_MovingButton</code>
|-
| <code>State_Ladder</code> || <code>player/PlayerState_Ladder.hps</code> || <code>cScrPlayerState_Ladder</code>
|-
| <code>State_ClimbLedge</code> || <code>player/PlayerState_ClimbLedge.hps</code> || <code>cScrPlayerState_ClimbLedge</code>
|-
| <code>State_InteractiveCameraAnimation</code> || <code>player/PlayerState_InteractiveCameraAnimation.hps</code> || <code>cScrPlayerState_InteractiveCameraAnimation</code>
|-
| <code>State_Sit</code> || <code>player/PlayerState_Sit.hps</code> || <code>cScrPlayerState_Sit</code>
|-
| <code>State_Conversation</code> || <code>player/PlayerState_Conversation.hps</code> || <code>cScrPlayerState_Conversation</code>
|-
| <code>State_Dead</code> || <code>player/PlayerState_Dead.hps</code> || <code>cScrPlayerState_Dead</code>
|-
| <code>State_Interact_ZoomArea</code> || <code>player/PlayerState_Interact_ZoomArea.hps</code> || <code>cScrPlayerState_Interact_ZoomArea</code>
|-
| <code>State_CustomControls</code> || <code>player/PlayerState_CustomControls.hps</code> || <code>cScrPlayerState_CustomControls</code>
|-
| <code>State_Null</code> || <code>player/PlayerState_Null.hps</code> || <code>cScrPlayerState_Null</code>
|}

== MoveStates ==
{| class="wikitable"
! Name !! ScriptFile !! ScriptClass
|-
| <code>MoveState_Normal</code> || <code>main/MoveState_Normal.hps</code> || <code>cScrMoveState_Normal</code>
|-
| <code>MoveState_Climb</code> || <code>main/MoveState_Climb.hps</code> || <code>cScrMoveState_Climb</code>
|-
| <code>MoveState_Dead</code> || <code>main/MoveState_Dead.hps</code> || <code>cScrMoveState_Dead</code>
|}

== 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_ChangeStateToCustomControls ===
Changes the player state so that the normal controls are used for something else.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asLookInputCallback</code> || Overrides look controls. If false is returned, normal controls are overridden. Syntax: bool F(const cVector2f &in avLookAmount)
|-
| <code>asMoveInputCallback</code> || Overrides move controls. If false is returned, normal controls are overridden. Syntax: bool F(const cVector2f &in avMoveAmount)
|-
| <code>asActionInputCallback</code> || Overrides action input. If false is returned, normal controls are overridden. Syntax: bool F(int alAction, bool abPressed)
|-
| <code>asLeanInputCallback</code> || Overrides lean input. If false is returned, normal controls are overridden. Syntax: bool F(float afAmount)
|}

In <code>maps/chapter05/05_01_phi_inside/05_01_phi_inside.hps</code>, SOMA calls <code>Player_ChangeStateToCustomControls</code> as follows.

<syntaxhighlight lang="cpp">
Player_ChangeStateToCustomControls("LoaderArm_Look", "LoaderArm_Move", "LoaderArm_Action", "LoaderArm_Lean");
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asLookInputCallback</code> || <code>"LoaderArm_Look"</code>
|-
| <code>asMoveInputCallback</code> || <code>"LoaderArm_Move"</code>
|-
| <code>asActionInputCallback</code> || <code>"LoaderArm_Action"</code>
|-
| <code>asLeanInputCallback</code> || <code>"LoaderArm_Lean"</code>
|}

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

[[Category:English]]

HPL3/SOMA/Scripting/Player States - Revision history

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