TPW EBS - Engine Based Suppression for Arma3 SP

Authors: tpw
Requires: Community Base Addons for Arma 3, ebs.pbo
Compatibility: SP only

IMPORTANT: With the release of Arma3 1.42 and Marksmen DLC, the Arma engine now features native reaction to nearby projectiles! TPW EBS is now deprecated and disabled by default. 

Description
-----------
By default Arma3 (and all Arma games) have no true suppression mechanism: a unit under fire will ignore passing bullets unless they hit the ground nearby. This makes suppressive fire, a fundamental military tactic, essentially useless in Arma 3. 

My original attempt at TPW EBS tried to overcome this limitation by implementing a pseudo suppression eventhandler: an invisible massless 2-5 m radius "shell" object around each footbound unit which reacted to bullet hits whilst allowing those bullets to pass unhindered through it. Bullets passing through this shell were then used to determine the suppression status of the attached unit. While very nice in principle this concept eventually became unworkable - the shell was not passing through explosives, interacted with helicopter rotors, and due to A3 engine changes eventually started interacting with bullets again.  

Eventually I bowed to the inevitable and retired the shell concept in favour of an extremely light and simple SP only implementation of the bullet-centric approach to suppression, as pioneered by yours truly, Fabrizio_T and Ollem in TPWCAS. Using this approach, rather than a unit detecting bullets, every live bullet checks whether there are any units around it. The end result is largely the same and the new bullet-centric EBS functions identically (well, better actually) to the old shell one.

Some ideas are resistant to death however, and it seems that shell based suppression is one of them. Das Attorney redesigned the shell concept in such a way that it no longer interacted with bullets/rotors/explosions. This new improved shell was reimplemented as an option, allowing the user to either use the tried and true bullet-centric approach, or the more experimental and possibly more efficient shell approach which makes use of the low level engine collision detection routines. 

TPW EBS and is (and will probably remain) significantly less fully featured than its A2/A3 SP/MP/Dedi siblings TPWCAS (now maintained by master coder Ollem) and bDetect/bCombat (code magician Fabrizio_T). However even with a reduced feature set, it dramatically changes the dynamics of an engagement. If you want a full AI combat behaviour change package, look elsewhere.

Features
--------
	- Will work for all footbound units (civilian and combatant) within a specified radius of the player (default 500m).
	- Subsonic projectiles (eg pistol and silenced rifle) are ignored.
	- Units have 4 levels of suppression:
		0 = totally unsuppressed.
		1 = friendly fire.
		2 = light enemy fire, less than (default) 5 bullets each 5 sec.
		3 = heavy enemy fire, more than 5 bullets each 5 sec.
	- Suppression lasts from 5-10 sec.
	- Units under light fire will crouch, those under heavy fire will go prone if there is no nearby cover.
	- Units have their skills reduced by 25% under light enemy fire, 50% under heavy enemy fire, returning to pre-suppression level when non-suppressed.
	- Suppressed units will seek cover behind any nearby objects greater than 1m high.
	- Player may optionally exhibit suppression symptoms under enemy fire: increased breathing rate, increased weapon sway, slight vision blur.
	- Visual debugging can be enabled, which changes the colour of the units' uniforms and allows you to determine if the suppressed unit is behaving appropriately:
		0 = blue
		1 = green
		2 = yellow
		3 = red
	- Will disable itself if bDetect/bCombat are already running.

Additional configuration
------------------------
tpw_ebs_suptype = 0; // Suppression type. 0 = bullet centric, 1 = suppression shell object  

tpw_ebs_playersup = 1; // suppression effects applied to player. 0 = no player suppression
tpw_ebs_aisup = 1; // suppression effects applied to AI. 0 = no AI suppression
tpw_ebs_findcover = 1; // AI will seek cover when suppressed. 0 = will not seek cover

These 3 settings allow you to decide to what degree the player and AI are affected by suppression. If you set all three settings to 0, then TPW EBS will not affect AI/player at all, but will merely assign variables to each unit that you can use to write your own suppression effects. Unit's suppression state will be monitored and reset every 5-10 seconds.

	_unit getvariable "tpw_ebs_skill"; // skill prior to suppression
	_unit getvariable "tpw_ebs_stance"; // stance prior to suppression
	_unit getvariable "tpw_ebs_fatigue"; // fatigue prior to suppression 
	_unit getvariable "tpw_ebs_allbullets"; // all bullets
	_unit getvariable "tpw_ebs_enemybullets"; // enemy bullets
	_unit getvariable "tpw_ebs_supstate"; // suppression state (0 - 3)
	_unit getvariable "tpw_ebs_uptime"; // how long til unit is unsuppressed
	_unit getvariable "tpw_ebs_downtime"; // how long until unit reacts to bullet
	_unit getvariable "tpw_ebs_weptype"; // weapon type unit is holding
	
Known issues
------------
TPW EBS won't blow your computer up, but it may not function perfectly either. If you want the full SP/MP/Dedi suppression experience, use TPWCAS. If you are interested in trying an alternative simple lightweight SP suppression system, give TPW EBS a try.

	- TPW EBS makes use of a number of Arma 3 specific commands and won't work in A2.
	- No long term changes are made to unit skill/stance/stamina, these values are always restored to the value they were prior to suppression.  
	- No other behavioural changes are made, I prefer to let the engine make these decisions.
	- Find cover implemented but is extremely simple.
	- TPW EBS uses setunitpos to change unit stance, with an additional playmove animation of the changed stance to ensure that the stance actually changes. Both of these systems may be ignored by AI stance changes under certain combat situations however.
	- Player suppression effects are implemented entirely using setfatigue. This gives a reasonable approximation of the suppressed physical state via heavier breathing, aiming shake and slight visual blur. I've never been shot at in real life so can't confirm how realistic this is. 
	
Feedback
--------
Q - Why did you bother writing TPW EBS if there was another perfectly good suppression system in TPWCAS?!? 
A - Because I enjoy the coding challenge. I enjoyed being a part of TPWCAS and am in complete awe of the coding abilities of Fabrizio_T and Ollem in writing a script based bullet detection framework that works as beautifully as it does. But I have always felt there was merit in trying to exploit the optimised bullet collision routines of the game engine as an alternative way of registering suppression. I'm very pleased that Das Attorney was able to help me rescue this concept! 

There's been some, ahem, "strident" debate about the merits of player and AI suppression recently, which I refuse to engage in. If you want to voice your opinion of it to me then I suggest you:
	1 - read this: https://yourlogicalfallacyis.com/.
	2 - realise that shouting your opinion over and over won't magically make it a fact.
	3 - accept that this is an OPTIONAL addon made by a volunteer. I am not a BIS coder forcing my vision of suppression upon you.
	
	

Thanks
------
I am deeply indebted to the following talented gentlemen for their generosity and coding skills:
-Coulum-: original AI suppression concept which became TPWCAS. He's the "C" in TPWCAS!
Fabrizio_T: wrote the incredible bdetect bullet detection framework at the heart of TPWCAS.
Ollem: polished TPWCAS to a high gloss, made it MP and dedi compatible, and continues on as maintainer.    
Mrflay: invisible firegeometry object concept which I adapted to the suppression "shell" in the original TPW EBS.
Das Attorney: complete reimplementation of an optimised "shell", as well as invaluable support, encouragement and friendship. 