HPL3/SOMA/Level Design/Environment Particles

Environment particles add a field of textured particles to a level. SOMA’s underwater maps use them with the shipped waterdust_tiny_3x3.dds texture. The renderer turns the particle faces toward the camera and wraps their positions inside a box, so this is a repeating particle field.

Find the controls

Open Level Settings and select its Env Particles tab. Active toggles the particles, Color tints them, and Brightness controls how bright that tint appears.

The SOMA editor also contains controls labelled Texture, Box Size, Box Distance, Num Particles, Particle Size, SubDivs, Affected by light, Num of iterations, Gravity Velocity, Wind Velocity, Rotate Velocity, Fade In and Fade Out. The following example gives the authored map values rather than treating them as editor defaults.

Reproduce the Delta particle settings

Use a map inside your own mod, with the working editor/save/launch setup from Edit Your First Map. The example below copies only Delta’s environment-particle settings; Delta’s fog, lighting and other map settings are separate.

1. Close the mod map in the editor before editing its .hpm file.
2. Open your mod’s maps/sample_map/sample_map.hpm in a text editor. Inside GlobalSettings, replace its EnvParticles element with the following element from maps/chapter02/02_03_delta/02_03_delta.hpm.
3. Reopen the mod map in LevelEditor.exe and inspect the Env Particles tab. The texture is populated and the particles are active, whereas the bundled sample map stores an empty texture and Active="false".

<EnvParticles
    Color="0.898438 0.959534 1 1"
    Brightness="0.3"
    BoxDistance="0.1"
    GravityVelocity="0 0.01 0"
    GravitySpeedRandomAmount="0"
    WindVelocity="0 0 0"
    WindSpeedRandomAmount="0"
    WindDirRandomAmount="0"
    RotateVelocity="0.005 0.005 0.005"
    RotateSpeedRandomAmount="1"
    RotateBothDirs="true"
    NumIterations="2"
    FadeInStart="0.1"
    FadeInEnd="1"
    FadeOutStart="10"
    FadeOutEnd="16"
    BoxSize="10"
    NumParticles="3000"
    ParticleSize="0.08 0.08"
    SubDivUV="3 3"
    AffectedByLight="false"
    Texture="particles/underwater/materials/waterdust_tiny_3x3.dds"
    Active="true"
/>

1. Save the mod map and launch it. The particle field uses the small underwater-dust texture and the pale blue tint from the copied settings.
2. Make one visible comparison in the Env Particles tab: turn Active off, save, and restart the map; then turn it on again and repeat. This checks the particle layer separately from fog and other effects. Use the development loop for restarting and reading errors.

Read the example

• Texture references a shipped texture under particles/underwater/materials/; it is a texture filename, not a .ps particle-system file.
• NumParticles="3000", ParticleSize="0.08 0.08" and SubDivUV="3 3" are Delta’s authored values. They are not a recommended count or a universal preset.
• GravityVelocity="0 0.01 0", WindVelocity="0 0 0" and RotateVelocity="0.005 0.005 0.005" are distinct motion parameters. The script API has separate setters for all three.
• The fade-in begins at distance 0.1 and finishes at 1; fade-out begins at 10 and finishes at 16. These are distance thresholds, not durations. The map helpers document their meaning, and the rendering shader computes their effect from particle depth.

Let a script change the field

Map scripts can change the particle field after the map loads. Include helpers/helper_map.hps alongside your existing map-script includes. The Delta map enables the field with:

Map_SetEnvironmentParticlesActive(true);

During its transition towards Theta Outside, the same stock script fades all matching particle layers to a new color and brightness:

Map_FadeEnvironmentParticleColor("*", cColor(0.295,0.556,0.59,1.0), 7);
Map_FadeEnvironmentParticleBrightness("*", 1, 7);

Here "*" selects all particle layers. The last argument is the fade duration; the Map Effects Handler accumulates elapsed update time for these fades. These calls alter existing layers rather than define their texture, particle count or box size.

If the particles disappear

• Check both the saved Active value and map-script calls: stock SOMA scripts can enable or disable the field at runtime.
• Check that the texture exists; the worked example uses particles/underwater/materials/waterdust_tiny_3x3.dds.
• Check the fade distances. A particle at the fully faded-out distance contributes no visible alpha.
• Check clipping when using water areas. The Liquid area definition exposes EnvParticlesToClip for naming the layers constrained to that area, and accepts wildcards and space-separated names.

Still to expand

The exact units and ranges for the motion and randomization controls, the meaning of Box Distance and iteration count, and a visually verified editor demonstration still need documentation. The stock values above establish an authored setup, not those undocumented semantics.

See also

• Level Settings
• Map scripting helpers
• Fading level effects