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

2026-10-02T12:09:20Z

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

New page

{{shortPageTitle}}

The Ai helper file in SOMA is <code>script/helpers/helper_ai.hps</code>.

AI helpers call entity components for movement, pathfinding, senses, voices and head tracking. Pathfinder_MoveToNode requires an entity with a Pathfinder component and broadcasts EndOfPath when its path completes.

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

=== Pathfinder_MoveToNode ===
Moves an entity containing a Pathfinder component to a node. The entity message eLuxEntityMessage_EndOfPath is broadcasted when complete.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asEntityName</code> || name of the entity with the pathfinder.
|-
| <code>asNodeName</code> || name of the node to move to.
|-
| <code>asCallbackFunc</code> || The name of callback called when end is reach. Syntax: void Func(const tString& in asEntityName, bool abReachedEnd)
|-
| <code>afUpdateFreq</code> || The number of times per second that the path will be updated. O or below means never update.
|-
| <code>abExactStopAtEnd</code> || If the goal node should be hit exactly.
|-
| <code>asResultCallbackFunc</code> || The name of callback called when the pathfinding has been performed. Syntax: void Func(bool abSuccesful)
|}

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

<syntaxhighlight lang="cpp">
Pathfinder_MoveToNode("Leviathan", "LeviathanTarget");
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asEntityName</code> || <code>"Leviathan"</code>
|-
| <code>asNodeName</code> || <code>"LeviathanTarget"</code>
|}

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

=== Pathfinder_Track_Add ===
Adds a track node to be followed.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asEntityName</code> || name of the entity with the pathfinder.
|-
| <code>asNodeName</code> || Name of the path node to be added.
|-
| <code>afMinWaitTime</code> || minimum time before the entity moves to the next node.
|-
| <code>afMaxWaitTime</code> || maximum time before the entity moves to the next node. If <0, then the value will be same as afMinWaitTime
|-
| <code>asAnimName</code> || animation played when at node, per entity.
|-
| <code>abLoopAnim</code> || if the animtion should be looped, per entity.
|}

In <code>maps/chapter04/04_01_tau_outside/04_01_tau_outside.hps</code>, SOMA calls <code>Pathfinder_Track_Add</code> as follows.

<syntaxhighlight lang="cpp">
Pathfinder_Track_Add("LightBot","LightNode_"+i);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>asEntityName</code> || <code>"LightBot"</code>
|-
| <code>asNodeName</code> || <code>"LightNode_"+i</code>
|}

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

=== Pathfinder_Track_Start ===
Starts a track

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asEntityName</code> || name of the entity with the pathfinder.
|-
| <code>abLoop</code> || if the path should loop
|-
| <code>afUpdateFreq</code> || the frequency at which the path is recculated
|-
| <code>asEndOfTrackCallback</code> || Callback called when path is over. Syntax: void MyFunc(const tString& in asEntityName)
|}

== 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/SOMA/Scripting|SOMA scripting]]
* [[HPL3/SOMA/Scripting/Scripting Api|SOMA scripting API]]

[[Category:English]]

HPL3/SOMA/Scripting/Ai Helper - Revision history

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