Bullet Holes (and other phantom parts)
How to Create Bullet Hole Effects
You can either apply small texture decals directly over model polygons, or create multiple texture files and use dynamic texture swapping to show increasing bullet damage as the aircraft gets hit.

The Polygon Method

CFS2 stock aircraft will display bullet holes on the model only when the aircraft is hit in combat and only in those areas which get hit. If the model is shot only through the right wing, bullet holes appear only on the upper and lower surfaces of the right wing.

How'd they do that?

In CFS2 stock models, the "bullet hole" is actually a small square/rectangular textured polygon created and placed at a location on the model where the bullet hole will appear. Therefore, if you want bullet holes, then your model file has to contain every polygon needed to display every bullet hole you want to see on your model.

Earlier, when you added the parameters bullets0 through bullets7 to the Parameter Dictionary, you added the variables CFS2 uses to determine when and where a bullet passes through your model.

CFS2 tests each "bullet" variable to see if a bullet has passed through a particular damage box. If there's no bullet, then no bullet hole is drawn. If there is a bullet, CFS2 renders your bullet hole polygon, which appears one pixel above the underlying polygon to eliminate any flickering of the bullet hole texture.

CFS2 can handle a maximum of 120 bullet hits on a single aircraft (that's a lot of holes!). If you want to track and use them all, you'll need to create 120 small polygons ... each designed as a separate part ... each with a parent part on the aircraft (either breaking or non-breaking) ... each with its own bullet hole texture applied.

Each bullet hole or bullet hole pattern will appear on a small, 4-point polygon. Each polygon is named in a manner that identifies its parent part, whether it is on the top, bottom, left, or right side of the part, the CFS2 offset of the bullet variable to test for a hit, and the hex mask used to make that test.

For example, bh106_R_fuselage.0001 is a "bullet hole" polygon (offset 0106 hex) attached to the right side of the fuselage and the mask to use in the test is "0x0001."

DESIGN

TIP
You can use any naming convention you like, but this method makes it easy to locate where the bullet hole is supposed to appear and the parameters to use in testing the var "bullets3." This convention also has the benefit of putting all your bullet hole parts in order by hit location in the Parts List.

In creating these small polygons, keep one thing in mind. A bullet hole polygon must lie in the exact same plane as the polygon over which you place it.

If you put a polygon on the side, top, or bottom of a rectangular part, this is easy. Just match the X,Y coordinates for each point in the polygon with the X,Y coordinates for the side of the rectangle onto which you're locating the small polygon.

On a curved surface, such as the fuselage, things get a bit tricky. It would be far too much work to rotate a small 4-point polygon to exactly match the planar position of a polygon defining the fuselage surface.

Instead, create a polygon "in place" on the fuselage surface, copy it, paste it in place, then split it off as a seperate part and rename it.

As an example, to put a bullet hole polygon on the right side of the fuselage, first select the part and then set FSDS for point mode. Highlight all points on the left side of the fuselage and hide them.

In the right view window, select a fuselage polygon over which you want to make a bullet hole.

While still in point mode, select two points from that polygon that define a long side and add a point between them. Do the same thing for the other two points on the same polygon. You now have six points defined on this fuselage polygon. Any four of them can be used to make your bullet hole polygon. If these four points would result in a polygon too large for your taste, repeat the process using the two just added points and two from the original polygon.

Now, select the four points you want to use to define the bullet polygon and, from the main menu, select Polygon/Make Polygon from Select Points. Pay attention to the direction of the polygon's normal vector. You may have to flip the polygon to make it visible.

Select the polygon you just created, then copy and paste the polygon in place. Do not move it! The polygon will have the name fuselage.1.

From the main menu, return to Part Mode. Select Edit/Part Properties and change the new part's name to bp_fus_R01 (bullet polygon, fuselage, right side, no. 1). Set the Part Parent to "fuselage." Also add the display condition, "Fuselage Visible." You now have your first bullet hole polygon ready for texturing!

Repeat this process for each bullet hole you want to include on your model.

Bullet holes are not rendered on the model unless ...

A. FSDS is set to include the bullets flag parameters in its Parameter Dictionary,

B. The appropriate flag integers are added to the [BOXES] tab definitions for the appropriate damage boxes and,

C. The SCASM code within the model is modified to test each of the bullet flags to determine if a bullet impact has occured on a given system.

There are 8 CFS2 variables bullets0 ... bullets7 used to indicate bullet strikes on the aircraft. Each 16-bit flag will track up to sixteen hits, which means that each of sixteen possible bullet strikes can be tested to determine if a hit has occurred.

If the flag bit is set, a bullet impact occurred. If the flag bit is clear, no impact has occurred.

CFS2 Bullet Variables
VariableAircraft Surface
bullets0Upper Right Wing, Aileron, Flap, Wing Structure, Wing Tip
bullets1Upper Left Wing, Aileron, Flap, Wing Structure, Wing Tip
bullets2Left Fuselage, Nose Structure
bullets3Right Fuselage, Nose Structure
bullets4Right Tail (Fwd), Vertical Stabilizer, Rudder, Upper Horizontal Stabilizer
bullets5Lower Right Wing, Aileron, Flap, Wing Structure, Wing Tip
bullets6Lower Left Wing, Aileron, Flap, Wing Structure, Wing Tip
bullets7Left Tail (Fwd), Vertical Stabilizer, Rudder, Lower Horizontal Stabilizer

There are 120 integers (1-120) that can be used in connection with damage boxes. The order of the integers for a given box isn't important, but the value range is important, since they relate to specific aircraft surfaces.

Grouped in clusters of either 4, 8, or 12, each integer represents a bullet hit.

CFS2 Bullet Hole Groups
Bullet FlagCFS2 VariableAircraft Surface
1,2,3,4,5,6,7,8,
9,10,11,12
bullets0Right Wing - Upper
13,14,15,16bullets0Right Wing Tip - Upper
17,18,19,20,21,22,23,24,
25,26,27,28
bullets1Left Wing - Upper
29,30,31,32bullets1Left Wing Tip - Upper
33,34,35,36bullets2Nose - Left Side
37,38,39,41,40,42,43,44bullets2Fuselage - Left Side
45,46,47,48bullets7Tail (fwd) - Left Side
49,50,51,52bullets7Vertical Stabilizer - Left Side
53,54,55,56bullets3Nose - Right Side
57,58,59,60,61,62,63,64bullets3Fuselage - Right Side
65,66,67,68bullets3Tail (fwd) - Right Side
69,70,71,72bullets7Rudder
73,74,75,76bullets4Right Elevator - Upper
77,78,79,80bullets4Left Elevator - Upper
81,82,83,84,85,86,87,88,
89,90,91,92
bullets5Right Wing - Lower
93,94,95,96bullets5Right Wing Tip - Lower
97,98,99,100,101,102,103,104,
105,106,107,108
bullets6Left Wing - Lower
109,110,111,112bullets6Left Wing Tip - Lower
113,114,115,116bullets7Right Elevator - Lower
117,118,119,120bullets7Left Elevator - Lower

The damge box section below is from the DP file for the CFS2 A6M5 Zero model. The integers in bold at the end of each data string are the index values shown in the above table. They tell CFS2 to track bullet hits on that damage box.

Box.0 is defined for the nose. The integers 33, 34, 35, and 36 track hits on the left side of the nose and the integers 53, 54, 55, and 56 track hits on the right side.

[BOXES]  ; Comment lines added to identify each damage box
; Nose -
box.0=%box_name.0%,-0.68,-0.69,1.15,0.64,0.68,1.93,
33,34,35,36,53,54,55,56

; Fuselage -
box.1=%box_name.1%,-0.68,-0.65,-1.39,0.65,1.07,1.14,
37,38,39,40,42,43,44,57,58,59,60,64,82

; Pilot -
box.2=%box_name.2%,-0.34,0.13,-1.05,0.34,1.03,-0.26

; Port Wing -
box.3=%box_name.3%,-4.97,-0.53,-1.73,-0.69,0.22,0.80,
100,101,102,103,104,105,106,107,108,
17,18,19,20,21,22,23,24,25,26,27,28,97,98,99


; Port Wing Tip -
box.4=%box_name.4%,-5.98,0.06,-1.08,-4.99,0.27,0.55,
109,110,111,112,29,30,31,32

; Starboard Wing -
box.5=%box_name.5%,0.66,-0.53,-1.73,4.97,0.22,0.80,
1,2,3,4,5,6,7,8,9,10,11,12,81,83,84,85,86,87,88,89,90,91,92

; Starboard Wing Tip -
box.6=%box_name.6%,4.99,0.06,-1.08,6.00,0.27,0.55,
13,14,15,16,93,94,95,96

; Tail (forward) -
box.7=%box_name.7%,-0.65,-0.68,-3.80,0.63,0.76,-1.39,
41,45,46,47,48,61,62,63,65,66,67

; Tail (aft) -
box.8=%box_name.8%,-0.40,-0.35,-6.55,0.37,0.58,-3.81,
117,52,68,71,72

; Port Elevator -
box.9=%box_name.9%,-2.33,0.11,-5.66,-0.41,0.29,-4.14,
118,119,120,77,78,79,80

; Starboard Elevator -
box.10=%box_name.10%,0.38,0.11,-5.66,2.34,0.29,-4.14,
113,114,115,116,73,74,75,76

; Rudder -
box.11=%box_name.11%,-0.10,0.59,-6.27,0.09,1.77,-4.51,
49,50,51,69,70,71,72

When the first bullet passes through the right side of the damage box for the nose, CFS2 sets the flag bit for index 53. The next hit sets the flag bit for index 54, and so on, until index 56 is set. After that, further bullet hits on the right side of the nose aren't tracked.

To see if the nose has been hit, test the bullets2 variable using the appropriate bit mask for hits to the left side of the nose and the bullets3 variable for hits to the right side.

If you've ever wondered about the integers following the damage box coordinates ... now you know.