Chapter 9 - Revision history

Sirius at 20:19, 26 November 2010

2010-11-26T20:19:12Z

MrSugarCube at 18:29, 3 June 2009

2009-06-03T18:29:35Z

MrSugarCube at 15:40, 2 June 2009

2009-06-02T15:40:22Z

MrSugarCube at 15:11, 2 June 2009

2009-06-02T15:11:07Z

MrSugarCube at 14:29, 2 June 2009

2009-06-02T14:29:01Z

MrSugarCube at 14:14, 2 June 2009

2009-06-02T14:14:45Z

MrSugarCube at 13:29, 2 June 2009

2009-06-02T13:29:07Z

Show changes

MrSugarCube at 12:40, 2 June 2009

2009-06-02T12:40:39Z

MrSugarCube: Created page with ''''''(WIP)''''' ==How to "install" [EVENTS]== A basic event looks like the following: [EVENTS defname] code Looks just like every other thing we'...'

2009-06-02T12:32:54Z

Created page with ''''''(WIP)''''' ==How to "install" [EVENTS]== A basic event looks like the following: <spherescript>[EVENTS defname] code</spherescript> Looks just like every other thing we'...'

New page

'''''(WIP)'''''
==How to "install" [EVENTS]==
A basic event looks like the following:

<spherescript>[EVENTS defname]
code</spherescript>

Looks just like every other thing we've done so far doesn't it? Well events work the same way. They can be installed either in-game our through a script using the following:

<spherescript>EVENTS +defname
EVENTS=defname
EVENTS -defname</spherescript>

These are three very different commands. Some people tend to confuse them. Here is what they do:

'''EVENTS +DEFNAME''' 
Adds the event to the character's list of events. Yes, a character can have more than one event. Both of the following will respond to triggers called on the character:

<spherescript>SRC.EVENTS +e_death_event
SRC.EVENTS +e_ctf_event</spherescript>

'''EVENTS=DEFNAME''' 
This method is should not be used. It will erase all other events on the character in place of this one.

'''EVENTS -DEFNAME''' 
This will remove the specified event from the character.

'''''THE DEFAULT OBJECT OF AN [EVENTS] SCRIPT IS THE CHARACTER ON WHICH THE SCRIPT IS INSTALLED.'''''

==The order of event handling==
There are quite a few ways to add events to items or characters. These are:

'''''EVENTS +DEFNAME''''' 
Can be set by a function, another event, a player action, or inside a trigger (for example, the @Create trigger).

'''''TEVENTS=DEFNAME''''' 
In the body of the ITEMDEF or CHARDEF. There may be as many of TEVENTS lines as you wish.

'''''TYPE=DEFNAME''''' 
(Items only) In the body of the ITEMDEF. There can only be ONE base type definition. TYPEs are not only events, they also determine some basic behaviour of the item, and it's capabilities (for example, if an item is not of an equippable type, it cannot be equipped).

'''''DIRECT TRIGGERS''''' 
Poor man's events: As events are generally assortments of triggers what can be added to an item or character. You may also "hardcode" some trigger actions in the ITEMDEF/CHARDEF itself.

'''''ORDER OF FIRING''''' 
Look at these simple code examples:

<spherescript>[ITEMDEF i_triggertester]
ID=i_floor_wood
TYPE = t_testtype
NAME=TriggerTester
TEVENTS=e_tev_test

ON=@Create
EVENTS +e_ev_test

ON=@DClick
SERV.LOG item dclick from direct trigger

[TYPEDEF e_ev_test]
ON=@DClick
SERV.LOG dclick from event

[TYPEDEF e_tev_test]
ON=@DClick
SERV.LOG item dclick from tevent

[TYPEDEF t_testtype]
ON=@DClick
SERV.LOG item dclick from base typedef</spherescript>

This gives the following results:

<tt>item dclick from event 
item dclick from tevent 
item dclick from base typedef 
item dclick from direct trigger </tt>

The same for characters:

<spherescript>[CHARDEF c_testorc]
ID=c_orc
NAME=TestOrc
TEVENTS=e_tev_character

ON=@Create
STR = 100

