Precipitation¶

Defines a precipitation based storm (rain, snow, etc).

Inherit:: GameBase

Description¶

Defines a precipitation based storm (rain, snow, etc).

The Precipitation effect works by creating many ‘drops’ within a fixed size box. This box can be configured to move around with the camera (to simulate level-wide precipitation), or to remain in a fixed position (to simulate localized precipitation). When followCam is true, the box containing the droplets can be thought of as centered on the camera then pushed slightly forward in the direction the camera is facing so most of the box is in front of the camera (allowing more drops to be visible on screen at once).

The effect can also be configured to create a small ‘splash’ whenever a drop hits another world object.

Example:

// The following is added to a level file (.mis) by the World EditornewPrecipitation( TheRain )
{
   dropSize = "0.5";
   splashSize = "0.5";
   splashMS = "250";
   animateSplashes = "1";
   dropAnimateMS = "0";
   fadeDist = "0";
   fadeDistEnd = "0";
   useTrueBillboards = "0";
   useLighting = "0";
   glowIntensity = "0 0 0 0";
   reflect = "0";
   rotateWithCamVel = "1";
   doCollision = "1";
   hitPlayers = "0";
   hitVehicles = "0";
   followCam = "1";
   useWind = "0";
   minSpeed = "1.5";
   maxSpeed = "2";
   minMass = "0.75";
   maxMass = "0.85";
   useTurbulence = "0";
   maxTurbulence = "0.1";
   turbulenceSpeed = "0.2";
   numDrops = "1024";
   boxWidth = "200";
   boxHeight = "100";
   dataBlock = "HeavyRain";
};

Methods¶

void Precipitation::modifyStorm(float percentage, float seconds)¶

Smoothly change the maximum number of drops in the effect (from current value to numDrops * percentage ). This method can be used to simulate a storm building or fading in intensity as the number of drops in the Precipitation box changes.

Parameters:	percentage – New maximum number of drops value (as a percentage of numDrops). Valid range is 0-1. seconds – Length of time (in seconds) over which to increase the drops percentage value. Set to 0 to change instantly.

Example:

%percentage = 0.5;  // The percentage, from 0 to 1, of the maximum drops to display
%seconds = 5.0;     // The length of time over which to make the change.
%precipitation.modifyStorm( %percentage, %seconds );

void Precipitation::setPercentage(float percentage)¶

Sets the maximum number of drops in the effect, as a percentage of numDrops . The change occurs instantly (use modifyStorm() to change the number of drops over a period of time.

Parameters:	percentage – New maximum number of drops value (as a percentage of numDrops). Valid range is 0-1.

Example:

%percentage = 0.5;  // The percentage, from 0 to 1, of the maximum drops to display
%precipitation.setPercentage( %percentage );

void Precipitation::setTurbulence(float max, float speed, float seconds)¶

Smoothly change the turbulence parameters over a period of time.

Parameters:	max – New maxTurbulence value. Set to 0 to disable turbulence. speed – New turbulenceSpeed value. seconds – Length of time (in seconds) over which to interpolate the turbulence settings. Set to 0 to change instantly.

Example:

%turbulence = 0.5;     // Set the new turbulence value. Set to 0 to disable turbulence.
%speed = 5.0;          // The new speed of the turbulance effect.
%seconds = 5.0;        // The length of time over which to make the change.
%precipitation.setTurbulence( %turbulence, %speed, %seconds );

Fields¶

bool Precipitation::animateSplashes¶: Set to true to enable splash animations when drops collide with other surfaces.

float Precipitation::boxHeight¶: Height (vertical dimension) of the precipitation box.

float Precipitation::boxWidth¶: Width and depth (horizontal dimensions) of the precipitation box.

bool Precipitation::doCollision¶: Allow drops to collide with world objects. If animateSplashes is true, drops that collide with another object will produce a simple splash animation.

int Precipitation::dropAnimateMS¶: Length (in milliseconds) to display each drop frame. If dropAnimateMS lt = 0, drops select a single random frame at creation that does not change throughout the drop’s lifetime. If dropAnimateMS gt 0, each drop cycles through the the available frames in the drop texture at the given rate.

float Precipitation::dropSize¶: Size of each drop of precipitation. This will scale the texture.

float Precipitation::fadeDist¶: The distance at which drops begin to fade out.

float Precipitation::fadeDistEnd¶: The distance at which drops are completely faded out.

bool Precipitation::followCam¶: Controls whether the Precipitation system follows the camera or remains where it is first placed in the scene. Set to true to make it seem like it is raining everywhere in the level (ie. the Player will always be in the rain). Set to false to have a single area affected by rain (ie. the Player can move in and out of the rainy area).

ColorF Precipitation::glowIntensity¶: Set to 0 to disable the glow or or use it to control the intensity of each channel.

bool Precipitation::hitPlayers¶: Allow drops to collide with Player objects; only valid if doCollision is true.

bool Precipitation::hitVehicles¶: Allow drops to collide with Vehicle objects; only valid if doCollision is true.

float Precipitation::maxMass¶: Maximum mass of a drop. Drop mass determines how strongly the drop is affected by wind and turbulence. On creation, the drop will be assigned a random speed between minMass and minMass .

float Precipitation::maxSpeed¶: Maximum speed at which a drop will fall. On creation, the drop will be assigned a random speed between minSpeed and maxSpeed .

float Precipitation::maxTurbulence¶: Radius at which precipitation drops spiral when turbulence is enabled.

float Precipitation::minMass¶: Minimum mass of a drop. Drop mass determines how strongly the drop is affected by wind and turbulence. On creation, the drop will be assigned a random speed between minMass and minMass .

float Precipitation::minSpeed¶: Minimum speed at which a drop will fall. On creation, the drop will be assigned a random speed between minSpeed and maxSpeed .

int Precipitation::numDrops¶: Maximum number of drops allowed to exist in the precipitation box at any one time. The actual number of drops in the effect depends on the current percentage, which can change over time using modifyStorm() .

bool Precipitation::reflect¶: This enables precipitation rendering during reflection passes.

bool Precipitation::rotateWithCamVel¶: Set to true to include the camera velocity when calculating drop rotation speed.

int Precipitation::splashMS¶: Lifetime of splashes in milliseconds.

float Precipitation::splashSize¶: Size of each splash animation when a drop collides with another surface.

float Precipitation::turbulenceSpeed¶: Speed at which precipitation drops spiral when turbulence is enabled.

bool Precipitation::useLighting¶: Set to true to enable shading of the drops and splashes by the sun color.

bool Precipitation::useTrueBillboards¶: Set to true to make drops true (non axis-aligned) billboards.

bool Precipitation::useTurbulence¶: Check to enable turbulence. This causes precipitation drops to spiral while falling.

bool Precipitation::useWind¶: Controls whether drops are affected by wind.