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)

Name	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.