ON=@NPCRestock
EVENTS +e_ev_character

ON=@DClick
SERV.LOG char dclick from direct trigger

[EVENTS e_tev_character]
ON=@DClick
SERV.LOG char dclick from tevent

[EVENTS e_ev_character]
ON=@DClick
SERV.LOG char dclick from event</spherescript>

The results:

<tt>char dclick from event 
char dclick from tevent 
char dclick from direct trigger </tt>

← Older revision		Revision as of 20:19, 26 November 2010
Line 1:		Line 1:
		+	{{Languages\|Chapter_9}}
		+
	==How to "install" [EVENTS]==		==How to "install" [EVENTS]==
	A basic event looks like the following:		A basic event looks like the following:

← Older revision		Revision as of 18:29, 3 June 2009
Line 731:		Line 731:

	We're subtracting one number between 0 and 5 from another. If one happens to be 0 and the other is 5, the answer will be 0 - 5 = -5. If it is the other way around, the answer will be 5 - 0 = 5. However, as we get closer to the middle, the numbers are the same. There is more of a chance of receiving a small number (3 - 2 = 1, 2 - 1 = 1, 4 - 3 = 1, etc) than a large one. This makes the script more interesting! :) Don't deny it. It's interesting. Say it. "This script is interesting." Now shut up and keep reading.		We're subtracting one number between 0 and 5 from another. If one happens to be 0 and the other is 5, the answer will be 0 - 5 = -5. If it is the other way around, the answer will be 5 - 0 = 5. However, as we get closer to the middle, the numbers are the same. There is more of a chance of receiving a small number (3 - 2 = 1, 2 - 1 = 1, 4 - 3 = 1, etc) than a large one. This makes the script more interesting! :) Don't deny it. It's interesting. Say it. "This script is interesting." Now shut up and keep reading.
		+
		+	[[Category:Tutorials]]

@@ Line 1: / Line 1: @@
 ==How to "install" [EVENTS]==
 A basic event looks like the following:
@@ Line 609: / Line 608: @@
 Like I said in the beginning, this tutorial isn't here to give you free scripts. It's here to teach you HOW to script. Although in two more sections you're going to get a free script all for yourself! Can you wait?  :)

