TPW PUDDLE - Ambient water puddles during and after rain

Author: tpw
Requires: CBA A3, tpw_core.sqf, tpw_puddle.pbo
Compatibility: SP

Description
-----------
It's probably escaped no-one's attention that while Arma3's recent sea water handling is beautiful, its fresh water handling remains totally lacklustre - it's just raindrops. And without any mods raindrops are visualised but do not interact with objects in any way, there is no wetting of surfaces, no rain splash or ripple effects, no puddles, no freshwater streams and no ponds, dams and larger bodies of fresh water. TPW RAINFX has addressed rain splash on ground, windscreens and player goggles, and now TPW PUDDLE allows fresh water puddles to form during rain and for some time after it stops. I've had the idea for ambient puddles for several years and am pleased to finally be able to offer it in finished mod form. 

TPW PUDDLE works by dynamically spawning custom small pond objects with simple water shaders within a defined radius around the player. Puddles will only spawn on relatively flat outdoor ground surfaces, only during rain and for a user specified amount of time after the rain stops. Puddles are removed when the player moves out of range. Puddles are true water objects, they are transparent and somewhat reflective, you'll splash when running through them and they send up a plume of water if you shoot them.

The overall effect greatly increases immersion (get it, immersion?!?!?) on raining and wet maps.

Usage:
------
By default TPW PUDDLE will spawn up to 8 puddles within a 10-50m radius of the player, when rain exceeds 0.2, and for 10 minutes after the rain stops. You can of course change all these parameters, but be aware that large numbers of pond objects can impact performance. 

You can force puddles to always appear by setting tpw_puddle_rainthresh to -1.

By default TPW PUDDLE uses a simple static water shader based pond object, which does not ripple. If you'd like rippling puddles then set tpw_puddle_ripple = 1 (but see issues below). 

TPW PUDDLE objects can be found in the editor as PUDDLE_S, PUDDLE_M, PUDDLE_L, PUDDLERIPPLE_S, PUDDLERIPPLE_M, PUDDLERIPPLE_L and can be manually placed on any map as desired. S, M and L puddles are approximately 1, 3 and 10m across respectively. 

Issues:
-------
Although they seem simple, I've actually put a serious amount of effort into modelling and config wrangling the puddles. O2 is rather arcane to me, water object documentation is extremely scarce, and I've relied mainly on a couple of forum posts by DeanosBeano for inspiration. Arma2 and custom maps have offered pond objects for some time, but shrinking the concept down to small surface puddles tends to run up against the limits of Arma3's fresh water shading technology. The default static water puddles generally tend to look somewhat realistic, but in some circumstances can look a little like a sheet of glass. The rippling puddles use the "calmwater" pixel and vertex shaders and can look more realistic under some circumstances, but often display absent or completely inappropriate reflection colours depending on their angle of view. Even more disconcertingly, they are affected by the wave parameter which is in turn affected by the degree of overcast, and will thus appear to wave up and down by up to 20cm during a storm! Rippling puddles need to be spawned 10cm above the surface to appear to have any depth and reflection, and to not periodically disappear into the ground. For this reason they are disabled by default. I'm continuing to investigate ways to get better looking water shaders into the puddles (and any tips would be appreciated).

Early pre release versions of TPW PUDDLE caused serious framerate issues, mainly due to spawning/removing the ponds, and using the isflatempty command to find appropriate places to put them. I got around this by a) pre-spawning puddles and just moving them around as required, and b) writing my own custom terrain flatness determination function. As a result default settings for TPW PUDDLE should cause little impact on FPS. Be aware though that water shaders are more CPU/GPU taxing than other shaders and using large puddle numbers will kill your framerate regardless of optimisations.

Puddles will generally appear away from the player's direct gaze, though will occasionally pop in, particularly if you are running. Given the amount of texture, clutter and LOD popping in the game, a few puddles appearing is par for the course so I'm probably not going to waste CPU cycles with pre spawning visibility calculations.

Puddles are designed as transient static decorative objects and thus I've not written code to take into account factors such as gradient water flow, wind and temperature based evaporation, animals drinking, cigarette butts floating etc. 

Thanks
------
DeanosBeano for pond object inspiration.