Chapter 4

(incomplete)

Introduction to Objects

Your first glimpse of real scripting!

First and foremost, you MUST understand the object structure of the SPHERE system. Now, because SPHERE interacts with something visible, most of these objects are relatively easy to understand. But first, you must understand this simple fact about object-oriented programming (a term I'm sure all you programmers havel come to know and fear):

OBJECT-ORIENTED SCRIPTING IS CENTERED AROUND OBJECTS.

Duh.

Actually, it isn't as "Duh" as you may think. Here is a list of the objects available to you in a SPHERE script:

Who	What
SRC	The "source" of an event. If an item is damaged, the SRC is whatever damaged it. If a player is hit, the SRC is whoever hit the player. If an item is double-clicked, the SRC is the player who double-clicked it. The ONLY event that does not have a SRC, as we shall see later, is @Timer, for good reasons. Note that usually on functions the SRC isn't always the one who called the functions, but the default object (I or just an empty thing, eg: <I.NAME> or <NAME> are the same thing.
ACT	The last object acted upon by the referenced character, for example on that char trigger @ItemDclick, ACT is the item the player double-clicked.
TARG	The object targetted by the character.
CONT	The container of the object.
TOPOBJ	If an object is buried in several containers within containers, this is always the top-level container before you get to the world. If an item is buried in a player's backpack, TOPOBJ is the player.
ACCOUNT	The account of a player, obviously.
REGION	The current region/area a player is in.
SECTOR	The world is divided into 64 by 64 tile sectors (by default but you can change it by setting the MAPx settings (look at sphere.ini section for this)). This is the player's current sector.
SERV	used to call server commands, like serv.save, serv.allclients, etc. Object references from SERV LASTNEWITEM The last item created from NEWITEM/NEWDUPE functions. LASTNEWCHAR The last character created by NEWNPC/NEWDUPE functions.
LINK	The object referred to in the LINK property of an item.
UID.x	The object with UID equal to X.
FINDLAYER.X	The object in layer X.
FINDCONT.X	The xth object in the container referenced.
FINDID.x	The first object with ID of x in the container.
FINDTYPE.x	The first object with TYPE of X in the container.
NEW	The newer object created from NEWITEM/NEWNPC/NEWDUPE functions.
OBJ	An empty object variable, which you need to set to use, eg: OBJ = <FINDLAYER.layer_bankbox> OBJ.SAY HEHE will make I's bank box say hehe. NOTE: OBJ is a global variable so it can possibly interfere with other scripts. It's best to set it back to nothing when not in use in a certain script.
REFx	This works in the same way as OBJ except the reference is local and will not interfere with other scripts. 'x' is a number between 1 and 65535, allowing you to reference as many objects as you need simultaneously (e.g. REF1 = <FINDLAYER.layer_bankbox>).
FILE	Call the file commands on the current FILE object.
DB	See MySQL
PARTY.MEMBER.x	The xth party member of the referenced party.
GUILD.MEMBER.x	The xth guild member of the referenced guild.

As you can see, we're rather limited in what we can do! Actually, not really. With the current scripting system, you can do almost anything imaginable with SPHERE. It might run slow or be laggy, but it can be done. Those last five events (the ones with the x in them) are complex and I don't expect you to know how to use them yet.

Now that we know the objects, we need to know how to access the properties of those objects, and above all, do things to those objects. We use the dot operator (.) to access properties of objects. For example:

SRC.STR
ACT.MOREP
SRC.ACT.MOREP
SRC.TARG.HITS
SRC.DAMAGE {1 5} 01 <ACT>
SERV.NEWITEM i_gold
NEW.AMOUNT 10000
SRC.TARG.KILL
CONT.KILL
FINDLAYER.layer_backpack.FINDID.i_gold.AMOUNT

I don't expect you to understand what all of these things do yet, but you will by the end of this chapter.

Some notes: You must also understand that OBJECTS aren't ITEMS, when someone say OBJECT they probably mean a character/item/some of those in the table. The objects can also be called REFERENCE, for example, ACT.STR 100 the reference is ACT.

Here is the next principle of SPHERE scripting:

ALL ACTIONS ARE TRIGGERED BY EVENTS OR FUNCTIONS, WHICH DEFINE THE OBJECTS

Nothing happens in a SPHERE script that just sits there. A player, or something else in the game, must do something to an item or a character for a script to execute. For example, being hit executes the @GetHit script on the person being hit, and @Hit on the hitter. Stepping on an item executes the @Step script on the item and the @ItemStep script on the player. When an item is double-clicked, @DClick is executed on the item and @ItemDClick is executed on the player.

If the player is the one who double-clicks the ITEM, he becomes SRC. If he targets an item, in the @Targon_Item script, the player is SRC, and the item he targeted is SRC.TARG.

We refer to an event like this:

ON=@DClick

Following that line would be everything that we want to happen when the player clicks the item.

We'll see examples in the next section of the use of both events and objects.