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

2026-10-02T12:21:11Z

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

New page

{{shortPageTitle}}

A SOMA user module combines a script class with a native module object. This guide traces the Light Flash Handler so you can recognize the two interfaces and call the module from a map script.

== Follow a stock module ==
# Open <code>script/modules/LightFlashHandler.hps</code>. Its class inherits the base, callback interface and its own typed interface:

<syntaxhighlight lang="cpp">
class cScrLightFlashHandler : iScrUserModule, iScrUserModule_Interface, iScrLightFlashHandler_Interface
</syntaxhighlight>

# Read <code>script/interfaces/UserModule_Interface.hps</code>. <code>iScrUserModule</code> stores the native <code>cLuxUserModule</code> in <code>mBaseObj</code>; <code>SetupBaseInterface</code> assigns it and <code>GetBase()</code> returns it.
# Read <code>script/modules/ModuleInterfaces.hps</code>. <code>iScrLightFlashHandler_Interface</code> declares the module’s <code>Add</code> operation. This typed interface is the contract used by the helper, rather than the lifecycle callback interface.
# Follow the position overload of <code>LightFlash_Add</code> in <code>helpers/helper_modules.hps</code>:

<syntaxhighlight lang="cpp">
iScrLightFlashHandler_Interface @LFHandler = cast<iScrLightFlashHandler_Interface>( cLux_GetUserModuleFromID(eModuleType_LightFlashHandler) );
return LFHandler.Add(afTime, afFadeInTime, afFadeOutTime, avTargetPos, aColor, afRadius, afBrightness);
</syntaxhighlight>

The helper retrieves the registered module, casts it to the typed interface and calls <code>Add</code>. A map script can use the helper without repeating that lookup and cast; see [[HPL3/SOMA/Scripting/Light Flash Handler|the light-flash example]].

== Make your own module ==
Follow [[HPL3/Scripting/User Modules Overview|User Modules Overview]] for the class, callbacks and <code>Modules.cfg</code> entry. Match the configured class name to your script class and use a unique module ID. SOMA’s inspected configuration already uses IDs 0–20, including 20 for the Eye Tracking Handler.

== See also ==
* [[HPL3/SOMA/Scripting/Modules Helper|Calling stock modules]]

[[Category:English]]

HPL3/SOMA/Scripting/Module Interface - Revision history

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