View source for Script Tutor

= Part 0 =

== PREFACE ==

Ok the intent of these documents is not to teach you every little detail about scripts. It is ment to give you an idea of how scripts work and hopefully, teach you how to make some simple scripts. Not all the commands are covered in these documents. For more detail on any subject please consult other topics in this Wiki.

This document is not complete by any means.  consider it a growing "work in progress".

= Part 1 =

== The Anatomy of A Script ==


Most of this stuff is self explanatory but, we will go over it anyways.

Anatomy of a script
----
 Name:                 ,Vnum:[   ], Type:
 Trigger flags:        ,NArg:     , Arg List:
 Commands
----

=== Name: ===
This is just a small label to leave a brief description of the script. You do not need to put in a name for your script as it has no effect on the performance, however it is a good idea so you can easily see what you were working on at a later date.

=== Vnum:[  ] ===
This is the virtual number of the script. a script is automatically assigned a virtual number upon creation.


=== Type: ===

This indicates what the script is going to be attached to and what set of commands the script can use. There are currently three differant script types.

* '''MOB''' - This type of script is for use only on mobiles and will understand mobile trigger flags and mobile commands.

* '''ROOM''' - This type of script is for use only on rooms and will understand room trigger flags and room commands.

* '''OBJ''' - This type of script is for use only on objects and will understand object trigger flags an object commands.

It is important that you do not assign a script to something other than the type. i.e. do not assign a mobile type script to a room or object.  This will cause errors.

=== Trigger flags: ===
This describes the events that will cause your script to run.  The different trigger types will be discussed later.

=== NArg: ===
This is a number argument. The purpose of Narg is dependent on the type of trigger used. Some triggers do not need a number argument.

=== Arg list: ===
This is a string (word) argument. The purpose of Arg List is dependent on the type of trigger used. some triggers do not need an arg list.

=== Commands: ===
This is the body of your script. When the script is triggered it will execute the commands put in this area.

= Part 2 =
== Trigger Flags ==

Each type of script (mob/room/obj) has different types of triggers available for use.  Do not assign more than one trigger flag per script. There is one exception to this rule which we will cover later. Some of these triggers list variables set after them. We will go into the different variables and what they do later. This document does not cover all trigger types, only a few basic ones. Refer to
this wiki for more details.


=== Random (usable by: Mob/Room/Obj) ===
This type of trigger is checked to see if it will be run every 13 seconds in the game. When the trigger is checked, it has a percent chance that it will be run. The percent chance is determined by the value given to NArg. i.e. if narg is set to 10, there will be a 10 percent chance the script will be run every 13 seconds.  This trigger type is only checked when there is someone in the zone.  This trigger flag does not use Arg list.

=== Command (usable by: Mob/Room/Obj) ===

This type of trigger is checked whenever someone types a command in the same room as the mob/room/obj with the script.  The command that is used to trigger the script is determined by the value of Arg list: i.e. if you had a trigger flag Command, and Arg List was set to look, the trigger would be executed when someone typed look. or an abbreviation of look (loo, lo, l would all trigger the script). A command will always override a normal command. This trigger flag does not use NARG.

'''Variables set:''' actor, arg

'''Notes:''' When used with an object, Narg determines where the object must be for the script to be run. Narg 1 means the object must be in the player's equipment to run. Narg 2 means that the item must be in the inventory to run. Narg 4 means the item must be in the same room as the character to run. The numbers can be added to combine areas. i.e. Narg 3 would mean the the item can be either in the player's equipment or in their
inventory to run, Narg of 7 would mean that the item can be in the player's inventory, equipment or on the ground to run.

=== Speech  (usable by: Mob/Room) ===
This trigger is checked when someone speaks in the same room as the mob/room with this script. Narg is used to specify if the trigger is looking for a phrase (Narg:0) or a word from a list (Narg:1).  The phrase or list is set in Arg list. i.e. if NArg was set to 1 and Arg list was set to : this that other anyone saying something containing one of those words would set off the trigger.

'''Variables set:''' Actor

=== Greet (usable by: Mob/Room) ===
This Trigger is checked when someone enters the [room/same room as the mobile]  that has this trigger. The percent chance that it is run is set by Narg. Arg list is not used.

'''Variables set:''' Actor

'''Notes:''' The greet trigger on a mob will only be activated if the mob will only be activated if the mob can see the person enter the room.

=== Fight (usable by: Mob) ===
This trigger is checked every round of combat while the mob is fighting. The percent chance that it will be run set by Narg. Arg list is not used.

