Basics and theory

I'm going to explain how I understand the damage system of SH3, or in other words how the different units (ships, airplanes and land units) can be destroyed.

The whole damage system depends on the following files :

- Zones.cfg in the data folder
- ---.zon in the units' folder
- Shells.zon and Torpedo.zon in the library folder

A well-posed question is already half-answered.

So, first, let be clear about the vocabulary ...


UNIT :
  - in absolute, whatever thing which can be placed in SH3 world with the mission editor (ships, airplanes, dolphins, coastal defenses, minefields, antisub nets, air bases...).
  - for our study, a visible 3D object which represents ... which can be attacked and defeated (eg : a rock is not a unit, but a destroyable lighthouse is a unit (because a passive unit will be recognize by the player as "defeated" only if it is "smashed")).

OBJECT : 3D part of a unit. It can be the "main part" of the unit (for example the complete hull of a ship), or "subparts" (for example : afunnel, a mast, etc.). A 3D model is characterised with a number, written in a small square in S3D.



Fig. 1 - Unit's .dat file : 1 : main part ; 2 : subpart ; 3 : characteristic number of the 3D model
__

BOX : virtual rectangular parallelepiped linked to an OBJECT ....... and which is configured to have the properties of a specific ZONE TYPE.

ZONE TYPE : ensemble of properties (detailed/defined in Zones.cfg) which are applying to the boxes linked to this zone type. Each property is a specific value for the mandatory (and optional if any) parameters ; cf. next post.

box or zone type ?? :
  destroyable
  explosive

PARTICLE EFFECT :  ........  (examples : smoke, fire, bubbles(?) ...)

__

VECTOR OF DAMAGE (VD) : whatever device which can cause damages (meaning taking away some hitpoints from units and boxes) : it can be a shell, a torpedo, a rocket, etc.

HIT POINTS (HP)  (life points)

DAMAGE POINTS (DP) : maximal amount of HP that a VD can take away from units and boxes.

EXPLOSIVE AREA (EA) : spherical area in which a VD will release its DP when exploding.

  # schema #

__

IMPACT : a UNIT (or a BOX) is "impacted" when a VD is exploding after having collided with this unit (or box).

HIT : a BOX is "hit" if one of its part is located in an EA (note : a box can be hit without being damaged).

DAMAGED : a BOX or a UNIT is "damaged" while loosing some HP, or if it has lost some HP.

__

DEFEATED (out of combat) : a UNIT is "defeated" (and not "destroyed") if it has no more HP, or if it is too deep in the water.

DESTROYED : a BOX is "destroyed" if it has no more HP.

SMASHED : an OBJECT is "smashed" (and not "destroyed") if it is physically destroyed : it is thrown in the air or it collapses, and then it disappears. When an object is smashed, all the sub-objects linked to it are also smashed.

__

A.L. : armor level of a unit or a box (the A.L. value of the unit's boxes can be provided by the zone type linked to the boxes, or by the unit's .zon file).

# schema #

M.A.P. : maximal armor penetration value of a VD.

The Zones.cfg file contains all the zone types with their parameters.

Each specific zone type has mandatory parameters (they must be completed) and optional parameters (meaning that the line can be deleted if not needed, marked in blue in the following text) :

Parameter	Values	Meaning
Category	Engines Room ; Fuel Bunkers ; Keel ; Fore Ammo Bunker ; Aft Ammo Bunker	not sure ....
Multiplier	number	not sure ...
Flotability	number	Tests are needed to understand exactly how this is working ....
HitPoints	number
Destructible	Yes ; No
Effect1	name of the particle effect, number between 0 and 100 (%)	The specified particle generator will be spawned when the box's HP are equal or inferior to the percentage specified
Armor Level	number
Critic Flotation	number between 0 and 1(?)	?
Critical	Yes ; No	Probably : if a critical box is destroyed, then the unit itself is defeated
Critical Chance	number between 0 and 1(?)	?
FloodingTime	number (seconds ?)
CargoType	None ; Custom ; Fuel ; Ammo	Fuel or ammo explosion when the box is destroyed, which will damage the units and the boxes which are in the EA
Crash Depth	number (meters)	Probably : when the box is under the specified depth, it is destroyed

Also, there are very important lines at the end of the file.

Each unit's .zon file contains :

  - the general data of the unit
  - the damage boxes and/or the collision spheres for the unit and its subparts.


1. General data

- Contained in the node called "ColisionableObject". This node must be added in order that a VD is able to impact the unit.

- the number of HP : each type of shell fired against an unit will inflict a certain amont of damage to it. In fact, the shell will "take" a certain number of HP to the unit AND to the damage boxe(s) which is (are) hit by the shell. When all the unit's HP are loss, the unit is defeated, resulting in the immediate destruction of all the damage boxes (the explosive damage boxes (ammo or fuel) will explode) of the unit.

