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

2026-10-02T12:10:43Z

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

New page

{{shortPageTitle}}

The ImGui helper file in SOMA is <code>script/helpers/helper_imgui.hps</code>.

ImGui helpers read GUI input and state, convert normalized coordinates into screen or group coordinates, and draw GUI widgets. Normalized positions use the 0–1 range; ImGui_GetSize returns the GUI screen size in pixels.

== Choose the GUI callback ==
For a terminal layout, put these GUI-coordinate and widget calls in the terminal’s OnGui callback. They work with the current GUI’s size and state. Follow [[HPL3/SOMA/Scripting/Terminals Overview|the terminal tutorial]] to connect the callback to a terminal before adding its layout.

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

=== ImGui_GetSize ===
Get the size (in pixels) of the GUI screen

In <code>maps/02_06_theta_tunnels_old/02_06_theta_tunnels.hps</code>, SOMA calls <code>ImGui_GetSize</code> as follows.

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

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

=== ImGui_NrmPos ===
Input should be normalized, 0-1, and a position in screen space is returned.

In <code>maps/chapter05/05_02_ARK_inside/05_02_ARK_inside.hps</code>, SOMA calls <code>ImGui_NrmPos</code> as follows.

<syntaxhighlight lang="cpp">
cVector3f vPos = ImGui_NrmPos(1.0f, 0.5, 2);
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Value in this stock call
|-
| <code>avPos</code> || <code>1.0f</code>
|}

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

=== ImGui_NrmPos ===
Input should be normalized, 0-1, and a position in screen space is returned.

== 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/ImGui Helper - Revision history

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