'''Variables set:''' Actor

=== Get  (usable by: Obj) ===
This trigger is checked when someone tries to get the object with the script. the percent chance it will be run is set with narg. arg list is not used. If the script returns a 0 the item is not picked up. Otherwise the object is picked up. Arg list is not used.

'''Variables set:''' Actor

=== Drop (usable by: Obj) ===
This trigger is checked when someone tries to drop an object with the script. Narg sets the percent chance that the script will be run if th script returns the value of 0 the object is not dropped.  Otherwise the objet is dropped. Arg list is not used.

'''Variables set:''' Actor

=== Wear (useable by: obj) ===
This trigger is checked when a person attempts to wear the object.  If the script returns a 0 the object is not worn. Arg list and narg are not used.

'''Variables set:''' Actor

=== Triggers not covered ===
* Act       (Mobile)
* Death     (Mobile)
* Greet-All (Mobile)
* Entry     (Mobile)
* Receive   (Mobile)
* Hitprcnt  (Mobile)
* Bribe     (Mobile)
* Give      (object)
* Enter     (room)

For details about these triggers please refer to [[ROOMFLAGS]], [[OBJFLAGS]], and [[MOBFLAGS]].

= Part 3 =
== Variables ==

Variables are used in scripts to store/represent numbers and text.
Variables appear as a name sourrounded by percent signs (%). for
example the variable 'actor' is represented by '''%actor%'''.  When a script
comes across a variable it replaces it with the value stored within.

There are two types of variables, Global and Local. when the script
searches for a variable, first is searches the global, then the local
variables.

=== Global Variables ===
Global variables are useful for giving your scripts some ammount of
memory. They also allow you to share variables between scripts on the
same obj/room/mob.

Global variables remain until they are removed with the command
unset, or a reboot/crash. If the variable is on a mobile, global variables
will be removed if the mobile dies. If the variable is on an object,
the variables will be preserved if the item is rented/stored/buried.


=== Local Variables ===
Local variables are only usable by the script that assigns them. They
are removed once the script has finished executing.

Some trigger types automatically set up some local variables for you to
use. These are generally referred to as field variables. The most common
field variable setup is 'actor'. They hold information in various fields
that can be accessed using '''%variable.field%''' valid fields are listed below.
For example '''%actor.name%''' would return the name of the character. Mob, room
objects always set the 'self' field variables.


Characters (used by variables: self[for a mob]/actor)
{| border=1 style="border-collapse: collapse"
|-
| align=center | '''Name'''
| align=center | '''Description'''
|-
|| name 
|| returns the characters name.
|-
|| alias        
|| returns a mobs alias list. returns nothing if the actor is a player character.
|-
|| level
|| returns the characters current level.
|-
|| gold
|| returns the ammount of gold on the character.
|-
|| clan
|| returns characters clan as a string, if the character is not in a clan it returns no_clan.
|-
|| sex
|| returns characters sex as a string
|-
|| himher
|| returns him or her based on sex.
|-
|| hisher
|| returns his or her based on sex.
|-
|| canbeseen
|| mob triggers only, returns 1 if the mob can see the actor, or 0 if not.
|-
|| class
|| gives characters class as a string.
|-
|| race
|| returns the characters race as a string.
|-
|| vnum
|| returns the vnum of a mob or -1 fir PCs.
|-
|| str
|| returns characters str
|-
|| stradd
|| returns characters stradd
|-
|| dex
|| returns characters dex
|-
|| con
|| returns characters con
|-
|| int
|| returns characters int
|-
|| wis
|| returns characters wis
|-
|| cha
|| returns characters cha
|-
|| room
|| returns the vnum of the room the character is in.
|-
|}

 Objects (usable by variables: self[for an object]/object)
 name         returns alias list of the object
 sortdesc     returns the short desc of the object
 vnum         returns the vnum of the object
 type         returns the type of the object as a string
 val0         returns the value stored in v0
 val1         returns the value stored in v1
 val2         returns the value stored in v2
 val3         returns the value stored in v3
 min_level    return the min_level of the object

 Rooms (usable by variables: self[for a room]/room)
 name         returns the name of the room
 north        returns the vnum of the exit north*
 east         returns the vnum of the exit east*
 south        returns the vnum of the exit south*
 west         returns the vnum of the exit west*
 up           returns the vnum of the exit up*
 down         returns the vnum of the exit down*


* Some variable fields are not covered here. please refer to [[VARIABLES]] to get an accurate listing of all variable fields.

