Builder's Tutorial
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 ]