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 schelp online.

This document is not complete by any means. More sections will be added later, typos will be fixed, and revisions will be made.

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 ust 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 schelp.
 [ Part 5: "Attached Text" ]

AddictMUD Script Tutor 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 unset 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 refered 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 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*

• these variable descriptions may not beaccurate at the time

this was written. For details refer to schelp.

• • Some variable fields are not covered here. please refer to

schelp 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. I.e. %random.10% will
 return a number between 1 and 10.

 Arg
   This variable contains whatever is typed after a command trigger.
 ex. if a command trigger is drink and a player types drink water
 Arg is set to water

 [ Part 6: "Attached Text" ]

AddictMUD Script Tutor Part 4 "Commands"

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

You can make comments in your code by starting the line with an astrik 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 mathmatical operations and stores them in

a variable. While it's not always nessessary it's a good idea to enclose the expresson you want evaluated in parentheses

usage: EXAL <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. When you use this

command, it must be right after you set a variable (with set or eval).

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 certian length of time.

The number placed after the wait statement tells the script how long to delay in pulses (a pulse is currently 2 seconds long).

usage: WAIT <number> ex. WAIT 5 this will make the script pause for 10 seconds

HALT

This command ends the script execution permaturely.

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 statment 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 statment is found to be false. You must enclose the statement to be checked in parentheses. when referancing 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 equl 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 7: "Attached Text" ]

AddictMUD Script Tutor Part 5 "TIPS AND EXAMPLES"

When possible try to make scripts reusable.
 Instead of making many scripts that do something similar it's
usally 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 differant dance instructors

in 2 differant 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 differant 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 to 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. ssuming 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 ubove script will teleport the wearer into the clan hall reguardless of 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.

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.

I know that I personally am really bad at both of these things but 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.