← Older revision		Revision as of 15:11, 2 June 2009
Line 524:		Line 524:

	This is a rather simple script, and you'll see one big example that utilizes almost every useful character-based event.		This is a rather simple script, and you'll see one big example that utilizes almost every useful character-based event.
		+
		+
		+	==The Elusive @Death Event==
		+	Here are the object references available to you from within the @Death trigger:
		+
		+
		+	<tt>@Death Objects<br />
		+	SRC = the creature being killed<br />
		+	[] = the creature being killed<br /></tt>
		+
		+
		+	Any experienced admin will have encountered a particular obstacle when using this trigger. How do we know who killed the player? For a long time ACT was considered to be the killer, and many still believe this is the case. In fact, if you were to right now add an @Death trigger to a player, kill them, and check their ACT. You would more than likely discover that ACT did indeed point to the killer, yet here I am telling you that '''ACT is _NOT_ the killer in @Death!'''
		+
		+
		+	You can protest all you like, but it is a simple fact that the ACT reference is completely meaningless within the @Death trigger. ACT is used by various internal systems and means different things. For example if you were to get a player to craft an item and then target them <font color="darkred">.xhits 0</font> they will die, and you will discover that ACT actually points to the item the player was crafting with!
		+
		+
		+	If you want to determine who killed someone, there are two safe ways of doing so:
		+	* Use the [[@Kill]] trigger, which fires when one character kills another (not discussed in this chapter)
		+	* Use the [[ATTACKER]] property, which allows you to access a full list of characters which have harmed a character.
		+
		+
		+	Anyway, back to the topic at hand.
		+
		+
		+	Have you ever played Asheron's Call or Everquest? When you die in either of those games, you are returned to a particular location of your choosing, but you must choose the location prior to death. We're going to make a system similar to that. Here's the script, and then I'll explain it:
		+
		+
		+	<spherescript>[PLEVEL 1]
		+	deathpoint
		+
		+	[FUNCTION deathpoint]
		+	IF (<REGION.FLAGS> & region_flag_guarded) // Are they in a guarded area?
		+	// If so, we need to set this as their new death location.
		+	TAG.DEATH_LOC = <P>
		+	EVENTS +e_death
		+	ENDIF
		+	RETURN 1
		+
		+	[EVENTS e_death]
		+	ON=@Death
		+	IF (<BRAIN>) // We don't want this script on NPCs by accident (player brain = 0 = false)
		+	RETURN 0
		+	ENDIF
		+	RESURRECT // Prevent death
		+	IF !(<ISEMPTY <TAG.DEATH_LOC>>) // make sure the TAG has is not empty/blank
		+	GO <TAG.DEATH_LOC>
		+	ELSE // No tag, send them to a default location, such as Britain
		+	GO Britain
		+	ENDIF
		+	RETURN 1 // No death recorded, no corpse left behind</spherescript>
		+
		+
		+	I think that this requires a little explanation. First, we use a function differently than we've seen in the past:
		+
		+
		+	This is an in-game command. You use it by typing .deathpoint in-game. In an in-game function, the objects are as follows: The person executing the function is the SRC. If they would type .xdeathpoint rather than .deathpoint, they would get a target. The target of the function is the default object.
		+
		+
		+	When the player uses this function, we check to see if he's in a town. The purpose of this function is to let the player decide the place he goes when he dies. It can be any location as long as it's within the guarded area. So if he is in a guarded area, we simply store his current position into a TAG. We also install the event e_death on the player. Look over it until you understand what's going on. There's nothing here we haven't seen before.
		+
		+
		+	The next part is an [EVENTS] section, which contains an @Death event. (Duh.) I think that the only part of this script that isn't things we've done before (or explained rather clearly in the comments) is the purpose of the <ISEMPTY ...> function in the middle of the event. Say, by some strange fluke in the game, this player has the e_death event installed, but the value for TAG.DEATH_LOC hasn't been set yet. When the @Death script is triggered (by the death of the player), we run into the following statement:
		+
		+
		+	<spherescript>GO <TAG.DEATH_LOC></spherescript>
		+
		+
		+	If TAG.DEATH_LOC has no value, this statement is meaningless and you WILL get an error. So we use the following statement to check if it has a value:
		+
		+
		+	<spherescript>IF !(<ISEMPTY <TAG.DEATH_LOC>>)</spherescript>
		+
		+
		+	If the tag does have a value, this will evaluate to some scary number, which is not blank and therefore true. If it has no value, the statement simply becomes <tt>IF !(<ISEMPTY >)</tt>, which of course is false.
		+
		+
		+	The @Death event can be a powerful tool if used wisely. A few other things it could be used for:
		+
		+	# Special race abilities (i.e. Last Chance, Final Attack type abilities)
		+	# A leveling system where NPCs have the @Death event to give experience to the killer
		+	# What you just saw up above
		+
		+
		+	Like I said in the beginning, this tutorial isn't here to give you free scripts. It's here to teach you HOW to script. Although in two more sections you're going to get a free script all for yourself! Can you wait? :)

