==================================================================================================
------------------------------ Denton's Enhanced Doom3 -------------------------------------------
==================================================================================================

==================================================================================================
DLL related Changes in Detail (New gamex86.dll, for Windows only) -
==================================================================================================

Note that, this document includes information about changes that were introduced by newer version. For previous version features, please refer to readme_old.txt

---------------------------------------------------------
Table of content
---------------------------------------------------------
	1. New Bloomshader
	2. New WeaponFX System
	3. Real Tracers 2.0
	4. Ability to attach smokeParticles to any entity.
	5. Unified impact FX.
	6. Multiple projectile types per weapon.
	7. Other changes.
	8. Making a SP map compatibble with this mod
---------------------------------------------------------

---------------------------------------------------------------------------------------------------------
1. New Bloomshader: 
---------------------------------------------------------------------------------------------------------
The new bloom uses heavily modified use_less' bloomshader as base and is for DX9 compliant hardware only. There are three types of bloom now. The first two types support HDR like shift sensitivity (taken from maha_x's bloomshader). The shifting of sensitivity is not as perfect as HDR, it works much like oblivion's HDR based shift sensitivity effect. The new bloomshader not only is works better on low end systems (with DX9 hardware) but also can provide ultra high quality bloom for high end systems.

In an effort to make the bloom as user cnfigurable as possible, I had to add many new cvars which may make you feel overwhelmed at the beginning; but you'll get hang of them after a while. 

All these three types use two pass Gaussian blur with standard deviation 3.

When activated, there are some cvars you need to pay attention to:

r_bloom: Activates bloom. Defaults to 1.

0 - no bloom.
1 - bloom with sensitivity shifting and variable blur. Makes one extra blur pass.
2 - bloom with sensitivity shifting.
3 - Normal bloom (equivalent to use_less bloom when r_bloom is 3)

r_bloom_blurIterations: Number of iterations to apply bur. Default to 1.

r_bloom_buffer: sets buffer image size (in square pixels). Default to 4.
Larger the buffer size better the bloom quality.
1 - 64x32
2 - 128x64  
3 - 256x128
4 - 512x256  
5 - 1024x512

Following console variables work differently for the three types.

----------------
For r_bloom 3:
----------------
r_bloom_src_mult: The original, non blurred image is multiplied by this value.
Ranges from 0 to infinity, but each level above 1 requires an extra blend.

r_bloom_blur_mult: The blurred image is multiplied by this value.
Ranges from 0 to infinity, but each level above 1 requires an extra blend.

r_bloom_contrast: Chooses the type of contrast filter for the blurred image.
0: No contrast.  Acts like a crossfader.
1: modulate 2x.  Image is squared and then multiplied by four.
2: subtract.  Image is reduced by a constant.
----------------

----------------
For r_bloom 1 & 2:
----------------
r_bloom_src_mult: The original, non blurred image is multiplied by this value.
Ranges from 0 to infinity.

r_bloom_blur_mult: The blurred image is multiplied by this value.
Ranges from 0 to infinity.

Note that, r_bloom_src_mult and r_bloom_blur_mult now does not require any additional passes, since everything happens inside the shader programs.

r_bloom_contrast: Chooses the type of contrast filter for the blurred image.
0: No contrast.  
1:  Image is squared and then multiplied by r_bloom_contrast_mult.

Sensitivity shifting means, the bloom drops or rises based on whether you are looking at a bright area or dark area respectively.

r_bloom_shiftSensitivity_delay: Delay in milliseconds, that decides how slowly the bloom sensitivity should shift.
 0 - No delay.
-1 - Disables sensitivity shifting.

r_bloom_contrast_min and r_bloom_contrast_mult:
When sensitivity shifting is enabled, the bloom contrast varies between contrastImage x r_bloom_contrast_min and contrastImage x r_bloom_contrast_mult.
When sensitivity shifting is turned off, the bloom_contrast is always equal to contrastImage x r_bloom_contrast_mult.
r_bloom_contrast_mult defaults to 1.55, value may range from 0 to infinity.
r_bloom_contrast_min defaults to 0.1, value may range from 0 to infinity.
----------------

-------------------------------------------------------------
Recommended Bloom Settings:
-------------------------------------------------------------
For low-end systems:
set r_bloom to 2 or 3 
set r_bloom_buffer within range 1-3 (lower the number better the performance)
When r_bloom_buffer is set to less than 3, there is a noticeable bloom-contrast drop. To increase the contrast, first set r_bloom to 2 and then try increasing r_bloom_contrast_mult and r_bloom_src_mult a little. 

For mid-end systems:
These setting gives the most optimally good looking bloom.
set r_bloom to 1 or 2 
set r_bloom_buffer to 4 to get high quality bloom.
set r_bloom_blurIterations to 1 or 2 based on performance impact.

