Chapter 5

From SphereWiki
Revision as of 12:18, 1 June 2009 by MrSugarCube (talk | contribs)
Jump to: navigation, search

(incomplete)

Tags

All these things you have learned so far seem rather restrictive don't you think? Well, I personally don't think they are very restrictive and I was able to script most things that people are scripting today in about version .40. But think about it. Items are restricted to MORE, MORE2, etc. Those poor characters only have PLOT2 to store stuff in before you have to start resorting to storing information on the variables of their backpack.


So SPHERE developers gave us a long-awaited feature:


The TAG.


Important TAG principle number one, even before you know how to use them:


ALL TAGS ARE STRINGS. PERIOD.


They are also just about the simplest part of SPHERE you will ever use. Here is an example of a tag:


SRC.TAG.JOE = 1


What did we just do? We just CREATED a variable on the SRC of this script. This variable is named TAG.JOE and has a value of 01. (Keep in mind that is the string 01, not the number 01.) It will be saved with the character and we can put ANYTHING WE WANT into it.


How's that for powerful?


Here are some more examples of TAGs:


ON=@DClick

SRC.TAG.CLICKS += 1
RETURN 1


ON=@Equip

SRC.TAG.GOOFYTAG = This is a really stupid tag.
SRC.SYSMESSAGE <SRC.TAG.GOOFYTAG> // Will see "This a really stupid tag."
RETURN 0 // Allow them to equip


ON=@UnEquip

SRC.TAG.GOOFYTAG = // remove the tag
RETURN 0 // Allow them to unequip


In those three examples, you have the three ways you can use a TAG.

  1. A TAG can store a number as in the first example. Unfortunately, it stores that number as a string, so we must use EVAL every time we want to use that number.
  2. A TAG can store a string, as in the second example. Actually TAGs always store strings, but this one is obviously a string.
  3. You can delete a TAG. We do this by typing the name of the tag and then an equal sign with nothing after it. Why would we ever want to delete a TAG? Well, TAGs, like everything else, use memory. The more memory you use, the more lag your server has.


TAG principle number two:


ALWAYS DELETE A TAG YOU ARE FINISHED USING.


You may not be finished using a TAG at the end of a script. Or even when the server shuts down. In fact, there are some TAGs you'll want to stay on the character forever. However, if you finish using a TAG for any reason, DELETE IT. It conserves memory and is good scripting practice in general.


Here is another important TAG principle. While the TAG is a very powerful feature, it has its limits. A TAG can ONLY be used on the following objects:

  1. Characters.
  2. Items.
  3. Regions. Yes, regions can have TAGs.


It's very hard to give examples of the use of TAGs without going into a complex system. Most complex systems will use two, three, or more PERMANENT tags. For example, a system involving experience points might store numbers in TAG.CURRENT_EXPERIENCE_POINTS and TAG.CURRENT_LEVEL. You'll find a good example of when to use TAGs to your advantage in chapters from now on, as I present more and more complex scripts. BTW, when you're dealing with tags, sometimes you need to check if a tag exists or if it has a value. If it doesn't exist SPHERE gives a stupid error on the console. To avoid that, we make TAG's default to 0 by using TAG0 instead of TAG if the tag doesn't exist. If you want to you can always use TAG0 instead of TAG to be safe. Say you write this line of code:


MORE = <EVAL <TAG.JOE>>


If TAG.JOE contains no value (or hasn't been defined yet), you will get an error on the console that says something like this: Undefined value ' '. To complicate matters, the value of MORE will not change, which will severely screw up your script. To prevent this, use the following method:


MORE = <EVAL <TAG0.JOE>>


In this case we have used TAG0 to access the TAG value. Accessing the TAG in this manner will return the value as normal, except for when TAG.JOE is undefined a "0" will be returned rather than a script error being raised.


The same trick can also be used when setting the value of a TAG. For example:


TAG0.JOE = <MORE>


As you may expect, this sets the value of TAG.JOE to whatever value is held in MORE. The difference however is that because we have used TAG0 when setting the value, if the value of MORE is zero then TAG.JOE will actually be cleared! This may initially sound undesirable but it offers the benefit of reducing the number of TAGs stored on the object. Since we can use TAG0 to retrieve a value of zero when a tag doesn't exist then you may be wasting memory by storing a large number of TAGs all with a value of zero. Of course if you do decide to use TAG0 when setting the value of a TAG then you should ensure that you also use TAG0 when reading that value back, or else you will quickly run into the aforementioned "Undefined value" script error.


CTags

CTAGs are temporary versions of TAGs that are only available with objects (i.e. online player characters). CTAGs are not saved and will be cleared when the player logs out. This means that you don't have to worry about removing the tag after using it, assuming the player logs out one day :). You can use CTAG0 too, used just the same as you can with TAG0. In short, if you are going to use tags that will no longer be needed after logging out, it is probably a good idea to consider using a CTAG.


Note: CTAG can only be used with online players. Attempting to read from or write to a CTAG on a logged out player will raise a script error.


Useful TAG/CTAG Functions

CLEARTAGS Removes all TAGs on an object, eg SRC.CLEARTAGS. Be careful with this as once the tag is gone there is no way to get it back.
CTAGLIST Displays a list of tags on a client to SRC.
CTAGLIST LOG Displays a list of tags on a client to the Sphere console (but not into logfile).
TAGAT.x.KEY Returns the name of the TAG at position x. (the first TAG is at position 0)
TAGAT.x.VALUE Returns the value of the TAG at position x. (the first TAG is at position 0)
TAGCOUNT This function returns the number of TAGs on an object.
TAGLIST Displays a list of tags on an object to SRC.
TAGLIST LOG Displays a list of tags on an object to the Sphere console (but not into logfile).