← Older revision		Revision as of 14:29, 2 June 2009
Line 456:		Line 456:

	These are just a few applications of these events. As you can probably imagine, as with anything else in SPHERE, the applications are limitless.		These are just a few applications of these events. As you can probably imagine, as with anything else in SPHERE, the applications are limitless.
		+
		+
		+	==NPC-based Events==
		+	Hmm, you may be saying. How do we tell if an event can be used on a player or just on NPCs? (Remember, " NPC " means any computer-controlled character, be it a monster, a vendor, a banker, or anything)
		+
		+	Well, there's a rather easy way. Let's look at a list of some NPC-only events:
		+
		+
		+	<spherescript color="darkgreen">@NPCAcceptItem // NPC accepts item (needs)
		+	@NPCHearGreeting // hear greeting (can be triggered by most speech i found)
		+	@NPCHearNeed // someone mentions sopmething i want (needs)
		+	@NPCHearUnknown // rather obvious
		+	@NPCRefuseItem // NPC don't want this (needs)
		+	@NPCRestock //vendor/ npc restocks.. Auto called at on=@Create
		+	@NPCSeeNewPlayer // see new player
		+	@NPCSeeWantItem //see something i want (needs)</spherescript>
		+
		+
		+	Those aren't my comments. :) Something else you'll notice is that some of them comment about this concept of NEEDS. We'll cover that in this section as well. Actually, why don't we cover that first?
		+
		+
		+	If you look in an NPC script, it'll have a property called DESIRES. It looks something like this:
		+
		+
		+	<spherescript>DESIRES=i_gold</spherescript>
		+
		+
		+	This means that the NPC wants gold. It's a NEED of this NPC to acquire gold. He wouldn't be happy otherwise. And we all know what happens when you get an NPC angry. (They say "Shut up and fight, coward!") Other NPC needs are, for example, fire for fire elementals, or t_crops for crows. Sometimes there's even t_grass for animals like sheep. But humans don't need to eat. All they need is money. I believe that an NPC will also accept any item that it sells (someone verify this).
		+
		+
		+	Now that you understand this concept of desires and needs, here's a more descriptive list of these events:
		+
		+
		+	<spherescript color="darkgreen">@NPCAcceptItem - An item is dropped onto the NPC and identified as one of the NEEDS of this NPC. RETURN 1 will bounce the item back to where it came from. The item is stored in ACT.
		+	@NPCHearGreeting - Someone speaks directly to this NPC who hadn't spoken to him before. The NPC will remember for a short time that the player talked to him. (See later chapters on memory.)
		+	@NPCHearNeed - Someone says the name of one of the needs of the NPC. Such as "gold". In this event, the variable <needname> will print out the name of the need that was spoken.
		+	@NPCHearUnknown - Someone says something the NPC does not understand. This is where the "Huh?" and "I don't understand thee!" come from.
		+	@NPCRefuseItem - An item is dropped onto the NPC that he has no NEED for. The item is bounced back to where it came from. The item is stored in ACT.
		+	@NPCRestock - This occurs about once every half hour. BUY and SELL items should be placed under this event, along with any loot and clothing you want on your NPC. This is also called on creation of the NPC (since technically, he IS restocking for the first time).
		+	@NPCSeeNewPlayer - The most useful of the NPC events, this one fires when the NPC sees a player he didn't previously see. RETURN 1 from this event will prevent the NPC from remembering that he has seen the player, and RETURN 0 will let him remember.
		+	@NPCSeeWantItem - The NPC sees something he wants on the ground and walks toward it.</spherescript>
		+
		+
		+	Now let's see some examples of the use of these events. The examples that come with SPHERE (i.e. in sphereevents.scp in the 55i package) are huge and complex and deal with a lot of sector complexity and karma issues to determine which response to give. Each event has about 30 potential spoken responses.
		+
		+
		+	So here's a simpler example using what I see as the most useful of events. This could, for example, be placed on a new NPC to give him special abilities. We're going to assume that when this NPC is standing still, he is invisible. Actually in the last section, you're going to see the completed script for this NPC.
		+
		+
		+	<spherescript>ON=@NPCSeeNewPlayer
		+	IF (<DISTANCE> > 5) // If the player is more than 5 steps away
		+	RETURN 1 // Don't remember him so the event fires when he gets closer
		+	ENDIF
		+	// We can only get this far if he is closer than 5 steps away
		+	SAY Boo!
		+	INVIS 0
		+	ATTACK // Attacks the SRC of the event
		+	RETURN 0</spherescript>
		+
		+
		+	This simple script would make a surprisingly diverse number of creatures with just a few variations. Do you understand it? Well, if you don't here's my explanation:
		+
		+	# The NPC sees a player it doesn't remember seeing before and the event takes place.
		+	# We check to see how far away the player is. DISTANCE will return the distance the object referenced (in this case the default object) is from the SRC of the event (in this case the player who is being seen). If the player is too far away, we don't want the NPC to react. This event fires as soon as the creature first notices a player nearby, meaning up to about 12 tiles away depending on the player's resolution. We return 1 here so the NPC will forget that he saw the player and the event will fire again a second or so later.
		+	# If the player is close enough, the NPC appears (INVIS 0) and says "Boo!" to scare the player. It then proceeds to attack him. We RETURN 0 at the end of this second section because we don't need the NPC to forget the player again.
		+
		+
		+	This is a rather simple script, and you'll see one big example that utilizes almost every useful character-based event.

