Key groups

http://www.eventscripts.com/pages/Category:Key_Commands

The basic thing to remember is a "keygroup" is like a dictionary... the "keys" are like a page in a dictionary, and the "Keyvalue" is the definition on a page... e.g. Imagine you had a dictionary called "Collins dictionary 2006" and the definition "abacus" was on "page 1".... Then the "keygroup" in this case is "Collins dictionary 2006", the "key" is "page 1", and the "keyvalue" is "abacus" which will hold the definition of the term....

Similar.... If we had a "keygroup" called "Players", and inside that "keygroup" we had "keys" of all the players within our servers, and within each "key" there is 1 "key value" called "name", we could access it like this....

Code

GeSHi (eventscripts):
block load
{
  es_keygroupload Players
  // Open up a new keygroup within the server memory called "Players"... Now the keygroup is loaded we can use it to 
  // define all our keys and keyvalues
  es_xset check 0
  // Assign a 'check' value to 0
  es_xset get_value 0
  // Assign a 'get_value' variable to hold a value of 0. We will use this to retrieve the value from the keyvalue
}
 
block unload
{
  // Okay upon unload, delete the keygroup from memory as we do not need the keygroup anymore
  es_keygroupdelete Players
}
 
event player_activate
{
  es_exists check key Players event_var(userid)
  // Okay... We are checking to see if the event_var(userid) key already exists in the keygroup Players... If it does, it will assign the variable check to hold 1, otherwise, that variable will hold 0.
  ifx true(check) do
  {
    // If the key exists, we're going to delete it so we can create the 'real' userid... In theory this should NEVER happen... But it's good practise to ensure you always check...
    es_keydelete Players event_var(userid)
    // Delete the key from the keygroup Players
  } 
  // Okay... Now we're sure there is definitely NO key with the same value as the players userid, so create it...
  es_keycreate Players event_var(userid)
  // Create the value event_var(userid) inside the keygroup Players
  es_keysetvalue Players event_var(userid) "Name" event_var(es_username)
  // Okay... So here we are assigning a keyvalue to the players key..
  // Read it from right to left we get... We are assigning the value event_var(es_username) to be the keyvalue of "name" which is inside the key event_var(userid) which is a key of the keygroup Players
  // If you don't get that... Then re-read everything I've typed ;)
}
 
event player_say
{
  if (event_var(text) == "What is my name?") do
  {
    // Okay when a player types "What is my name?" we'll get the value of their username from the keygroup, then tell them it
    es_keygetvalue get_value Players event_var(userid) "Name"
    // Reading it from right to left we get we are getting the value which is held by the keyvlue "Name" within the key event_var(userid) which is held inside the keygroup Players and we are storing the value in get_value
    // get_value now contains the name of the player
    es_tell event_var(userid) Your name is server_var(get_value)
    // Just tell them their name
  }
}
 
event player_disconnect
{
  // Okay, the player has disconnected, so we need to free up some memory by deleting their key in the Keygroup. Again this is not necessary, but it's got practise.
  es_exists check key Players event_var(userid)
  // Check if the key exists, see player_activate
  ifx true(check) do
  {
    es_keydelete Players event_var(userid)
    // If the key exists then delete the player... Very similar to event player_activate only we don't need to re-create the key after.
  }
}

A note to remember:

Keygroups are slow, very slow.... If you only want to store 1 or 2 values on a temporary basis, you may want to look at playervar instead.

Keygroups can hold as many keys and keyvalues as you want, but once it's starts getting big, I'd suggest learning SQLite as it deals 'on access memory' which means only the column needed is loaded into memory rather than the whole database so it saves on A LOT of memory, and generally has massive speed increments over keygroups.

Hope you like this tutorial Wink

-freddukes