Keygroup example

Current revision

This article assumes the user is somewhat familiar with EventScripts.

What is a "keygroup" and how do I make one?

A keygroup is EventScripts way of creating and retrieving, storing, editing, and sorting values from databases.

Keygroup explanation

A keygroup resides within memory until it is saved. When a keygroup is referenced and manipulated, only the keygroup within memory is changed. Therefor, keygroups are non-permanent unless they are saved.

Keygroup Example

Creating a keygroup

In this example, we will be creating an RPG-like leveling system. To first create a keygroup, we will use es_keygroupcreate.

// keyrpg
block load
{
    es_keygroupcreate rpgplayers
}

Creating a key

To store information about a player, we must create a key for them. A key is a named location for storing name-value pairs. We first check to see if the player is already in the keygroup using es_exists.

// keyrpg
block load
{
    es_keygroupcreate rpgplayers
}
 
event player_activate
{
    // Use the steamid of the player because it is the only permanent information
    // available about every player. 
    es_xset key_exists 0
    es_exists key_exists key Example event_var(es_steamid)
    ifx false(key_exists) do
    {
        es_keycreate Example event_var(es_steamid)
    }
}

Saving and loading keygroups

Before name-value pairs are explained, saving and loading a keygroup will be addressed.

To make a keygroup permanent, you must load and save it (to disc). The commands es_keygroupload and es_keygroupsave are used for this manner.

Wiki syntax is preventing this from displaying properly. For the location parameter, we add "|" before the script name to save it in the same directory as the script. Otherwise, it is saved in /game/cfg/

// keyrpg
event round_end
{
    // When loading and saving keygroups, add "|script-name" after the keygroup name
    // to save it within the same directory as the script. Otherwise, it is saved
    // in /game/cfg/
    es_keygroupsave rpgplayers |keyrpg
}
 
block load
{
    // They keygroup is deleted from memory so that data is overwritten
    es_keygroupdelete rpgplayers
    // Because we are saving and loading the keygroup, we do not need to create it
    es_keygroupload rpgplayers |keyrpg
}
 
event player_activate
{
    es_xset key_exists 0
    es_exists key_exists key Example event_var(es_steamid)
    ifx false(key_exists) do
    {
        es_keycreate Example event_var(es_steamid)
    }
}

Creating name-value pairs

Within every key (a player's steamid in our case) a name-value pair may be created. This is the information you will be dealing with most of the time. For easiest use, create all the necessary information at the same time you create the relevant key. So that the value is not overwritten, we make sure it does not exist before setting it to a default.

// keyrpg
event round_end
{
    es_keygroupsave rpgplayers |keyrpg
}
 
block load
{
    es_keygroupdelete rpgplayers
    es_keygroupload rpgplayers |keyrpg
}
 
event player_activate
{
    es_xset key_exists 0
    es_exists key_exists key Example event_var(es_steamid)
    ifx false(key_exists) do
    {
        es_keycreate Example event_var(es_steamid)
    }
    // Create variables to check if the player has any xp or levels
    es_xset xpcheck 0
    es_xset levelcheck 0
    es_keygetvalue xpcheck rpgplayers event_var(es_steamid) xp
    if (server_var(xpcheck) == 0) then es_keysetvalue rpgplayers event_var(es_steamid) xp 0
    es_keygetvalue levelcheck rpgplayers event_var(es_steamid) level
    if (server_var(levelcheck) == 0) then es_keysetvalue rpgplayers event_var(es_steamid) level 1    
}

Manipulating name-value pairs

Manipulating name-value pairs is done in much the same way creating them is done using es_keygetvalue and es_keysetvalue.

// keyrpg
event round_end
{
    es_keygroupsave rpgplayers |keyrpg
}
 
block load
{
    es_keygroupdelete rpgplayers
    es_keygroupload rpgplayers |keyrpg
    
    // This is the experience awarded for getting a kill
    es_xset keyrpg_killxp 50
    
    // A server command will be used to check to see if a player is eligible for a new level
    es_regcmd checklevel keyrpg/checklevel
}
 
event player_activate
{
    es_xset key_exists 0
    es_exists key_exists key Example event_var(es_steamid)
    ifx false(key_exists) do
    {
        es_keycreate Example event_var(es_steamid)
    }
    // Create variables to check if the player has any xp or levels
    es_xset xpcheck 0
    es_xset levelcheck 0
    es_keygetvalue xpcheck rpgplayers event_var(es_steamid) xp
    if (server_var(xpcheck) == 0) then es_keysetvalue rpgplayers event_var(es_steamid) xp 0
    es_keygetvalue levelcheck rpgplayers event_var(es_steamid) level
    if (server_var(levelcheck) == 0) then es_keysetvalue rpgplayers event_var(es_steamid) level 1
}
 
block checklevel
{
    // This is where we check to see if a player is eligible for a new level
    // The experience required to level is equal to their level mutliplied by one-thousand
    es_xset rpg_player 0
    es_getargv rpg_player 1
    es_xset curxp 0
    es_xset curlevel 0
    es_xset rpgsteamid 0
    es_getplayersteamid rpgsteamid server_var(rpg_player)
    es_keygetvalue curxp rpgplayers server_var(rpgsteamid) xp
    es_keygetvalue curlevel rpgplayers server_var(rpgsteamid) level
    es_set xpneeded server_var(level)
    es_math xpneeded * 1000
    if (server_var(curxp) > server_var(xpneeded)) do
    {
        es_math curlevel + 1
        es_keysetvalue rpgplayers server_var(rpgsteamid) level server_var(curlevel)
        es_tell server_var(rpg_player) #greenYou just achieved Level server_var(curlevel)!
    }
    es checklevel server_var(rpg_player)
}
    
 
event player_death
{
    // Here we will add the experience set in block load (50) to the players current experience
    // We will also then check to see if they have enough experience to level using "checklevel"
    if (event_var(es_userteam) != event_var(es_attackerteam)) do
    {
        es_xset curxp 0
        es_keygetvalue curxp rpgplayers event_var(es_attackersteamid) xp
        es_math curxp + server_var(keyrpg_killxp)
        es_tell event_var(attacker) #greenYou gained server_var(keyrpg_killxp) for getting a kill!
        es checklevel event_var(attacker)
    }
}    
 
event player_spawn
{
    // We check to see if the player is eligible for a new level when they spawn for redundancy
    es checklevel event_var(userid)
}