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

2026-10-02T12:12:56Z

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

New page

{{shortPageTitle}}

The Attack Meter Handler manages entity-based threats and player damage sequences. AddInstance uses start and end distances for the threat, while AutoDamage schedules damage after a delay. Custom and after-damage callbacks allow a map to replace or continue the damage sequence.

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

=== AttackMeter_AddInstance ===
Adds an entity as something that is about to damage the player.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>a_idEntity</code> || ID for the entity
|-
| <code>afStartDistance</code> || How close entity needs to be before the attack meter starts.
|-
| <code>afEndDistance</code> || How close the entity needs to be for the player to take damage
|-
| <code>afDamage</code> || How much damage will the attack take?
|-
| <code>abFatal</code> || Whether this attack is fatal.
|-
| <code>abFastNonLookKill</code> || If true, the entity will damage quickly even if the player isn't looking at it.
|-
| <code>abInstantKnockOut</code> || if true, the player will be knocked out on the first attack
|}

In <code>script/custom_depth/agent_construct_worker.hps</code>, SOMA calls <code>AttackMeter_AddInstance</code> as follows.

<syntaxhighlight lang="cpp">
AttackMeter_AddInstance(mBaseObj.GetID(), 4, 2, 0.2);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>a_idEntity</code> || <code>mBaseObj.GetID()</code>
|-
| <code>afStartDistance</code> || <code>4</code>
|-
| <code>afEndDistance</code> || <code>2</code>
|-
| <code>afDamage</code> || <code>0.2</code>
|}

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

=== AttackMeter_SetAfterDamageCallback ===
This sets a callback that is called after taken daming.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asCallback</code> || The callback function to be used. Syntax: void f(const tString& in asSource)
|}

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

<syntaxhighlight lang="cpp">
AttackMeter_SetAfterDamageCallback("VentBotDamage");
</syntaxhighlight>

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

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

=== AttackMeter_RemoveInstance ===
Removes an entity as something that is about to damage the player.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>a_idEntity</code> || ID for the entity
|}

In <code>maps/chapter02/02_06_theta_tunnels/02_06_theta_tunnels.hps</code>, SOMA calls <code>AttackMeter_RemoveInstance</code> as follows.

<syntaxhighlight lang="cpp">
AttackMeter_RemoveInstance(Map_GetEntity(msElevatorPuppet).GetID());
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>a_idEntity</code> || <code>Map_GetEntity(msElevatorPuppet).GetID()</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/Attack Meter Handler - Revision history

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