[Phil25]

ATTENTION: These tutorials are outdated! Please review the newest API documentation and examples here.

Tutorial on Adding Custom Perks

Note: There are two types of perks - Core & External:

• Core perks are added via editing the RTD plugin, External ones are added via a different plugin.
  
• Core perks have consistent IDs specified in the config file, whereas External ones do not necessarly have a consistent ID and they are always greater than the last core perk's ID.
  
• Core perks have custom settings in the config file, but External ones have to handle different perk settings themselves.
  
• You will have to update your custom Core perks with new RTD releases.

External Perks:
1. Register the perk using the RTD2_RegisterPerk() native.

• Look in the Include File under For Developers in the main post for an in-depth explanation.
  
• A practical usage could be found in the example plugin attached to this post.

2. RTD2_RegisterPerk() should be used in 2 instances:

1. In OnPluginStart(), but only when the RTD2_IsRegOpen() native returns TRUE. (to account for late load)
   
2. Each time in the RTD2_OnRegOpen() forward. (regular perk registration)

3. Last parameter of RTD2_RegisterPerk() is the callback function with parameters:

1. int client – The client index to set the perk to, guaranteed to be valid.
   
2. int perk ID – Your custom perk's ID which was given to it upon registration with RTD2_RegisterPerk().
   
3. bool apply - TRUE if perk should be applied, FALSE if perk should be removed; FALSE is never passed on instant perks.

4. A few notes:

• Perks cannot be unregistered once registered. You can use the RTD2_SetPerkBy*() natives to disable them.
  
• If an existent token is passed in the RTD2_RegisterPerk() native, it will override the functionality of a perk with that token. This applies to Core perks as well.
  
• If a Core perk's functionality has been overriden, you can use the RTD2_DefaultCorePerk() native to set it back to default. This native should not be used on External perks.
  
• If your perks hurts other players with SDKHooks_TakeDamage(), I advise you to use the RTD2_CanPlayerBeHurt() native, as it additionally checks whether the player is in Friendly Mode.

Core Perks (simple):

1. Put your perk's .sp in the scripting/rtd/ folder.
2. Create a function in it with parameters: (int client, char[] const sPref, bool apply)
3. Include your perk in scripting/rtd/#perks.sp.
4. Add your perk to the rtd2_perks.cfg and configure it, having the ID consistency in mind.
5. Add your initialization function to the switch() statement in the ManagerPerk() function of the scripting/rtd/#manager.sp.

Core Perks (detailed):
First, to clarify, in order to add a custom Core perk, you don't need to edit the base rtd2.sp in the slightest. Everything you need to edit is in the scripting/rtd/ folder.
Before you get started, you should familiarize yourself with the Detailed Breakdown of the rtd2_perks.cfg.

Start Up

1. Create an .sp with your desired perk's name and place it in the scripting/rtd folder.
2. This file is where all the magic happens, you can go ahead and use this template:
   Template

   PHP Code:

   //Let's have some global variables so our perk could behave in a customized way
char    g_sValue1[32];
int    g_iValue2;
bool    g_bValue3;
float    g_fValue4;

//PerkName_Perk is the only function being called by the base script. You can name it whatever you wish, as long as you'll be able to keep the consistency in other places.
void PerkName_Perk(int client, const char[] sPref, bool bApply){

    if(bApply)
        PerkName_ApplyPerk(client, sPref);
    
    else
        PerkName_RemovePerk(client);

}


//Let's split it into two functions for simplicity's sake.
void PerkName_ApplyPerk(int client, const char[] sPref){

    //We have a string of settings that is getting passed from the base plugin, let's process it.
    PerkName_ProcessSettings(sPref); //NOTE: YOU SHOULDN'T USE THIS IF THERE'S JUST A SINGLE SETTING

    //Enable perk on the client here

}

void PerkName_RemovePerk(int client){

    //Disable perk on the client here

}

