Index
1. What are Specials?
2. How Do They Work?
3. Passing In Attributes.
4. How Code Is Run.
5. How To Use Commands.
6. A Basic Example.
7. How Do I Write Specials Code?
1. What are Specials?
Specials are objects that you can attach to most any other object
that will execute when certain conditions are met. For instance, if you
attach a special to a stick that activates when the player picks up the
object, you can make the stick burst into flames. You can also set a
special to a location that will check the player's inventory when they
enter and if they contain a light, have a creature attack them in fear.
Specials provide the flexibility to perform actions that aren't already
coded into the mud.
2. How Do They Work?
When a certain condition occurs, such as the player picks up an object,
the object is first searched for a special with the "pre_get" trigger. If
one is found, it executes the code in the special. If the special code
returns with the return_invalid_criteria command, the get function quits
and doesn't let the player "get" the object. If on the other hand the
special returns normally, the get function continues and picks up the
object. Then it searches for the "post_get" special and if found,
runs through the code there.
The mud does this for every verb. When you start to go east, it
searches for the "pre_east" trigger and when you enter a location, it
searches for the "onentry" trigger. The "eachsecond" trigger occurs
as the trigger suggests, each second of the game. You can use this to
slowly burn out a torch, decrementing a counter each second until it reaches
zero and then destroy the torch. A list of triggers can be found on
the triggers page.
3. Passing In Attributes.
In a special, three objects can be passed into the code. They are
designated "primary", "secondary", and "this". The actual objects that
are passed in will vary from trigger to trigger. However, "this" will
commonly refer to the object that the trigger is attached to. The
"primary" attribute will usually refer to the object that is receiving
the action from "this". Finally, "secondary" is used for any left-over
objects that need to be passed in. For example, in the "pre_light"
special (activated when a player trys to lights an object with the "pre_light"
special attached), "this" refers to the object that is being lit, "primary"
refers to the object that is doing the lighting, and "secondary" is not
used. What the attributes that are passed in actually refer to are
listed in the list of triggers.
4. How Code Is Run.
When code is first run, it starts at the very top of your code and
executes each command like a train. It continues from command to command,
performing the action dictated in each command. The only time it breaks
from the "trainlike" fashion of execution is when you hit a "goto" command
or a command that terminates the special. On a "goto" command, it will
go to a predefined location in your code. This is defined by a marker which
could look something like:
middle:
or could look like
end:
You can call it whatever you want, all that matters is that you have a : after
it. This way you can tell the mud "if they are carrying the dragonslayer, go
to my spot in the code marked endofcode". Also, certain commands will cause
the code to drop out. For instance, the return_invalid_criteria() command
will cause the code to exit and tell the command (whether that be "get", "put",
"kill") not to continue executing.
5. How To Use Commands.
Commands are what perform the various actions of the special. They all
have unique names, such as get_title, award_quest, etc. Every command will
have a few things in common, such as a name followed by a () which may have
something inside it depending on the command. For instance, say you want to
send the actor (the player that caused the special to run) a message saying
that they just got a shock from the sword. You would use the command:
send_actor("You receive a shock from the sword!\n");
The "send_actor" is the command name and inside the () you find the
parameters of the function. A "parameter" can be compared to a bucket that
you send data into the function with. Some commands will have three
parameters, some more and some less. With parameters, you can send in
numbers, strings, even other commands. Another example is:
send_room_except(get_playername(), " finds something in the desk.\n");
The first "parameter" is the function "get_playername" which as you can
see has no parameters. Actually, the function returns the name of the player
who caused the special to run. So say the player "Biff" examines the desk
which has a special attached to it with the "pre_examine" trigger on it. The
special runs and it gets to the function above. Before the function send_room_except
can run, it needs to find the data in all its parameters. Since get_playername
is a function, it needs to run it first to get the data from it. get_playername
runs and returns "Biff". Now send_room_except executes. Since that function
combines strings and sends them to everyone in the room except the actor, it combines
"Biff" and " finds something in the desk.\n" and all those in the rooms see
"Biff finds something in the desk.\n". The \n causes it to go onto the new line.
It is the same thing as hitting enter.
6. A Basic Example.
The following code is attached to a desk with the "post_examine"
trigger. When the player examines the desk, it executes the code and
if this is the first time anybody has examined the desk, the player
will find a button in the desk.
goto_if_neq("end", 0, get_state());
send_actor("You find a button hidden in a recess of the desk.\n");
send_room_except(get_playername(), " finds something in the desk.\n");
set_state(1);
move_object(button@eforest, "inloc");
end:
The first line runs the goto_if_neq which compares the current state
of the object, acquired with the get_state function in parameter 3 with the
0 in parameter 2 (markers have an attribute called state which starts out as 0)
and if they are not equal, it goes to the "end:" marker. Since the first
time this code runs, the state will equal 0, it does not go to "end:". Instead,
it continues onto the send_actor function which tells the actor they
found a button in the desk. It then goes to the "send_room_except" function
which tells all in the room except the actor that the actor found something
in the desk. Next, it sets the state to 1 so that the next examine will find
nothing. Finally, it moves the button@eforest object into the location. Notice
the second parameter of the move_object function, "inloc". This tells it to
place the button in the location. You could use several other locations, such as
in another object or in the actor's inventory.
Each function provides a different ability to the coder and therefore needs
different parameters passed into it. A list of all functions along with what
parameters they expect can be found in the Special
Functions List.
Another even simpler example is of some code that prevents the player from
moving south while a mobile is there. The special is attached to the mobile
with the trigger "pre_south". When the player tries to go south, the following
code is executed.
send_actor("Asmadeus refuses to let you enter his museum.\n");
return_invalid_criteria();
The first line sends the message to the player stating that Asmadeus is
blocking their movement south. The second line informs the mud to leave the
special code and not continue processing the command to move south.
7. How Do I Write Specials Code?
To create specials code is not that difficult. You merely have to know
what you want the code to do and then find the functions that will do it for
you. This can, however, take some experience before it becomes second-nature.
Try looking over the examples in the Special
Functions List to get a feel for how the code works in different
circumstances. Then try creating a simple special, moving onto tougher ones
later on. If you need help with anything, you can always ask a power and
if they can't help you, feel free to contact Slate at noelg@acm.org.
[ Concept
| Status
| Latest News
| Tutorial
| Building ]