=== Special variables ===
==== random ====
This variable returns a radom number between 1 and the field value each time it is called.

For example: 

 set num %random.10%

will return a number between 1 and 10.

==== arg ====

This variable contains whatever is typed after a command trigger. For example, if a command trigger is ''drink'' and a player types "drink water", ''arg'' is set to ''water''

= Part 4 =
== Commands ==

The commands are the actual meat of a script. When a script is run it executes all the commands in order. The following is a list of some basic commands available.

=== Comments (*) === 

You can make comments in your code by starting the line with an astrix ex.  

 * this is a comment and wont be executed.

=== SET ===
Set allows you to set the value of an existing variable. If you set the value of a variable that does not exist the variable will be created.

Usage:
 set <variable name> <value>

ex. 
 set var1 1

this will set the value of var1 to 1

=== UNSET ===
This command unsets a variable (basically deleting it).

usage:
 unset <variable name>

ex. 
 unset var1

=== EVAL ===
This command performs mathematical operations and stores them in a variable. While it's not always necessary it's a good idea to enclose the expression you want evaluated in parentheses.

usage:
 eval <variable> <expression>
ex. 
 eval result (5 + 4)

This would add 5 + 4 then store that number in the variable named result.

=== GLOBAL ===
This command changes a local variable into a global.  A global variable is visible to all scripts on the mob / object / room that the script is attached to.  This is useful for situations where you want one script to set a value, and another script to react based on that value.

usage:
 global <variable name>
ex.
 set val1 1
 global val1

This would make the variable 'val1' a global variable.

=== WAIT ===
This command causes the script to pause for a certain length of time.  The number placed after the wait statement tells the script how long to delay in seconds.

usage:
 wait <number>
ex. 
 wait 5

This will make the script pause for 5 seconds

=== HALT ===
This command ends the script execution immediately.

Usage:
 halt

=== RETURN ===
Return sets the value of the trigger itself. Normally a script returns a value of 1. What this means is, the mud acknowledges that the script was triggered/executed and  wont send the command back to the mud. If a script returns a 0, the command/action that triggered the script will be sent to the mud after the script is executed.

usage:
 return <value>
ex. Say we wanted a script on a mob that blocked female characters from
kissing it.

 if ("%actor.sex%" == "female")
   return 1
 * this blocks the command from going back to the mud making
 * the command have no effect.
 else
   return 0
 * this lets the command pass back to the mud allowing the action to
 * be performed.
 end

=== IF/ELSEIF/ELSE ===
The if statement is used to check if a condition is true. If the expression is checked and found to be true/correct then the code that follows is performed. otherwise the code following it is skipped. An END statement must follow code of an IF statement. to check more than one expression you can use ELSEIF after an IF statement. An ELSEIF statement is checked only if the first IF statement is found to be false. You must enclose the statement to be checked  in parentheses.  When referencing a string in an expression be sure to enclose it in double quotes.

usage:
 if (<expression>)
   command
   command
   ...
 elseif (<expression>)
   command
   command
   ...
 end

ex.
 * the first if statment is false/incorrect
 * so the commands following will run
 * the elseif statment is true/correct so the
 * commands following wil be run

 if (1 == 2)
   halt
 elseif (1 == 1)
   say one is equal to 1
 end


=== OPERATORS FOR EXPRESSIONS ===
A false expression is any expression that evaluates to 0, or an empty string. A true expression is any expression that evaluates to anything else. These operators can be used to write your expressions.

 &&    Logical and
 ||    Logical or
 ==    Equivalance
 !=    Inequality
 -     subtraction
 +     addition
 *     multiplication
 /     devision
 !     negation


COMMANDS SPECIFIC TO SCRIPT TYPE

MOB COMMANDS
 Mobs can use all basic actions available to a player as commands. This
includes socials, speaking on channels, moving, etc. however there are
also a few extra commands that are available.

MECHO
 This command will send a message to everone in the same room as the mob.

usage:
MECHO <message>

MECHOAROUND
 This command will send a message to everyone in the room except for the
target.

usage:
MECHOAROUND <target> <message>

MSEND
 This command will send a message only to the target.

usage:
MSEND <target> <message>

MFORCE
 This command will force the target to do perform an action. (much in the
same way that the immortal force command works)

usage:
MFORCE <target> <command>

MLOAD
 This command loads an object or mob into the room or mobs inventory.
If an object is loaded it will appear in the mobs inventory unless it
does not have the 'TAKE' flag, in which case it will load into the room