//The parameter looks simiilar to this: "X,Y,Z,W" (no spaces, more than a one value, should be separated by a special symbol)
void PerkName_ProcessSettings(const char[] sSettings){ //NOTE: YOU SHOULDN'T USE THIS IF THERE'S JUST A SINGLE SETTING
    
    char sPieces = new char[AMOUNT_OF_SETTINGS][LENGTH_OF_A_SETTING];//Let's set up a buffer to split the settings string into
    ExplodeString(sSettings, ",", sPieces, AMOUNT_OF_SETTINGS, LENGTH_OF_A_SETTING);//Split the string every 'comma' character

    //Do whatever we want with this information, such as assigning it to global variables, for one
    strcopy(sValue1, sizeof(sValue1), sPieces[0]);
    g_iValue2 = StringToInt(sPieces[1]);
    g_bValue3 = StringToInt(sPieces[2]) > 0 ? true : false;
    g_fValue4 = StringToFloat(sPieces[3]);

} 

3. Create a function in that script with which you want to initiate an enable or a disable of your perk. For template, see: PerkName_Perk()
4. Head over to scripting/rtd/#perks.sp and include your .sp.
5. Head over to scripting/rtd/#manager.sp and add your initiation function in the switch() statement of the ManagePerk() function.

The #manager.sp

1. This is what actualy invokes your perk, specifically the ManagePerk() function.
2. This function is all you need for your perk to work. However, if you want to provide some more functionality, check out the forwards below.
3. If you wish to use any forward, let's say you want to precache a sound in OnMapStart(), go to Forward_OnMapStart() and add a function corresponding to the one in your perk's .sp.
4. You can use these forwards in any way you like, but if there's an Action type one, you won't be able to return Plugin_Handled in order to stop it.

Configure rtd2_perks.cfg

1. Make sure that when adding your perk, its ID is greater than the previous one by 1. They have to be consistent.
2. Configure the rest. Once more, make sure you'd understood Detailed Breakdown of the config file.

Your .sp

1. The initiation function:
   • This function is used to enable or disable a perk on a client.
     
   • Parameters:
     1. (int) client - the client index. It is guaranteed to be a valid, non-bot client.
        
     2. (char) sPref - the perk's own settings string, found in rtd2_perks.cfg. For more info, go to "Detailed Breakdown" of the Config file.
        
     3. (bool) apply - Should the perk be applied (true) or removed (false)? For instant ("time" set to -1) perks, false never occures.
2. From the initiation function, forward the functionality to the rest of the script.

Some valuable stocks:

The plugin has some stocks and functions in its core, you can use pretty much all of them.
The ones which I feel should be included in this list, are:

1. (bool) IsValidClient(int client)
   • client >= 1
     
   • client <= MaxClients
     
   • client is connected
     
   • client is not fake (bot)
     
   • client is not in coach mode
2. (int) CreateParticle(int client, char[] paticle_name, bool should_attach=true, char[] attachment_point="", float offset[3]={0.0, 0.0, 36.0})
   • Spawns a perticle at client's location.
     
   • If 3rd parameter is true, attach it to the client...
     
   • ... by a specified attachment point.
     
   • The default offest is roughtly the middle of the client.
     
   • You have to handle destroying the particle yourself.
     
   • Returns created entity's index.
3. (int) GetPerkTime(int perk_id)
   • Get the time of specified perk's ID.
     
   • Useful if you need to do something time-related with the perk.
     
   • NOTE: This is NOT timeleft of the perk. Just how long it was applied for.
4. FixPotentialStuck(int client)
   • If you'd expect a client might get stuck after something, fire this function.
     
   • It will detect if the specified client is indeed stuck and force a respawn on him with a message.
     
   • It returns nothing.
5. (int) ConnectWithBeam(int iEnt, int iEnt2, int iRed=255, int iGreen=255, int iBlue=255, float fStartWidth=1.0, float fEndWidth=1.0, float fAmp=1.35)
   • Connects two entities with env_beam.
     
   • Returns created env_beam's index.

If anything needs to be clarified, go ahead and post a comment. I'm pretty sure I'll be editing this tutorial from time to time.