TPW MODS README
===============

In the months following the release of Arma 3 alpha I wrote a number of mods which did different things, but all of which had a common goal of increasing the immersion and realism of the single player experience in Arma 3. As the number of mods and their complexity increased, I found it increasingly difficult to keep track of feedback on multiple threads and maintain them all separately, so I took the decision to bundle them all into one addon, imaginatively titled TPW MODS. TPW MODS consists of a number of independently configurable components, and if you use them all you'll get:

Infantry realism:
-----------------
	- Units reacting realistically to suppressive fire by ducking/going prone and seeking cover (TPW EBS)*.
	- Units reacting to falls and bullet hits by falling/ragdolling to the ground (TPW FALL).
	- Units continuing to bleed from injuries, resulting in decreased mobility and eventually incapacitation and death if not treated (TPW BLEEDOUT).
	- Units able to self heal using First Aid Kits (TPW BLEEDOUT).
	- Units rapidly reacting to nearby enemies they have line of sight to (TPW LOS)*.
	- Sounds for jumping, falling, rolling and turning prone, sounds for freefalling and under canopy (TPW FALL).
	- Plausible 2035 mesh networked HUD with range and predictive targetting, bullet trajectory tracing, electrochromic tinting, positional audio ping of nearest enemies, and full colour night vision, when equipped with tactical goggles (TPW HUD).
	- Ambient infantry combat, with AI able to call in support (TPW SKIRMISH).
	- More realistic (slower) movement and stance change speeds.

* Deprecated due to engine improvements

Civilians:
----------
	- Region specific civilians in towns, walking around and interacting with each other, reacting to weather and gunfire (TPW CIVS).
	- Denser CPU friendly civilian crowds along the side of the road and near houses (TPW CROWD).
	- Civilian traffic, which you may commandeer (TPW CARS).
	- Civilian cars parked by the side of the road near habitable houses (TPW PARK).
	- Civilian boats (TPW BOATS).
	- Ohally's CAF Aggressors Middle Eastern and African civilians, RDS A2 Eastern European civilians and cars, and Leight's Opfor Pack Middle Eastern civilians will be used appropriately if present.
	- Maxjoiner's women will be used as female civilians on Greek and European maps, if the mod is present.

Ambience:
---------
	- Lights in civilian houses at night (TPW HOUSELIGHTS).
	- Working streetlights on A2/OA maps (TPW STREETLIGHTS)**.
	- Appropriate sized flocks of sheep/goats/chickens, and randomly barking dogs / yowling cats (TPW ANIMALS).
	- Occasional helicopter and jet flybys, with automatic support for 3rd party aircraft mods (TPW AIR).
	- Ambient environmental noises (voices, traffic, radio, louspeakers), with support for user added sounds/music (TPW SOAP). 
	- Mosques playing the Azan call to prayer at appropriate times, with prayer response from nearby houses (TPW SOAP).
	- Nearby gunfire eliciting screaming, babies crying and dogs barking, from houses near the player (TPW SOAP).
	- Creaking doors/timbers in houses, with whistling wind and rattling windows in windy conditions (TPW SOAP).
	- Ambient radio chatter when on foot, and in/near vehicles, with support for Russian radio chatter in RHS Russian vehicles (TPW RADIO).
	- Civs/animals/cars/parked cars/radio/houselights/streetlights/sounds easily excluded from areas of the map using triggers.
	- Glowing blinking animated fireflies on warm summer evenings (TPW FIREFLIES).
	- Ambient furniture in enterable Tanoan and Altian houses and buildings (TPW FURNITURE).

** Deprecated due to CUP Terrains implementing working streetlights

Weather:
--------
	- Region specific climate (TPW FOG).
	- Ground fog, units with foggy breath, and a chance of snow, during colder weather (TPW FOG).
	- Ground heat haze / mirage effects during hot weather (TPW FOG).
	- Dust storm functionality which may be called via script or trigger (TPW FOG).
	- Dynamic ground mist reacting to humidity, tree cover, and rainfall (TPW FOG).
	- Dynamic snow which will not fall through buildings/ cover, snow goggle fx, snow fx in vehicles (TPW FOG).
	- Rain droplet effects on the ground near the player (TPW RAINFX).
	- Refractive rain droplet effects on car windscreens and player goggles (TPW RAINFX).
	- Puddles on the ground around the player during and after rain (TPW PUDDLE).

