TiMan: Expand the practical source walkthrough and clarify how to use the handler.

2026-10-02T12:32:06Z

Expand the practical source walkthrough and clarify how to use the handler.

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

2026-10-02T12:18:02Z

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

New page

{{shortPageTitle}}

The Eye Tracking Handler registers entities and exposes gaze, blink and extended-view data. IsAvailable checks whether the eye-tracking engine is installed; IsActive checks whether eye tracking is active. Entity registration makes an entity available for gaze queries.

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

=== EyeTracking_IsAvailable ===
If the eye tracking engine is installed

In <code>script/modules/MenuHandler.hps</code>, SOMA calls <code>EyeTracking_IsAvailable</code> as follows.

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

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

=== EyeTracking_RegisterEntity ===
Registers an entity for eye tracking

=== EyeTracking_RegisterEntity ===
Registers an entity for eye tracking

=== EyeTracking_IsEntityBeingLookedAt ===
If the specified entity is being looked at

=== EyeTracking_IsEntityBeingLookedAt ===
If the specified entity is being looked at

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

@@ Line 24: / Line 24: @@
 This is an excerpt from that stock script; its referenced names and variables belong to that script.
-=== EyeTracking_RegisterEntity ===
+=== Register a target, then query it ===
-Registers an entity for eye tracking
+The transport-station map registers <code>AmyTalkTrigger</code> in <code>maps/chapter01/01_04_transport_station/01_04_transport_station.hps</code>:
-=== EyeTracking_RegisterEntity ===
+In the map’s <code>Update</code> callback, the registered target is queried by the same name:
-=== EyeTracking_IsEntityBeingLookedAt ===
+<syntaxhighlight lang="cpp">
-If the specified entity is being looked at
+if (EyeTracking_IsEnvironmentReactive() && EyeTracking_IsEntityBeingLookedAt("AmyTalkTrigger") && mbSpottedAmy == false)
-=== EyeTracking_IsEntityBeingLookedAt ===
+Gaze zoom is controlled separately from the event call: the handler changes the player’s field-of-view multiplier to <code>0.85f</code> when its tracking threshold is exceeded within the zoom distance, and restores it to <code>1.0f</code> when tracking drops below the threshold or the target moves beyond that distance.
 == Check your change ==

HPL3/SOMA/Scripting/Eye Tracking Handler - Revision history

TiMan: Expand the practical source walkthrough and clarify how to use the handler.

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