- the armor level : probably, a VD will inflict less damage if the ship and/or the damage boxe has an armor level higher than the max armor penetration value of the VD... From what difference the VD will inflict no damage ?

- the crash depth : when the unit reaches this depth, some HP are loss (the total number of HP of the ship decreases, not the HP of the damage boxes, except if they have also reached their own crash depth).


2. Damage boxes and collision spheres

- the damage boxes : they represent the hull and the internal rooms of a unit. Each box is linked to a chosen zone type.

- the collision spheres : they allow the unit to collide with other units and with the land (sea bed and shore) ; in this case, the unit and its damage boxes are damaged, depending on the unit's speed and other factors (not clear for now).

THE IMPACT

1) When does an impact occur ?

a) With a 3D model's number = 4

- A VD will impact an object even if there isn't any damage box on its trajectory. If there isn't any box on the VD's trajectory, it sometimes happens that a shell passes throw the object.

- A VD won't impact a box which is on its trajectory if this box is attached to an object but located outside of the 3D limits of this object.
_____

b) With a 3D model's number = 6

- A VD will pass throw an object if there isn't any damage box on its trajectory.

- A VD will impact a box attached to an object if this box is on its trajectory, and even if this box is located outside of the 3D limits of the object.

- The impact point is exactly situated at the intersection of the VD's trajectory and the first face of the box that the VD will encounter.

- If there are two or more damage boxes linked to the model, it appears that only the first one can be hit by a VD.


2) What does happen during an impact ?

a) A spherical (3D) explosive area is created, centered on the impact point.  [......]



Fig. 2 - Explosive area
__

b) The game determines a value (RDP) for the actual DP carried by the VD, which is a random number between min EF and max EF.

c) The game's engine will then proceed to a quick calculation in order to determine if these RDP will be "given" to the damage box (and/or the unit), meaning that the current HP amount of the box and/or the unit will be subtracted by RDP. Note that the game chooses only between 2 solutions : all RDP are given, or none.

So the game will calculate a "random" AP (RAP) value for the VD, with this formula :

RAP = (AP * Z) + (RDP / PT)

Z = random number between 1-ALF and 1+ALF
ALF = armor level factor
PT = penetration threshold
AP = armor penetration of the VD

If RAP is superior or equal to the AL of the box/unit, then all the RDP are given to it within the limits of the explosive area.

If a damage box is destroyed, any damage box having an area (in 3D space) in common with it will be destroyed too (whatever the amount of HP and AL it has).

According to my tests, an undamaged ship has 100 points of buoyancy. When you destroy (flood) a zone with a Flotability of 20, then you subtract 20 points of buoyancy from the ship (so, the ship will lean into the water but not sink). When the ship has a negative buoyancy, it will sink. The more negative buoyancy it has, the faster it sinks. With -1, it sinks very slowly. At -400 it will sink fast.

Also, the sinking speed depends on the 3D distribution of the floodings. For a same negative buoyancy, if the floodings are only at one end of the ship, it will sink faster than if both ends are flooded. At least, it seems so visually.
_______

When I refer to a parameter of a zone (assigned constant value written in Zones.cfg), I will write it in italic and with a capital letter, like HitPoints. I do this in order to avoid confusion with the actual in-game current amount of hitpoints of the zone. Same necessity goes for the flooding time...

When a zone begins to fill with water, it will continue until the zone is completly flooded.

About the in-game flooding time:
   - If a zone loses all its hitpoints, the flooding time (in-game) is the FloodingTime of the zone.
   - If a zone has lost HitPoints x Critic Flotation, or less, it won't flood at all.
   - Between these 2 extremes, the flooding time progressively decreases from infinite (no flooding, because not enough hp lost) to the zone's FloodingTime (all hp lost).

Actual in-game flooding time of a zone: ft = (1 - lf) * FT / (1 - (hp / (HP * (1-CF))))



In-game values :
   ft = remaining time (in seconds) before the zone is completly flooded
   hp = remaining hitpoints of the zone
   lf = level of flooding (% : between 0 and 1), percentage of space flooded with water

Constants (written in Zones.cfg) are in capital letters :
   CT = Critic Flotation (% : between 0 and 1)
   FT = FloodingTime (in seconds)
   HP = HitPoints

If Critic Flotation = 1, there will be a bug. Indeed, if you look at the formula above, you will see that with CF=1, you will divide by zero. Hence the bug... : HP * (1-CF) = HP * 0 = 0 ... leading to hp / 0.

Also, if Critic Flotation = 0, it should lead to a bug, because hp/HP = 1 (the zone hasn't lost any hp yet), leading to FT / 0.

If a zone is instantly destroyed, it won't be instantly flooded, but ft = FT.
So, it appears that FT is the minimum flooding time of a zone.