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

2026-10-02T12:11:52Z

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

New page

{{shortPageTitle}}
{{stub}}

The Player Pickup Handler moves a prop toward a point in front of the camera over the requested pickup duration. It interpolates position and orientation, applies the resulting transform in PostUpdate and calls the named completion callback with the prop name.

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

== Use the helper ==
<syntaxhighlight lang="cpp">
#include "helpers/helper_player.hps"
</syntaxhighlight>

=== Player_PickupProp ===
Initializes and starts a "pickup" animation for a the prop passed as argument.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asPropName</code> || name of the prop that will be animated.
|-
| <code>asCallback</code> || name of the function that will be called when animation is done. Syntax "void MyFunc(const tString &in asEntity)".
|-
| <code>afTimeToPickup</code> || the total time of the animation.
|}

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

== Still to expand ==
The helper and module implementation explain interpolation and the completion callback, but a shipped campaign caller was not found. A complete pickup scene still needs verification.

== See also ==
* [[HPL3/Scripting/User Modules Overview|User modules]]
* [[HPL3/SOMA/Scripting/Modules Helper|SOMA module helpers]]

[[Category:English]]

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

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