For High-end systems:
These setting gives the ultra high quality bloom and may cause noticeable performance drop.
set r_bloom to 1 or 2 
set r_bloom_buffer to 5 to get ultra high quality bloom.
set r_bloom_blurIterations within range 1-4 based on performance impact.
----------------------------------------------------------

Some more things to know:

r_bloom 1 gives a variable blur, where brighter areas blur more and less brighter areas blur less. It also provides excellent bloom contrast when r_bloom_buffer is set to high. It makes one extra blur pass than other two types. 

Many people increase the brightness levels in Doom 3. As a result, when the game crashes, their desktop brightness screws up. This can be avoided with the help of new bloom. First of all, go to menu screen, switch to windowed mode by pressing alt+enter. Now, go to options->system menu and start reducing the brightness until your desktop brightness comes to normal. Now load any map, and set r_bloom to 1 or 2. Try increasing r_bloom_contrast_mult and r_bloom_src_mult, until you get better contrast/brightness.


---------------------------------------------------------------------------------------------------------
2. New WeaponFX System
---------------------------------------------------------------------------------------------------------

The new weaponFX system let add any number of particle effects and lights to weapons in a really easy way. All you need to do is add some keys to weapon decls, that indicate name of the effect, bone to which they are to be attached, dir, offset etc. (See weapon_pistol decl and weapon_pistol.script for details)

Then thro' weapon scripts you can turn them on or off using the command:

startWeaponParticle("particleName");
stopWeaponParticle("particleName");
startWeaponLight("lightName");
stopWeaponLight("lightName");

Few more things to know:

There are two types of particles you can attach to a weapon bone, 
- smokeParticles
- general particles
smokeParticles are used for effects that involves trails e.g. muzzlesmoke effect. while general particles can be used for effects like flashlight, lasersight, muzzleflashes, you name it. ( Some more explanation regarding smoke particles v/s general particle can be found at the topic 5: Unified impact FX )

If a smoke particle is not continuous then it's not needed to be stopped using stopWeaponParticle() function, because it will stop automatically as soon as its time runs out. Where as a general particle, once started, needs to be explicitly stopped using the stopWeaponParticle regardless of whether it is continuous or not.


---------------------------------------------------------------------------------------------------------
3. RealTracers 2.0 
---------------------------------------------------------------------------------------------------------

This version introduces all new tracer logic for creating tracers and beams with customizable colors, size and speed etc. The tracer logic supports models (.lwo, .prt) as well as new customizable beam type. 
(See projectile_bullet_machinegun and projectile_plasmarail decl for details)

There are following types of tracers:
- tracers for view-origin launched projectiles.
- tracers for muzzle launched projectiles.
- tracers with different speed for view-origin launched projectiles.
Above three types supports any model(e.g.- .lwo, .ase, .prt) as visual tracer. You may also want to check out tracer.prt
- beam model based tracers for all above types (with customizable color, length, width etc)
- beam model based rail beam (with customizable attributes) and with rail beam smoke (for spiral like effect around beam)

Few more things to know if you are coding the DLL:
The new tracer logic mainly consists of two things, first, predicting the collision point before launching the projectile so that muzzle direction can b fixed to point accurately to what player is looking at; and second, creating a different tracerObject that represents the tracer.  

---------------------------------------------------------------------------------------------------------
4. Ability to attach smokeParticles to any entity
---------------------------------------------------------------------------------------------------------

 Added ability to attach smokeParticles to any entity: Ever wondered why all the hanging mummies, lying dead bodies or lying body parts(like dismembered hand, torso etc) never had blood spurting wound when shot at? Now, a smoke particle can be attached to any type of entity.

Doom 3 attaches smoke particles to actors upon projectile impact, but all the other entities couldn't have smoke particles attached to them. Now I have added some new code that lets every entity (including idBrittlefracture type) play an impact fx using smoke particles.

Some optimizations have been made to the original code that keeps track of smoke particle played on an idAnimatedEntity. Also, An issue that caused the smoke particle to completely miss some stages has been fixed. To see the difference, try playing with the DentonDllKit.pk4 only and you'd notice that, even the default impact effects(e.g. blood spurting wound, bullet ricochet effect etc) on entities look better now.  

---------------------------------------------------------------------------------------------------------
5. Unified impact FX
---------------------------------------------------------------------------------------------------------

Once above feature is added, unifying the impact fx was an easy task. Note that, I am referring sound + particle effect + decal applied to every entity when collided with a projectile as impact fx. Now, there is a unique impact fx for every different material type. The material based damage effects are now read from damage defs of projectiles for better understanding. (see damage_shotgun def for details)

Some more things to know if you are coding:

although the keys in damage defs have syntax: smoke_wound_<materialType>, this doesn't necessarily means that, every time the effect played upon projectile impact will be of smoke particles type. 