All mods interoperate well, and share a common startup hint. All mods are light on resources and a lot of work has gone into optimising them so they should not cause undue slowdowns or framerate issues. You can use the TPW MODS of your choice to enhance existing missions and campaigns, or to simply turn any empty map into a living breathing combat zone with endless replayability.

INSTALLATION
============
TPW MODS installation is no different to countless other mods, you need to merely install the addon folder and a folder containing the configuration files, and activate the mod using the method of your choice. 

	- You'll need the latest version of Community Base Addons A3 (CBA A3) for the addon to launch and function properly.
	- The simplest way to install TPW MODS is to extract the contents of TPW_MODS_20XXXXXXX.zip to a temporary location and then click on install.bat to automatically copy TPW MODS and its required files to the correct Arma3 location. The installer will also handle updating your TPW_MODS.hpp configuration file with any new variables.
	- Alternatively, manually extract the @TPW_MODS and @CBA_A3 modfolders to your preferred mod location. By default this would be \your_steam_location\steamapps\common\Arma 3
	- The @TPW_MODS addon can be easily activated using the Arma3 launcher, or in-game via the Configure -> Expansions menu. Alternatively, right click on Arma3 in your Steam menu, select Properties and then select Set Launch Options in the Arma3 Properties popup window. Add the following: -mod=@CBA_A3;@TPW_MODS into the field of the Launch Options popup.


INCLUDED FILES
==============
By default your @TPW_MODS\addons directory should contain the following pbos and bisigns.

	- ebs.pbb
	- ebs.pbo.tpw.bisign
	- flay.pbo
	- flay.pbo.tpw.bisign
	- tpw_ambience.pbo
	- tpw_ambience.pbo.tpw.bisign
	- tpw_azan.pbo
	- tpw_azan.pbo.tpw.bisign	
	- tpw_animspeed.pbo
	- tpw_animspeed.pbo.tpw.bisign
	- tpw_hud.pbo
	- tpw_hud.pbo.tpw.bisign
	- tpw_mods.pbo
	- tpw_mods.pbo.tpw.bisign
	- tpw_puddle.pbo
	- tpw_puddle.tpw.bisign
	- tpw_sounds.pbo
	- tpw_sounds.pbo.tpw.bisign


CONFIGURATION
==============
TPW MODS does is not run/configured via editor placed modules, but configured via an HPP config file using variables which may also be changed in-game.

TPW MODS is extremely configurable and has a lot of options which are available in the TPW_MODS.hpp file. This file contains sensible defaults and is heavily annotated so that you may configure the individual mods on/off and adjust their variables. Additional information and configuration options for each mod are contained in @TPW_MODS\docs, and in the links at the bottom of the TPW MODS webpage https://forums.bistudio.com/topic/154944-tpw-mods-v20161008-enhanced-realism-and-immersion-for-arma-3-sp/.

Copy @TPW_MODS\userconfig\TPW_MODS\TPW_MODS.hpp to \Your_Arma3\userconfig\TPW_MODS\TPW_MODS.hpp. You may need to create the \Your_Arma3\userconfig\TPW_MODS\ directory if it does not already exist. Please be aware that installing TPW MODS using PlaysWithSix may sometimes place TPW_MODS.hpp into the incorrect location.

You then have 3 choices for modifying tpw_mods.hpp

	1 - Manually using a text editor such as Notepad++ https://notepad-plus-plus.org

	2 - tpw_settings.py, a simple text based python script which allows you to quickly make changes to any variables. You'll need Python 2.7 for Windows, 32-bit: https://www.python.org/ftp/python/2.7.11/python-2.7.11.msi or 64 bit: https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi . Copy @TPW_MODS\userconfig\TPW_MODS\tpw_settings.py to \Your_Arma3\userconfig\TPW_MODS\tpw_settings.py and double click to run it. 

	3 - TPW SETTINGS.jar, a full Java GUI written by Gliptal https://github.com/Gliptal/TPW-Settings
	Please do not try to edit your latest hpp using anything other than the latest version of TPW SETTINGS.jar, as you may corrupt your tpw_mods.hpp. You will need Java 8 https://java.com/en/download/ or greater to run TPW Settings.jar. Many thanks to Gliptal for his continuing support for TPW Settings. TPW SETTINGS.jar is not included in the TPW MODS download by default, you will need to download and install it to \Your_Arma3\userconfig\TPW_MODS\TPW SETTINGS.jar
	