← Older revision		Revision as of 14:14, 2 June 2009
Line 361:		Line 361:

	This will set all sectors in the region to the "winter" season. Keep in mind that sectors can "overlap" regions, meaning that you may get some winter in other surrounding regions as well.		This will set all sectors in the region to the "winter" season. Keep in mind that sectors can "overlap" regions, meaning that you may get some winter in other surrounding regions as well.
		+
		+
		+	==The Clicky Events==
		+
		+	'''@DClick, @Click, and @Profile'''<br />
		+	These events are surprisingly underused since they have so many specific purposes. Here's a summary of what they do:
		+
		+
		+	'''@Click'''<br />
		+	User has been clicked by someone.
		+
		+
		+	'''@DClick'''<br />
		+	User has been double-clicked by someone.
		+
		+
		+	'''@Profile'''<br />
		+	Someone is trying to look at the user's profile.
		+
		+
		+	Now, these are three events where the RETURN value is exceedingly important. All of them have very expected default actions, such as the following:
		+
		+
		+	{\|
		+	\| '''Trigger''' \|\| '''Default Action'''
		+	\|-
		+	\| @Click \|\| The character's name pops up above his head (An allnames macro counts as @Click)
		+	\|-
		+	\| @DClick \|\| The character's paperdoll pops up
		+	\|-
		+	\| @Profile \|\| The character's personal profile pops up
		+	\|}
		+
		+
		+	Now, if you RETURN 0 or 2 from any of these events, the default action will take place. The user's name will pop up as usual, or their paperdoll will appear on the clicker's screen. But there are occasions where you don't want this to happen. For example, I created an event for one of my custom spells which allowed the user to double-click any creature for a given amount of time and shoot fireballs at that player.
		+
		+
		+	Here's an example script for the @Click event. This puts [MURDERER] above the player's name when he's clicked if his kills are above a certain amount. I had something similar on my server Talocon where new players (players with skills below a certain level) received a [NEWBIE] tag and certain protections.
		+
		+
		+	<spherescript>[EVENTS e_murderer]
		+	ON=@Click
		+	IF (<KILLS> > 5)
		+	MESSAGE [MURDERER]
		+	ENDIF
		+	RETURN 0 // Display his name</spherescript>
		+
		+
		+	We want to use a message here, rather than a SYSMESSAGE or a SAY so the text appears above the default object. In this case that's the player containing this event. SRC happens to be the player doing the clicking. It could be the same if someone clicks him- or herself, but that's usually not the case.
		+
		+
		+	(Remember, to install the events, we use the command in-game .events +e_murderer. In a script we use the same command without the dot.)
		+
		+
		+	We RETURN 0 from this event so that the player's name will actually be displayed. We could easily use a MESSAGE to put the player's name above his head, but it wouldn't be in the specific color necessary.
		+
		+
		+	Here's an example of the @DClick event. The effect of this event is to prevent players from seeing paperdolls of those outside of their guild. You'll also learn here how to check whether or not two people are in the same guild.
		+
		+	<spherescript>ON=@DClick
		+	IF (<SRC.UID> == <UID>) // did the player double click himself?
		+	RETURN 0
		+	ELSEIF (<SRC.MEMORYFINDTYPE.memory_guild.LINK.UID>) && (<SRC.MEMORYFINDTYPE.memory_guild.LINK> == <MEMORYFINDTYPE.memory_guild.LINK>)
		+	SRC.SYSMESSAGE You are in the same guild. You may view this paperdoll.
		+	RETURN 0 // let them see the paperdoll
		+	ENDIF
		+	RETURN 1 // don't</spherescript>
		+
		+
		+	I don't know if you'd want to use this event in your shard or not. Remember, it's up to you what your shard is like!
		+
		+
		+	Perhaps the most unused event is @Profile. It could be incredibly useful for various applications on a server.
		+
		+
		+	<spherescript>ON=@Profile
		+	DIALOG d_info
		+	RETURN 1</spherescript>
		+
		+
		+	You should have learned about dialogs in [[Chapter 8]]. For now you need to know that this script would make a dialog called d_info appear on the screen of the SRC (the profile clicker). Perhaps contained in this dialog could be information about the person whose profile has been clicked. It may be that you want to include an IF statement like so:
		+
		+
		+	<spherescript>ON=@Profile
		+	IF (<SRC.ISGM>)
		+	DIALOG d_info_gm
		+	ELSE
		+	DIALOG d_info
		+	ENDIF</spherescript>
		+
		+
		+	This would check first to see if the user was a GM and display a different amount of information. You've seen in [[Chapter 8]] how you can customize the appearance of this dialog down to the most detailed level.
		+
		+
		+	These are just a few applications of these events. As you can probably imagine, as with anything else in SPHERE, the applications are limitless.

