Marking and tracking players tutorial

Info and credits:
This tutorial was created with help from Dogmeat(Base Location indicator code) and a little help from the people over at the Steam forums Source Coding section.

The goal in my mod was to have a grenade which when it explodes could "mark" people and that the player who marked them can cycle through his targets at will(you could adapt this to track every target that's marked without too much effort), the player will have to be able to actualy cycle through his targets as in my mod he can push a button to teleport swap with the target(they'll both be teleported to each other's locations).

But since he can hit more then one player in the explosion of the grenade he will need to cycle through targets to get the desired player and as a bonus an icon will be displayed over their head even through walls making it even more usefull for timing the teleport or simply ambushing that player.

Example: You could wait behind a wall, on the other side is a base filled with enemies, you wait for the target to run towards a health pickup in the back of the base, then when you see the icon is far away push the teleport button and voila you will be right behind the enemies forces and can rip them a new one!

Part 1: The HUD Element(client side):
We'll start in the hud element that's gonna show our tracking icon.

In my case it's in a file I called: hud_teleport_marker.cpp in the client side project in the HL2 DLL filter/folder, but you can name it anything you want.

Let's start with the includes which have to be in the top of the file:

My actual class will be called CHudTeleportMarker, but again that can be anything you want it to be.

Now let's look at the header, which can be simply in the .cpp file as long as we won't need to include it anywhere.

First off, important is: m_nTeleportMarkerTextureID which is for the texture of the icon we'll show on the hud. If you don't have a icon you can use for testing I'm willing to send my icon so you can make sure it works.

Even more important is the handle:
CHandle m_hSelectedMarkedPlayer;

A handle is pretty much like a pointer but with some special properties, you can treat it like you would any pointer to a object of a class.
This handle will point to the currently selected player out of our marked players and will be used to fetch this players origin which is used to show the icon on the HUD.

Now the header looks like this:

Next we'll need to use some macro's to set up some stuff:

The second is very important here as this will declare the message that will be hooked to this hud(we'll have to register this message later as well).

Next we'll create the constructor for this class:

The next function will update the marked teleport target(the player who we are tracking), it's a function that will receive a networked usermessage, the usermessage sends a byte(1/4th the size of a normal integer) that contains the entity index of the currently selected player.

Be sure to read data sent in the same order you send it! In this case there's only one byte of data being sent, so there's no order to keep in mind, but if you're gonna send larger message you must read in the same order as you send data or else you'll put the wrong values into your variables.

Next up follow two small functions:

And now the function that's actually gonna paint/draw the tracker image on the screen:

Note that the target pointer gets created in the message receiving function like this(don't insert this code as it's already there):
m_hSelectedMarkedPlayer = UTIL_PlayerByIndex( sender_index );

It will create a C_BasePlayer pointer by fetching the player object by the index we are going to send with WRITE_BYTE which will be stored in an array part of the server side player class.

What's so handy about this system is that you only need to send a players index when the selection changed and that's only sent as a single byte(8 bits), which is then used to create a pointer which can then fetch the origin without sending the Origin vector over the network constantly to keep it updated but rather doing it locally, lowering network traffic.

There may be still be some form of networking going on behind the scenes(how else does the object being pointed to stay updated so that player origin stays correct) but that means we aren't sending it twice over the network so my point stands... lower amount of network traffic.

Next up the last function of the hud element:

This is the code DogMeat used for the base locations, to prevent showing the image when distance is too great or the image is behind the player.

We'll also need to register the usermessage, this is fairly simply, just open up hl2_usermessages.cpp and add:
usermessages->Register( "updateSelectedTeleportTarget", 1 );

Note that according to the Valve Developer Community this is the size in bytes not bits we'll only be sending a byte holding the entindex of the target so our size of the message will be 1 byte, for values that may differ insize(such as chat string) or if you don't know the size you can use -1 to have it determine the size on it's own.

Lastly to show the hud element we'll need a entry in HudLayouts.res
Which looks like this:

This finishes up the HUD side of the tracking, the next page will continue with selecting and marking players, cycling through selections and interacting with the targeted players(in my case I'm gonna teleport the marking player to the location of the marked player and the marked player to the location of the marking player) when a player activates his secondary weapon function for my custom weapon_stopwatch.

So keep on reading!

Part 2: Marking players and keeping track of them(server side):

First we're going to actually implement the marking, removing, cycling and more of targets.
First up add the following somewhere in shareddefs.h:
#define MAX_TARGETS 3

Change the 3 to whatever amount of maximum possible targets you want to hold in the array(note that this shouldn't be more then MAX possible players) if you want you could use the existing MAX_PLAYERS constant if you want the maximum amount of possible targets.
Also keep in mind this will increase or decrease the array size, also everything that may cause it to go out of bounds uses MAX_TARGETS so if you change this everything should still work fine.

Next a very miniscule client side part in c_hl2mp_player.h under m_iPlayerSoundType add:
int m_iTeleportTargetIndex;

This is the entindex of the currently selected target. It's what we set in the message receiving function in our HUD Element.

Next in the public: section add the functions:

Note that we're putting the bodies of the functions directly in the header as well, this might mean it will become inlined making calls to the function faster. Though it doesn't really matter in our case, if you want to be sure it won't be inlined feel free to add the body in the .cpp file instead.

To finish things up in the client side of the player add the following in the constructor:
m_iTeleportTargetIndex = -1;

Makes sure our integer gets initialized to -1(means nothing selected) afterwards the integer will only be updated through the message receiving function in our HUD element.

Next in hl2mp_player.h we'll add 2 variables and a integer array, but first let me discuss them:

• m_iLastMarkedIndex: This is the index of our array of player indexes, not a direct player index, assuming max targets is 3 this will be a value of -1 to 2, -1 meaning clean last index and 0 to 2 the array index. We use this index to add players to the array 1 by 1 rather then randomly adding onto the array.
• m_iCurSelectedPlayer: Similar to the LastMarkedIndex and is also an index for our array, but this one is important so our current selected target won't get switched whenever we mark a new player. It's also used to cycle through targets when the player does want to select a new target.
• m_iMarkedPlayers[MAX_TARGETS]: The array holding the player indexes, values of -1 will mean that there are no player indexes at that part of the array.

Ok now let's add these variables and the array underneath m_iModelType(in hl2mp_player.h):

Next in the public: section add the following functions:

The first three are for adding, removing or cycling through marked players the last one is a getter for the player index of our current target and is pretty much the brother of the client side version under the same name.

Let's start in the hl2mp_player.cpp file in the constructor where we initialize our variables to -1:

Now we'll take a look at the first function we declared which is for adding new marked players:

The comments should help you understand it, if not feel free to ask me about it.
The last part of the function will send a usermessage with the entindex of the player to show the tracker icon on to our HUD Element.

Next up removing marked players:

Again comments should help you here, moving on with cycling through targets:

These should be all the functions needed to add, remove and cycle through marked players, now we'll need to call these functions or else there ain't much use for them.

Let's start with marking players, in my situation my grenade(grenade_stopwatch) explodes and does "damage" like a normal grenade, BUT then the OnTakeDamage function get's called where I'll be cancelling damage and make the call to mark the player(s) that got hit by the grenade:

Please note that GetGrenadeEffectType is NOT a Source function, nor are the flags it uses part of the default code, I've added this myself, if you want to do the same thing in a simple way, you're best off overriding or editting a constructor of the class CTakeDamageInfo, create a private member variable in there which is set through the constructor and create getters and setters like I have, then in the Explode function of your grenade(should be in basegrenade.cpp) you then call your editted constructor or overloaded constructor instead(there should be a CTakeDamageInfo info object in the Explode function)

If my grenade type is hitting the player we'll create a pointer to the attacker(the player who threw it, this IS default part of CTakeDamageInfo) note that it returns a Object of CBaseEntity so you will need to type cast or use ToBasePlayer and then perform checking whether the pointer is correct, whether the player isn't attacking himself, the player being hit is alive(this function does seem to get called shortly after death so hence this check) and whether the attacker is still alive(he could have died in the time it took for the grenade to explode) now if those are all ok we'll call AddPlayerMarkedForTeleport on the ATTACKER(if you forget to use the pointer the player will add himself to the target list as it will be the same as calling this->Function() then) as an argument we pass the entindex of the player being attacked.

Lastly regardless of whether we're adding a new target or not we return 0; so no further code will be executed as part of the OnTakeDamage function chain, which will result in the part that actually does the damage never being called, note that inputInfo.SetDamage(0); should also work without having to return.

Next we'll take a look at removing marked players from our target list, we do this in the Event_Killed function, add the following code above BaseClass::Event_Killed( subinfo ):

We'll set our variables to -1, using a loop we're also looping through all players in the server(we skip the same player that died as there's no point removing yourself from the target list...) lastly we'll send an update to our HUD Element that we no longer have anyone selected.

Note that if your mod has a round based system you will also need to do the above in your Reset function of the player, excluding the loop through all the players in the servers though since when Reset is called everyone's target array will be cleared!

Part 3: Cycling targets and teleporting(shared code):
In my case this is done when the player is holding the grenade that will teleport the owner and the target to eachother's locations and you can push a key to cycle through targets.

This weapon is for me weapon_stopwatch.cpp
First off we'll need a private member variable:
bool m_bActivatedTeleport;

Note that if you have a appropiate animation and events for it that you could do this through events, in which case you probably won't need this boolean.

However in my case there's no animation ready yet and no special animation either, thus I'm sharing my custom event for pulling the pin of the grenade instead, where I use the boolean to prevent starting the timer that will happen when that event launches, like so:

If I were to have a seperate event I could do things more orderly then I do now. But alas have to wait for my lazy animator (just kidding Nauz, you rock!)

Ok next we'll initialize the boolean in the Deploy function:

Next in the SecondaryAttack function somewhere after the owner/player pointer initialization's I will add:

Again, using animations this could be much better, but as a substitute right now, I'm using the pOwner pointer to check if we have a target(note that this is both for the CLIENT and the SERVER sides of the players, if we have a target I play a sound that will be that of success, if not it will fail.

Next in the ItemPostFrame function we'll change the start of the function to:

We start with creating a pointer to the owner, if it's a valid pointer in the SERVER side code we'll check if the owner released a certain key recently, if so we call the Cycle function in the server side player class, for the owner, as you have guessed this will cycle through targets, note that IN_CYCLE_TARGET is a custom made key, you will have to make your own or use an existing IN_ key.

Next if the drawback is finished(grenade being readied) and the case is GRENADE_PAUSED_SECONDARY then we call the function that will initiate teleport. We also adjust some variables.

Let's take a look at the function for the teleport:

First we create a pointer to the target by retrieving the target player index, next we check if the pointer is valid and if the target is still alive, if so we continue onward. to the server side section, which handles the teleport, after the teleport we use a screenfade to create a minor flash of white effect and we remove the target player from the owners target array(can't teleport with the same player twice without marking him again)

Lastly back in shared code again we remove some ammo from the owner.

That should be all, if you have any questions please ask them, any suggestions/constructive critiscm are welcome as well.