HPL3/SOMA/Scripting/Effects Overview

SOMA registers effect classes by name, script file and numeric ID. Effect helpers retrieve them through the Effect Handler and call a typed interface. Screen and post-processing effects include shake, depth of field, tone mapping and video distortion; the Gamepad effect instead handles controller rumble.

Registered effects

Name	ScriptFile	ScriptClass
Shake	effects/Effect_Shake.hps	cScrEffect_Shake
DoF	effects/Effect_DoF.hps	cScrEffect_DoF
ToneMapping	effects/Effect_ToneMapping.hps	cScrEffect_ToneMapping
ImageTrail	effects/Effect_ImageTrail.hps	cScrEffect_ImageTrail
Flash	effects/Effect_Flash.hps	cScrEffect_Flash
Screen	effects/Effect_Screen.hps	cScrEffect_Screen
ChromaticAberration	effects/Effect_ChromaticAberration.hps	cScrEffect_ChromaticAberration
RadialBlur	effects/Effect_RadialBlur.hps	cScrEffect_RadialBlur
VideoDistortion	effects/Effect_VideoDistortion.hps	cScrEffect_VideoDistortion
TimeGlitch	effects/Effect_TimeGlitch.hps	cScrEffect_TimeGlitch
Sway	effects/Effect_Sway.hps	cScrEffect_Sway
ImageFadeFX	effects/Effect_ImageFadeFX.hps	cScrEffect_ImageFadeFX
Gamepad	effects/Effect_Gamepad.hps	cScrEffect_Gamepad

Before you start

1. Open the map script inside your own mod. Keep its generated includes, cScrMap : iScrMap class and callback structure. See Add your first script if you have not edited a map script yet.
2. Add the helper include shown below alongside the script’s other includes.
3. 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

#include "helpers/helper_effects.hps"

Effect_Shake_Start

Makes the screen shake for a certain amount of time. Returns id to the current shaking. If several calls to shake has been made the largest one is used.

Parameter	Meaning
afAmount	The strength of the shake.
afTime	The time it shakes at full intensity (fade in and fade out are added to this).
afFadeInTime	The time before it reaches full strength.
afFadeOutTime	The time, after afTime is up, that it will take for the shake to reach zero strength.
avDirAmount	The amount it will shake in each direction in camera space
afFrequency	Times per seconds the shake will change offset. 0=every update (ie max).

In maps/chapter02/02_04_theta_outside/02_04_theta_outside.hps, SOMA calls Effect_Shake_Start as follows.

Effect_Shake_Start(0.2, 2, 12, 0);

Parameter	Value in this stock call
afAmount	0.2
afTime	2
afFadeInTime	12
afFadeOutTime	0

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

Check your change

Save the script and restart the map in development mode with F5. If the script fails, open F1 and use Show Error List or Show HPL Log. See the development loop for the launch and debugging steps.

See also

• Effect helpers
• Effect interface