Bullet Holes

Adding Bullet Holes

In this tutorial I will ‘attempt’ to explain how the decal Manager works by setting up a simple bullet hole each time a projectile hits something.

First open up engine/game/projectile.cc and add this new include file at the top:

#include "sim/decalManager.h"

Then look for the function:

void Projectile::onCollision(const Point3F& hitPosition,
                             const Point3F& hitNormal,
                             SceneObject*   hitObject)

You will see an if statement there, after it add the following code after the if brace closes:

if(isGhost())
   {
      if (hitObject->getType() & (InteriorObjectType|TerrainObjectType))
	  {
		  if (mDataBlock->decalData != NULL)
		  {
			if(mSceneManager->getCurrentDecalManager()) 
			  mSceneManager->getCurrentDecalManager()->addDecal(hitPosition, hitNormal, mDataBlock->decalData);
		  }
         }
}

What this code does is very simple, or maybe not, the first line checks to see if the object the projectile collided with (notice we are in the OnCollision function) is an Interior or a Terrain object.
If it is it then checks if the decalData isn’t NULL, and if it isn’t it adds a new decal at the hitPosition using the decalData specified in the datablock as the bitmap.

Now we will add this decalData thing to our projectile, so open up projectile.h and about line 26 you will see:

class ExplosionData;
class ShapeBase;
class TSShapeInstance;
class TSThread;

After the TSThread class add:

class DecalData;

Now in the same file look inside the ProjectileData class and under the public section add our new decalData and the decalID which we will use to keep track of the decal.

DecalData *decalData;
   S32 decalID;

We need to initialize this values to some secure default values, so head back to projectile.cc and search for the projectileData constructor. Inside it add the following 3 lines:

decalData      = NULL;
   decalID        = 0;

Now we need to make the engine read the values of these 3 variables from the projectile datablock (the one you define in the scripts). Look for the function void ProjectileData::initPersistFields() and inside it add the following:

addField("decalData", TypeDecalDataPtr, Offset(decalData, ProjectileData));

That addField function is telling the engine to read the value of decalData (TypeDecalDataPtr) and store it in the member variable decalData of ProjectileData.

Now search for the function ProjectileData::packData() and add this lines:

if( stream->writeFlag( decalData ) )
   {
      stream->writeRangedU32( decalData->getId(), DataBlockObjectIdFirst,  DataBlockObjectIdLast );
   }

and in ProjectileData::unpackData() add this other lines:

if( stream->readFlag() )
   {
      decalID = (S32) stream->readRangedU32(DataBlockObjectIdFirst, DataBlockObjectIdLast);
   }

What this does is send and receive the decalData from the server to the client (server packs, client unpacks)
We need to add 1 more line to the engine and we are done, look for the ProjectileData::preload() function and add this code:

if (!decalData && decalID != 0 )
      if (!Sim::findObject(decalID, decalData))
         Con::errorf(ConsoleLogEntry::General, "ProjectileData::preload Invalid packet, bad datablockId(decalData): 0x%x", decalID);

This one checks if the decal exists before loading the projectile (preload) and if it doesn’t prints an error to the console. I don’t think this is really needed, but it was in the code I used as example and also it’s a nice way of knowing if the decal is being loaded.

Finally, recompile and … no! wait! Don’t run it just yet, you are missing something.
Open up the script of the weapon to which you want to add the bullet holes, in it add this datablock:

datablock DecalData(BulletHoleData)
{
   sizeX       = 0.125;
   sizeY       = 0.125;
   textureName = "~/data/special/weapons/bullethole";
};

Make sure to change the path to the texture you want to use as the bullet hole.
Now look for the dataBlock of the projectile it self, should be like ‘datablock ProjectileData(RifleProjectile)’ and in it add this line:

decalData = BulletHoleData;

Ok now we are done, run the g… oh, you already did… ok bye, enjoy it

If you come back from testing then:

Special Thanks to Frank Bignone for helping me with a problem I had while coding this.
Also thanks to everyone that hangs out on IRC everyday (this is intended to get more ppl on IRC)
If you are still reading might be because you had problems, if you do feel free to email me.

FAQ:

Q: Can I add decals to the player?
A: Yes you can but, they are attached to the bounding box of the player… so it looks kinda funny, if you want to try if by yourself remove the line ‘if (hitObject->getType() & (InteriorObjectType|TerrainObjectType))’ and its closing brace, so decals will be attached to every surface and not only to Interiors or Terrains.

Q: Is there a way to prevent the decal manager from fading out the bulletholes after a couple of seconds (make them persistant)?
A: Yes, you can set the decal timeout in the prefs.cs file, thanks Stefan.

Q: Will there be any more questions here?
A: If they are asked to me and I think they are important I’ll add them right here.