Please be aware that incorrectly editing or corrupting your tpw_mods.hpp may crash TPW MODS or Arma3 itself. I take no responsibility for this.	

RUNNING TPW MODS FROM SCRIPTS
=============================
In addition to the addon, the mods are provided as scripts which can be run on a per mission basis, and examined and modified to suit you (see disclaimer below). TPW MODS scripts are not truly stand alone however. To successfully run TPW MODS scripts you will need to disable/remove tpw_mods.pbo from your Arma3 startup, but retain tpw_azan.pbo, tpw_ambience.pbo, tpw_azan.pbo, tpw_hud.pbo and tpw_sounds.pbo, which provide assets and config data that the scripts will require. Running script versions without disabling the addon versions can and will lead to conflicts and unexpected behaviours as they fight for the same variables. You will also need to run the tpw_core.sqf, which provides functions that the other scripts need. Instructions and parameters for launching each script are provided in the header of each script itself.

ASSIGNING TPW MODS TO DIFFERENT PARTS OF A MAP
==============================================
The following variables can be used to activate/inactivate the various TPW MODS ambient life behaviours whilst the game is running:

- tpw_animal_active = true/false
- tpw_boat_active = true/false
- tpw_car_active = true/false
- tpw_civ_active = true/false
- tpw_firefly_active = true/false
- tpw_fog_active = true/false
- tpw_furniture_active = true/false
- tpw_houselights_active = true/false
- tpw_park_active = true/false
- tpw_radio_active = true/false
- tpw_skirmish_active = true/false
- tpw_soap_active = true/false
- tpw_streetlights_active = true/false