usage:
MLOAD <mob/obj> <vnum>

MTELEPORT
 This command will teleport the target to a room. If the target is 'ALL'
it will teleport all people in the room.

usage:
MTELEPORT <target> <room>

OBJECT COMMANDS
 Alot of the object commands work the same way as mob commands except
the name of the command is slightly changed.

OECHO
 This command is used the same as mecho.

OECHOAROUND
 This command is used the same as mechoaround.

OSEND
 This command is used the same as msend.


OFORCE
 This command is used the same as mforce.

OLOAD
 This command varies froom mload only in the sense that it always loads
objects on the ground in the room the object is currently in.

OTELEPORT
 This command is used the same as mteleport.

ROOM COMMANDS
 Just like objects, most of the commands are the same as mob commands
only with a slightly differant name.

WECHO
 This command is used the same as mecho.

WECHOAROUND
 This command is used the same as mechoaround.

WSEND
 This command is used the same as msend.

WLOAD
 This command is used the same as mload except that if an object is loaded
it will always load in the room.

WFORCE
 This command is used the same as mforce.

WTELEPORT
 This command is used the same as mteleport.


This document does not explain all the commands available. For more
details and a list of all available commands refer to schelp.


= Part 5 =
== TIPS AND EXAMPLES ==

When possible try to make scripts reusable.

Instead of making many scripts that do something similar it's usually a good idea to make 1 script that can be used in all places. Some helpful things to accomplish this are using variables like '''%self.name%''' in echos instead of actually writing in the name.  Using if statements to check the room number for any special commands needed in a specific place.

Lets say we wanted to make a script for 2 different dance instructors in 2 different rooms. We want the script make a mob say something then force the actor to do some sort of dance, and all the scripts will have the same command to trigger them.  We could write 2 different scripts, one for each mob, or we could write one script to handle both of them



 Name:dance instructer  ,Vnum:[1200], Type: MOBILE
 Trigger flags: COMMAND ,NArg:0     , Arg List: Lesson
 Commands
 
 set first_room 1250
 set second_room 1251
 
 mecho %self.name% walks over to you.
 wait 1
 mecho %self.name% says,'So %actor.name%, you want to learn how to dance?
 wait 1
 ponder
 wait 1
 say ok just follow my lead..
 wait 1
 if (%actor.room% == %first_room%)
    mechoaround %actor% %actor.name% does the charlston.
    msend %actor% You do the charlston.
  elseif (%actor.room% == %second_room%)
    mechoaround %actor% %actor.name% does the fox trot.
    msend %actor% You do the fox trot.
 end

Remember, take nothing for granted, and add as much error checking as possible.  Scripts, like any program CAN AND WILL be hacked. Make sure you include enough error checking to make sure that people don't abuse your script. Also, you want to make sure that the person types in the exact command.

Lets say that you want to make a script on an object that teleports a clan member to their clan hall if they press a button. Assuming the name of the clan is Fishermen and their clan hall is in room 16300


 Name:teleporting watch  ,Vnum:[1201], Type:OBJECT
 Trigger flags: Command  ,NArg:3     , Arg List: press
 Commands
 set clan_hall 16300
 oteleport %actor% %clan_hall%

The above script will teleport the wearer into the clan hall regardless if the person is a clan member or not. Also it would activate any time the person typed press as a command.

Now lets try this again...


 Name:teleporting watch  ,Vnum:[1201], Type:OBJECT
 Trigger flags: Command  ,NArg:3     , Arg List: press
 Commands
 if ("%arg%" != "button")
   return 0
   halt
 end
 set clan_hall 16300
 
 if ("%actor.clan%" != "fishermen")
    osend %actor% You are not a clan member!
  else
    oteleport %actor% %clan_hall%
    oforce %actor% look
 end


The above script first checks to see if the person typed press button or something else. if the person did not type press button, then the script returns a 0 then halts the script (effectively ignoring the command).  Then the script checks to see if the user is actually a member of clan Fishermen.  If the player does not belong to that clan, then they wont be allowed in.

== Final Tips ==

* Don't over script an area. It really is possible to have TOO much of a good thing.
* Remember to check and recheck the script with a mortal.  Some commands (like force) do not work on immortals, so remember to always test your script with a mort.
* Try to comment your script as much as possible and format it.  It does make it easier for you or someone else when they have to go through your script later.
* Comments should not be too long, but just enough to give an idea of what you were doing.



[[Category:Scripts]]