TPW FOG - Foggy breath for Arma3 SP

Authors: tpw, falcon_565, meatball, neoarmageddon
Requires: Community Base Addons for Arma 3
Compatibility: SP only

Description
-----------
TPW FOG started out as a simple mod to add foggy breath to units in cold weather on Altis/Stratis, but has since evolved into a more comprehensive climate system allowing region specific immersive weather effects including foggy breath, ground fog, snow, heat haze, dust storms, and ground mist effects for any maps.

Features
--------
	- Automatically applied region specific climates modelled on real world data. 
	- Ground fog, and foggy breath on all units within a specified radius of the player, based on realistic temperature and relative humidity calculations.
	- Increased chance of snowfall during colder months. 
	- Ground heat haze / mirage effects during hot weather.
	- Dewpoint based ground mist fx for tropical/jungle and cold winter environments. 
	
Dust Storms
-----------
TPW FOG allows you to manually spawn dust storms of the required intensity and duration using the function tpw_fog_fnc_duststorm. This function combines setviewdistance and setfog for visibility reduction, and particle efects to simulate billowing clouds of dust. tpw_fog_fnc_duststorm can greatly enhance immersion on desert and middle eastern maps, and can be configured to give a more foggy/smoky appearance which add to battle ambience on any map.

	- tpw_fog_fnc_duststorm may be run from the debug shell, script, trigger etc. Parameters: [storm_ time_minutes, fog_thickness, dust_opacity]
	- Only one storm may run at once, if you try to spawn a second storm it will quit with a message to this effect.
	- Storms will restore fog and viewdistance settings to their pre storm values upon completion.
	- You may cancel a storm at any time with the command tpw_fog_dustactive = 0;
	- Dust storm temporarily suspend TPW FOG's other fog related behaviours.

Because each map's lighting and fog configs are different, there is no one size fits all set of parameters for automatically spawning storms using these effects. You will need to experiment! Examples:

	[30, 0.1, 0.1] spawn tpw_fog_fnc_duststorm; // 30 minute mild dust storm
	[30, 0.4, 0.1] spawn tpw_fog_fnc_duststorm; // 30 minute fog/smoky/smoggy 
	[10, 0.5, 0.4] spawn tpw_fog_fnc_duststorm; // 10 minute dust heavy storm, significantly reduced visibility  
	[5, 0.8, 0.8] spawn tpw_fog_fnc_duststorm; // 5 minute apocalyptic storm, poor visibilty
	
Be aware that it takes roughly 30 seconds for a storm to activate or deactivate. 

Ground mist
-----------
TPW FOG can generate immersive gound mist/steam which is particularly effective on tropical/jungle maps such as Tanoa, but also works well on cold maps. Mist is more dynamic than engine based fog, as clouds of mist ebb/flow and move in the wind and react to the environment and lighting.  

The system utilises the dewpoint calculations of TPW FOG, so that mist will only form if the temperature drops below the dewpoint. In the tropics the dewpoint is often 25 deg C (ie extremely humid), but if the temperature is 30 deg C there won't be mist. To make it work in the jungle the number of trees within 200 m of the player are counted and the dewpoint increased by 1 degC for every 100 trees (to simulate the increased humidity from transpiration). So on a 30 deg C day with a dewpoint of 25 deg C, there shouldn't be mist around towns or out in the open fields, however in dense jungle the dewpoint might be 33 deg C. Et voila, mist. Similarly if it becomes heavily overcast or rains, and the temperature drops below 25 deg C, then you'll get mist. 

Mist thickness is dynamic: the heavier the overcast/rain, the heavier the mist. The greater the difference between the dewpoint and the actual temperature, the heavier the mist. The more trees, the heavier the mist. This means you might barely see mist on the beach at jungle's edge, but will see thicker and thicker mist the further you move into the jungle, particularly if it starts to rain. You are less likely to see heavy mist during the middle of the day when the temperature is higher.

By default the automatic mist system is activated, but may be deactivated in the tpw_mods.hpp:

	tpw_fog_mist = 0; // ground steam/mist fx in tropical/jungle and cold environments. 0 = no mist, 1 = extremely thick mist. Recommended = 0.04

Automatic mist can also be activated at any time during gameplay by setting tpw_fog_mist > 0 using the debug shell, scripts or triggers.

Lastly, mist can be called manually at your desired thickness regardless of humidity and temperature. Examples:

	[30,0.04] spawn tpw_fog_fnc_mist; // moderate mist for 30 minutes
	[10,0.5] spawn tpw_fog_fnc_mist; // very thick mist for 10 minutes
	[20,0.01] spawn tpw_fog_fnc_mist; // very subtle mist for 20 minutes
	
Mist (and dust) functions rely on BIS particle effects which inevitably consume some resources and may affect framerate, so use at your discretion. Be aware that the large particles used for these effects may display some slight visual anomalies depending on the angle of the player's gaze, an engine limitation I cannot work around without massively increasing the FPS hit.	