For example, setting tpw_animal_active=false in the debug shell will prevent new animals from spawning (but won't remove existing animals). This behaviour can be automated using triggers. Let's say you want to exclude all ambient life stuff from a 5km x 5km northeast corner of Altis. In the editor create a rectangular 5000x5000 trigger (but of course it can be any shape, size and angle you require), place it over the appropriate northeast area of the map, and set it thusly:

	Type: None
	Activation: BLUFOR, repeatedly,present
	Condition: vehicle player in thislist && time > 10;
	On act. : tpw_animal_active = false;tpw_boat_active=false;tpw_car_active = false;tpw_civ_active = false;tpw_firefly_active = false;tpw_houselights_active = false;tpw_park_active = false;tpw_radio_active = false;tpw_skirmish_active = false; tpw_soap_active = flase; tpw_streetlights_active = false
	On dea. : tpw_animal_active = true;tpw_boat_active=true;tpw_car_active = true;tpw_civ_active = true;tpw_firefly_active = true; tpw_houselights_active = true;tpw_park_active = true;tpw_radio_active = true;tpw_soap_active = true; tpw_skirmish_active = true;tpw_streetlights_active = true

MULTIPLAYER COMPATIBILITY
=========================
TPW MODS are primarily designed with single player in mind, and are generally player centric, spawning ambience and behaviour around the player to conserve CPU and give the illusion of a living map. As I have stressed many times, they are advertised as SP mods. I only play SP, have little interest in playing MP, little skill in coding MP, and no ability to test it. What this means for you is that:

	- All mods will work as advertised in SP.
	- Some of them will work without issues in MP when running clientside on the players' computers, some will not.
	- None of them will work on a dedicated server, they will detect it and disable themselves.

MP client compatible:
---------------------
These mods are specifically written so that spawned ambient people/animals/vehicles are shared between multiple players. If there are 10 players in a single small town, there won't be 10 times as many civilians/cars/parked cars/animals/boats/aircraft.

	- TPW AIR
	- TPW ANIMALS
	- TPW BLEEDOUT
	- TPW BOATS
	- TPW CARS
	- TPW CIVS
	- TPW PARK
	- TPW RADIO
	- TPW STREETLIGHTS

These mods have no specific MP code, but should work anyway (warning - not tested).

	- TPW HUD
	- TPW HOUSELIGHTS
	- TPW SOAP
	- TPW FIREFLIES
	- TPW FURNITURE
	
MP Incompatible:
----------------
These mods have no specific MP code written into them and while some may appear to function in MP, they may give unpredictable results as each player's version of the script fights for variables, tries to assign randomness, assigns sounds/lights to objects etc etc. 

	- TPW EBS
	- TPW FALL
	- TPW FOG
	- TPW LOS	
	- TPW PUDDLE
	- TPW RAINFX
	- TPW SKIRMISH

If you desperately want a fully functioning MP or dedi version of any of my mods, and can't wait for me to make it happen, then you are welcome to grab the code and knock yourself out (see disclaimer below though). 

COMPATIBILITY WITH OTHER MODS
=============================
TPW MODS encompasses a very wide range of Arma3 functionality and no doubt will run into compatibility issues with other mods that attempt similar things. I make zero apologies for this. I make every effort to ensure that TPW MODS does not cause undue conflicts with the mods I use, but I'm not a mind reader and can't allow for all the mods you use. TPW MODS provides an enormous amount of options and it's up to you to disable a particular TPW MOD or a facet of its behaviour. 

	- AGM: if you experience a frozen player character, please remove tpw_animspeed.pbo from your TPW MODS installation
	- Blastcore: if you observe missing particle fx on HE and other explosions, please remove ebs.pbo from your TPW MODS installation

ISSUES
======
TPW MODS is in constant development, and you are encouraged to regularly check for updates.

	- As always I welcome feedback. My mods only improve due to your input. However, input which consists of asking me why there is no proper MP or dedicated server version, without offering help in this department, improves nothing, especially my temper.
	- I'll repeat yet again - these are SP mods, some of which I've been able to give MP functionality after many requests. Accordingly, I have zero interest in hearing your opinions about TPW MODS negatively impacting your MP gameplay (eg TPW HUD is cheating).
	- TPW MODS will work on Arma2 maps via CUP Terrains, though may not be optimal depending on the various house classes on these maps.
	- TPW MODS will cause up to 30 seconds of jerky framerates after mission initialisation as it scans for houses and roads, and spawns and sets waypoints for people and vehicles. Once fully initialised there should be no further interruptions to framerate.
	- TPW MODS may change the atmosphere/dynamics of the official campaign, particularly as regards ambient civilians/traffic. Personally I'd advise playing the campaign through once without any mods.


TO DO
=====
I've been solidly developing TPW MODS for three years and although my enthusiasm waxes and wanes, I never stop thinking of ways to improve and extend it. Some of the things I'm considering:

	- Script version to over-ride/disable addon version
	- Start collaborating with real coders so TPW MODS can be ported MP and dedi

FEEDBACK AND BUG REPORTS
========================
For the sake of my sanity, when you're reporting bugs and issues can you please tell me:

	- Arma3 version (stable or dev)
	- 32 or 64 bit exe
	- Version of the specific mod
	- Script or addon version
	- Downloaded from Dropbox, Armaholic or PW6
	- Running on SP, MP or dedi

Also, please check that you have \your_steam_location\steamapps\common\Arma 3\userconfig\TPW_MODS\TPW_MODS.hpp.

THANKS
======
I have so many people to thank for their help, advice, support, feedback and friendship that I can't list them all. The incredible Arma community is what makes this game worth contributing to. Thanks everyone. 

DISCLAIMER
==========
I totally refuse to accept responsibility for anything that might happen to your game/computer/life as a result of using my mods. 

If you accept this, then feel free to use and modify this code, on the proviso that you post back changes and improvements so that everyone can benefit from them, and acknowledge the original author (tpw) in any derivative works. Wrapping my unacknowledged work up inside your pbo addon and monetising it does not count as returning it to the community.