← Older revision		Revision as of 12:40, 2 June 2009
Line 125:		Line 125:
	char dclick from tevent<br />		char dclick from tevent<br />
	char dclick from direct trigger<br /></tt>		char dclick from direct trigger<br /></tt>
		+
		+
		+	==Item-based events==
		+	There are two main types of events:
		+
		+
		+	'''ITEM EVENT'''<br />
		+	Triggered when any player interacts in a certain way with a given item.
		+
		+
		+	'''PLAYER EVENT'''<br />
		+	Triggered when a given player interacts in a certain way with ANY item or performs certain tasks, such as moving, casting a spell, crafting an item, etc.
		+
		+
		+	In the item script, the item is the default object. In the player script, the player is the default object.
		+
		+
		+	So what are these events? Well here's a short list of some of them:
		+
		+
		+	<tt>@itemDClick - Triggered when the player double-clicks any item. The reference object for the item is ACT.<br />
		+	@itemEquip - Triggered when the player equips any item. The reference object for the item is ACT.<br />
		+	@itemUnEquip - Triggered when the player unequips any item. The reference object for the item is ACT.<br />
		+	@itemClick - Triggered when the player double-clicks any item. The reference object for the item is ACT.<br />
		+	@itemStep - Triggered when the player steps on any item. The reference object for the item is ACT.<br /></tt>
		+
		+
		+	Notice anything similar between those descriptions? If you don't, I think you need to go back and take reading lessons. That's right. In ANY script beginning with @item, ACT is the item acted upon. How about that. Why do you suppose they called it ACT?
		+
		+
		+	In any case, for @item scripts, the following is true:
		+
		+
		+	<tt>ACT = the item acted upon<br />
		+	SRC = the character doing the acting (the player with the event)<br />
		+	[] = the character doing the acting (the player with the event)<br /></tt>
		+
		+
		+	Notice that in this case, SRC and the default object both refer to the character. THIS IS NOT ALWAYS THE CASE. If you want to refer to the character, get in the habit of using the default object rather than SRC in an event. Now, let's take a look at a rather useless event:
		+
		+
		+	<spherescript>[EVENTS e_test_events]
		+	ON=@itemStep
		+	SYSMESSAGE You have stepped on <ACT.NAME>!
		+	RETURN 0</spherescript>
		+
		+
		+	Put this script in one of your files and resync your server. Now, go in-game and type: <font color="darkred">.xevents +e_test_events</font> Target yourself. Congratulations, you just installed an event on yourself. From this point forward, until you remove the event, any time you walk on an item, you'll get an irritating message. Try it. Go around walking on things! Make an item called "a bug" and walk around stepping on them.
		+
		+
		+	Ok stop walking on things and continue reading now. :)
		+
		+
		+	Here's a little secret I bet you've already guessed: ALL ITEM EVENTS (except @Timer) HAVE AN @item COUNTERPART. This means that @itemPickUp_Pack, @itemTargOn_Char, @itemTargOn_Item, and all others should all (in theory) work.