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

2026-10-02T12:11:57Z

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

New page

{{shortPageTitle}}
{{stub}}

Terrain particles are material-based sprites distributed around the player. Fixed-axis sprites follow the surface orientation and point sprites face the player; the range setup controls fading and wrapping, while force and wind setup controls movement.

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

== Use the helper ==
<syntaxhighlight lang="cpp">
#include "helpers/helper_modules.hps"
</syntaxhighlight>

=== TerrainParticles_SetupRange ===
Sets up the maximum and minimum distance that the particles are visible
Particles also wrap around the maximum distance, coming out on the other side if they get to far away
This should be called before spawning particles to get the best spread

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>afRangeMinStart</code> || particles closer than this value will not be visible
|-
| <code>afRangeMinEnd</code> || particles between min start and min end will fade to fully visible
|-
| <code>afRangeMaxStart</code> || particles further away then this value will start to fade out
|-
| <code>afRangeMaxEnd</code> || particles further away then this will not be visible and will be spawned on the other side of the player
|}

=== TerrainParticles_SetupParticles ===
Spawn particles that use the specified material
There are two kind of particles. FixedAxis sprites follow the rotation of the surface. PointSprite always look at the player.

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>asMaterial</code> || the mat file used by the particles
|-
| <code>alFixedAxisCount</code> || the number of FixedAxis particles to spawn
|-
| <code>afFixedAxisSizeMin</code> || smallest size of a FixedAxis particle
|-
| <code>afFixedAxisSizeMax</code> || largest size of a FixedAxis particle
|-
| <code>avFixedColorMin</code> || random color bound of the FixedAxis particle
|-
| <code>avFixedColorMax</code> || random color bound of the FixedAxis particle
|-
| <code>alPointSpriteCount</code> || the number of PointSprite particles to spawn
|-
| <code>afPointSpriteSizeMin</code> || smallest size of a PointSprite particle
|-
| <code>afPointSpriteSizeMax</code> || largest size of a PointSprite particle
|-
| <code>avPointColorMin</code> || random color bound of the PointSprite particle
|-
| <code>avPointColorMax</code> || random color bound of the PointSprite particle
|}

=== TerrainParticles_SetupForces ===
Setup forces that affect the particles

{| class="wikitable"
! Parameter !! Meaning
|-
| <code>avVelocityLimit</code> || limit to velocity of the particles
|-
| <code>afGravityAmount</code> || how much gravity should affect the particles, value between 0.0-1.0
|-
| <code>afRandomDirectionForce</code> || the amount of random force that should be appled to the particles, the direction of this force is based on position and changes over time
|-
| <code>afRandomDirectionFrequency</code> || how fast the direction of the random force changes
|}

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

== Still to expand ==
The helper and module implementations define setup and motion, but a shipped campaign caller was not found. A complete map setup and visual verification are still needed.

== See also ==
* [[HPL3/Scripting/User Modules Overview|User modules]]
* [[HPL3/SOMA/Scripting/Modules Helper|SOMA module helpers]]

[[Category:English]]

HPL3/SOMA/Scripting/Terrain Particle Handler - Revision history

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