Explanation:
Smoke particles are particles that are emitted off of things that are constantly changing position and orientation, like muzzle smoke coming from a bone on a weapon, blood spurting from a wound, or particles trailing from a monster limb. The smoke particles are always evaluated and rendered each tic, so there is a performance cost with using them for continuous effects. Where as, the general particles are completely parametric, and have no performance overhead when not in view. Due to this, smoke particles are only played, as a part of impact fx, on entities that can change position; where as, entities which are static, always play general particle effects.

There were some issues related to impact sounds, where impact sounds played idEntity::AddDamageEffect and idAnimatedEntity::AddDamageEffect always played at different volume than impact sounds played by idProjectile::DefaultDamageEffect. As a result, when a projectile hits a metal surface on a monster body (e.g. helmet, shields etc), although plays the same sound shader when the projectile hits a metal surface of static objects; in the former case, sound is played with relatively low volume as compared to the volume of sound played in the later case. The reason behind this issue was, above three functions used different sound entities. Now, with the modified code, all the three functions above use the same sound entity.

---------------------------------------------------------------------------------------------------------
6. Multiple projectiles for a weapon
---------------------------------------------------------------------------------------------------------

# A weapon now can have more than one projectile type but consumes the same ammo type: E.g. plasmagun now has two different projectile types: plsama-balls, and plasma-rail beam. In the similar manner you can have different projectile type for rocket launcher, such as normal rockets and grenades etc. Each of the different projectile type can have different recoil for the same weapon.
(See projectile_plasmarail for more details)

---------------------------------------------------------------------------------------------------------
7. Other Changes:
---------------------------------------------------------------------------------------------------------

# New blood splat and blood pool decals: E.g. when a monster is hit by some shotgun pellets; in addition to flesh wounds some blood is splattered around those wounds making the monster's body bathed in blood. In addition to this, whenever you shoot a monster, there is a blood pool decal below his feet. 

Bloodpool decals are applied based on time intervals, this avoids excessive decal overlapping.
(see damage_shotgun def for details)

# Improved behavior of exploding and burning barrels: 
Fixed issue where exploding barrels did not apply splash damage correctly in some situations. Improved behavior of burning barrel so that it can explode  before it's burn time expires, when damaged severely. This makes them more useful when you want them to explode when enemies are near them.  

# Improved debris behavior:
 - Now debris trail can be made continuous or non-continuous (see debris_barrelpiece def).
 - Fixed an issue where idWeapon::event_ejectBrass use to set angular and linear velocity without referring to the decl values.
 - Now randomness of linear velocity and angular velocity for debris is controllable (see debris_brass def).
 - Now debris' linear velocity is added with ownerEntity's linear velocity. This not only gives better physics simulation in various situations but also fixes an issue where empty bullet casings used to eject without taking player's linear velocity into account.

# Added alternate fire key for weapons:
 - Added two new boolean variables to weapon_base.scripts, namely, WEAPON_SPECIAL, WEAPON_SPECIAL_HOLD. Where the former is used to get the key toggle status and the later is used to get button hold status. 

# Lots of bug fixes, improvements and optimizations:
 - Fixed a D3XP bug where, weapon::Event_useAmmo(int) consumed ammo from inventory ammo as well as from ammoclip (V2.02 change). 
 - g_debugdamage when set to 1, now dumps collision material information to console (see topic 8 below for details)
 - Added support for skyportals
 - Fixed a bug, where weapon would switch to plasmagun if soulcube not ready, where as, it should correctly switch to previous weapon.
 - Fixed axis of effect played  upon projectile collision.
 - Optimized calculations used to apply in idAnimatedEntity::AddLocalDamageEffect. 
 - Fixed issue where an idExplodingbarrel's particle model tried to track it's physics origin, even after freeing the physics object. 
 - Optimized the code, where idProjectile::think use to run physics even after the projectiles physics model freed.
 - Now, def_debris and def_shrapnel keys in projectile defs actually work.
 - Other minor changes. 
 
Previous version features can be found in readme_old.txt.

-------------------------------------------------------------------------------------------------
Making a SP map compatible with this mod
-------------------------------------------------------------------------------------------------
Basically, any SP map should work well with this mod. Only the thing is, if the map is using custom materials, a default smoke and spark effect will be used for all those. If you like this mod and you are making any SP maps that you might want to make compatible with material based damage feedback system, remember to add tags (like wood, stone, plastic etc. ) to your custom materials.

In case, you want to add tags to an already existing map's materials - Load the map with this mod, pull down the console (default key is: alt+control+tilde) and set g_debugDamage to 1. This will dump collision material information to console, every time you shoot at things; making it easy to find material of the entity you are shooting at. You'll then have to manually add a tag to that material.

Few things to know:

# These are the tags that the new material based damage system utilize:
metal
stone
flesh
wood
cardboard
glass
plastic
ricochet
surftype10 (for Concrete)
surftype11 (for Sand)

# Leaving materials untagged, will make them of type "metal" by default.

-------------------------------------------------------------------------------------------------