Snow
----
Should TPW FOG determine that climate conditions are conducive to it, light snow will fall around the player. The code for this has recently been extensively overhauled and optimised for increased realism and performance. Snow flakes will not fall through cover, so that you may stand inside a building and watch the snow continue to only fall outside. Or stand outside in the snow looking through a window to see no snow inside. Snowflakes occasionally melt on the player's goggles in first person view. Combined with TPW FOG's ground and mist functions this gives a great boost to immersion on cold winter maps.

Realistic snow relies on determining whether a given snowflake's spawn position has unobscured line of sight to the ground. Regardless of the precalculations and other optimisations employed, snow particles are CPU demanding in themselves and the default settings will cost a couple of FPS. By default TPW FOG changes the snow density every few minutes up to a maximum tpw_fog_snowdensity of 10 (light snow). You can manually change tpw_fog_snowdensity in the debug shell. Values < 10 will result in lighter snow, values greater than 10 give heavier snow. 500 would give very heavy snow, with a significant hit to FPS. To have heavier snow fall for 5 minutes, enter the following into the debug shell:  

	tpw_fog_snowtime = time + 300;
	tpw_fog_snowdensity = 50;

By default, snow will not always fall even when it's cold and cloudy enough. Snow functions can be forced on at any time using: 
	[] spawn tpw_fog_fnc_snow; 
	
Even if this function is running, snow will only fall if sufficiently overcast (> 0.5) and sufficiently cold (< 10degC). 	
	
How it works
------------
	- TPW MODS assigns the current map to one of several climatic regions: Arctic (eg Namalsk); Central Asian (eg Takistan); Mediterranean (eg Altis); Middle Eastern / Desert (eg Fallujah); Middle European (eg Chernarus); Nordic (eg Thirsk); Tropical (eg Tanoa).  
	- Each region uses simplified temperature, dew point and snowfall model based on real climate data from weatherspark.com. 
	- The average daily maximum temperature is modelled sinusoidally over the year. The same sine wave is applied to daily minimum temperature, daily maximum dew point, and daily minimum dew point. This approximates the way these values vary over a year. Some additional randomisation is applied to these values to simulate daily variation in weather. 
	- The chance of snowfall is modelled sinusoidally, peaking during the coldest month.
	- Generally speaking, the lowest temperature is roughly around 0600, and the highest at 1800. Conversely, the highest humidity (and thus dew point) is at 0600 and the lowest at 1800. These values are also modelled sinusoidally.
	- Dew point (en.wikipedia.org/wiki/Dew_point) is the temperature below which the air has 100% relative humidity (saturated) and moisture will condense out. In TPW FOG, if the air temperature falls below the dew point + 2.5 deg C, ground fog will form. Ground fog is thicker closer to sea level.
	- Foggy breath is more complicated, so I've chosen a simple scenario: breath (leaving the mouth at 35 deg C and 95% relative humidity) will condense if mixed with air colder than 12 deg C and greater than 50% relative humidity (www.sciencebits.com/ExhaleCondCalc). Dew point + 10 deg C is approximately 50% relative humidity. In TPW FOG, if the air temperature is less than dew point + 10 deg C, and also less than 12 deg C, breath will fog. 
	- Depending on the climate region, snow has an increased chance of falling during colder months.
	- When the temperature is greater than 25 deg C and the sky is clear (overcast < 0.8), heat haze can be observed when the player is prone.	
	
Issues
------	
	- Entering "tpw_fog_debug=true" in the debug shell will allow you to examine the climate region, temperature, dewpoint and chance of snow.  
	- Foggy breath is disabled in vehicles, due to a limitation with the attachto command.
	- Foggy breath is only applied to humans, not any nearby animals.
	- Although the visual breathing rate is increased as fatigue increases, it will not match the breathing sounds correctly.
	- Snow replaces rain, so you won't see both at once. However, the snow function uses "0 setrain 0" on a 2 second loop, so you might still see the occasional drop of rain.
	- In order for snow to not fall through cover, in-game wind strength is set to 0 when snow is falling, to prevent snow particles from drifting sideways through walls etc. 
	- Snow will not fall if the air temperature is greater than 10 deg C or when cloud cover (overcast) is less than 0.5, or when the player is underwater. Snow will not be spawned if the FPS is lower than 25.
	- Snow is dynamically spawned in a circle around the player, with additional snow spawned in teh direction of travel. A faster moving player thus cannot outrun the spawned snow. Beyond 20 kmh (in vehicles) the system switches to using a simple snow emitter box in the immediate vicinity of the player so that some snow particles are visible regardless of speed. 
	- Heat haze is not visible through 3D scopes (engine limitation), similarly snow fx are not visible through certain glass types.
	- Ground fog will override mission fog settings.
	- If you want to modify this system to change the climate data or the breath/snow/haze effects, then you'll have to dive into the script version.
	- SP only