Object Tutorial

So, you'd like to start to build your own little Muck Empire, would you? Well, you've come to the right place. This tutorial will step you through the simplest aspects of building, leave you with a room you can customise to be the seed for your own collection of rooms, and ready you for the more complex possibilities that building permits.

Object-oriented

The basic unit of the Muck is the object. Everything that you can interact with on the Muck is an object. There are five flavours of objects, which changes the way they behave in relation to each other. The five categories are: player, thing, room, exit and program. Each of these has a different command for creating, though as a Builder you will only be able to create three of them yourself.

Player: A player is, as its name suggests, a character on the Muck, an entity that you can control. As a player you have the ability to move from room to room, pick things up and say things to other players.
Thing: A thing is a tangible object. Things are the simplest objects to understand, since they are individual inanimate objects that have a definite location. Players can create things and describe them; you can also destroy a thing, or any other object, if you own it.
Room: A room is just as its name implies. It is an object which can contain other objects, including players, things and exits. When you are in the same room as another player or thing, you can interact with it, by talking to it or picking it up.
Exit: An exit is perhaps the most difficult concept to grasp. Exits are not simply the ways to leave a room. Any action with interacts with objects is an exit. Passages leading from room to room, actions which perform tasks such as moving an object to a different room, simple actions which merely print text onto people's screens - these are all technically exits. Often, when the job of the exit is not one of moving a player to another room, the term "action" is more appropriate. Here the two terms will be used interchangeably, with the most natural one for a given context being preferred.
Program: A program is a sequence of instructions written in a language called MUF (Multi-User Forth) which the Muck interprets. Builders are not able to create MUF programs. You will need to ask a Wizard for a MUCKER bit to be able to program. Because programs are so different from other objects, they are not discussed in this section.

Having just these objects might seem overly restrictive, but with creative use of things, rooms and exits you can make quite complex conglomerates that behave in many interesting ways.

Object structure

For basic objects - that is, all objects but programs - there are eight categories of information that can be connected to them. They are the name, database reference, location, link, lock, flags, properties and contents. Some of the objects may not have or use all of these categories, and different types of objects may use them differently. This section may not make much sense at first; just go on ahead and come back later and you will understand more.

Name: All objects have a name. The name is simply a label used to identify the object. You are a player, which is an object, and your name is the name of your character. You can pick things up by referring to their name, or part of their name if the part you give is unambiguous. Two names always work, regardless of who or where you are: "me" refers to your own player, and "here" refers to the room you are in. All names are case-insensitive, so you do not need to worry about capitalisation.
dbref: Names are not unique, however. There are probably many SuperSoakers on the Muck, so both the Muck and players need to be able to distinguish between them. Names are also not a very efficient way of referring to objects from the Muck's point of view. To circumvent these problems, the Muck attaches a number to every single object on the Muck, treats the objects internally using these numbers, and allows players to specify objects with the numbers in case two are named identically. This number is called the database reference number, or "dbref" for short. The format for a dbref is a # followed by a decimal number. Any time you name an object, you can use its dbref equally.
Location: The location of an object is simply the next-largest object that holds it. If you are holding an object, that object's location is your player object. If the object is in the room with you, then both you and the object are located in the room. An exit from the room is also located in the room. Rooms can be located within parent rooms, which makes all of the parent room's contents accesible. If an object is in the same room as you, in a parent room, or being carried by you can you refer to it by name. Otherwise you will have to refer to it by its dbref.
Link: Some objects also have what is called a link. This is an object that the Muck should associate with the current object, depending on what type the current object is. This definition is deliberately vague because links encompass a wide range of behaviours. For players and things, the link designates an object - usually a room - that is the object's home. When an object is sent home, the link object becomes its location. You can make yourself the home of objects you carry so that if they are sent home (such as with the zap command) they revert to being carried by you. Linking a room to another object says that things dropped in the room should go to that object (usually a room or player). Linking an exit to another object will cause a myriad of different actions, depending on what sort of object you are linking to. Only two such cases will be discussed here; other aspects of linking will be covered later. Linking an exit to a room will make the exit take anyone who uses it to that room; this is how connections between rooms are made. Linking an exit to a program simply will run the program whenever someone uses the exit. You can only link an object to one other object at a time, with the exception of exits, which are described later.
Lock: Every object has a boolean (true/false) function called a lock. A lock is checked when you try to pick up a thing or program, or when you try to use an exit. If the lock evaluates to true, you can use the object, otherwise you are unable to use it.
Flags: All objects also have a small number of flags that can be set on them. A flag is simply a boolean indicator of an object's status, or a bit which changes the way an object behaves slightly. None of the flags need to be discussed yet; it is only necessary to know that they are there.
Properties: Objects may also have several properties. A property is just a piece of text attached to a label. For instance, all players have the property sex, which can be either "male" or "female". This allows certain actions which need to differentiate between male and female characters to function. In fact, there is no restriction on the text of a property, so that you could quite easily set your gender to "thrice daily", but many programs expect this property to be properly set, so there is little point to such silliness. There is also little limit on the name of a property, nor on how many properties an object can have.
Seven properties, namely SUCCESS, OSUCCESS, FAIL, OFAIL, DROP, ODROP and DESC, are so special that they will be dealt with in detail shortly. (They are technically not properties, but behaviourally they are identical so it helps to think of them this way.)
Contents: Most objects - namely, things, rooms and players, can have contents. This is the converse of location. If objects A and B are located in room C, then room C has objects A and B as its contents. Contents can be things, players, rooms or exits (for rooms), exits (for things), and things and exits for players. The point of making a room's location another room will be discussed later. When an exit is part of a thing or player, it often becomes more natural to think of it as an action, though it should be remembered that the difference is one of name only.

There is a way to look at all of the eight types of information on an object that you own. Simply use the examine command. An example is:

examine me

This will print out all data associated with your player. You can examine any object by substituting its name or dbref. For objects you do not own, this will tell you who does own it. Creating things Creating objects depends very much on what sort of object you plan to create. Normal players can only create three types: things, rooms and exits. The simplest object to create is a thing. Creating a Thing object requires one command:

@create Sample Thing

(Note that the "@" sign in this and all such commands is necessary. It is part of the command.) This will create an object and call it "Sample Thing". All things that are created default to being held by you. If you glance at your inventory:

inv

you will see that you are carrying your Sample Thing. Beside the object is listed its dbref in parentheses. All objects you own, and some objects you don't own (specifically, those with any of the flags ABODE, CHOWN_OK or LINK_OK set, but don't concern yourself with what that means just yet), are listed with their dbrefs. You will also notice that creating this thing has cost you ten pennies. Creating is not cheap and should be done carefully.

You should examine your new object to see how it is represented by the Muck. Just

examine Sample Thing

Initially, there will be very little information present, until you set a few properties and describe it. These are explained in the following section.

Describing objects

Your Sample Thing is now an object on the Muck. You can drop it and pick it up, and other players can do the same. Go ahead and try:

drop Sample Thing get thing

Note how you abbreviated the name and the Muck still knew what object you meant. If the name were ambiguous, you would get an error message and none of the objects matching the name would be picked up. If all goes well, the Muck prints two lines:

Dropped. Taken.

If someone else were in the room, they would see:

Playerdrops Sample Thing.

Where Player is your character's name. If you would like to see these messages, ask someone else to join you and pick up the object while it is in the room.

This is all very well, but it's a bit dull. You would like to customise the messages that appear when the object is taken or dropped. You would also like the Muck to notify others when you pick up an object, because it doesn't by default. This is where the seven properties listed before come in handy. (Technically, these seven text strings are treated a little differently internally from regular properties, but it is helpful to think of them as such. Just remember that there are different instructions for setting these seven character strings than there are for regular properties.) Whenever you drop an object, the DROP string is printed to your screen instead of "Dropped.". In addition, your name followed by the ODROP string is printed to the screens of everybody else in the room. (The O in these names stands for "others", who are the ones who see the message.) To set these, use the @drop and @odrop commands:

@drop Sample Thing=You put the Sample Thing on the ground. @odrop thing=places a Sample Thing on the floor.

Note that the text before the "=" is the name (or dbref) of the object you are assigning this string to, which, as always, you can abbreviate if you are lazy. Note also that you don't include anybody's name in the ODROP message, because the Muck puts it there for you based on who is dropping it. Now if you drop the Sample Thing, you see

You put the Sample Thing on the ground.

and others in the room see

Playerplaces a Sample Thing on the floor.

Just as with dropping an object, you can change the messages for picking up an object. The two strings to set are SUCCESS and OSUCCESS, usually abbreviated SUCC and OSUCC. (The reason for this name will become clear when locking is discussed.) To set the picking-up strings, use the commands @succ and @osucc:

@succ sample=You pick up a Sample Thing to look at more closely. @osucc Sample thing=gently takes a Sample Thing and wonders curiously about just what it could be.

Long lines are shown wrapped here but should be typed in on one long line. Your Muck client will format the output when it needs to. When you pick up the object now, you see

You pick up a Sample Thing to look at more closely. Taken.

(The "Taken." will always appear) and others will see

Playergently takes a Sample Thing and wonders curiously about just what it could be.

Depending on what client (program) you are using to connect to the Muck, the line may have automatically been wrapped for you. If not (for instance, if you are using telnet alone) you will have to get used to long messages being split in the middle of words.

Probably the most important of the seven strings is DESC. This is the text printed when someone looks at an object. If you look at your Sample Thing:

look thing

then

You see nothing special.

But you would like to say that there is something special about the Sample Thing. This is done with the @describe (or just @desc) command:

@desc sample thing=Upon looking at the Sample Thing you see that it is quite an intricate device. It consists of a subspace jargon emitter attached to a small phased matter rerouter, and you can count at least five Treknobabble modulation units around its perimeter.

(Again, type that as one long line.) Now, when anyone looks at it, they will see:

Upon looking at the Sample Thing you see that it is quite an intricate device. It consists of a subspace jargon emitter attached to a small phased matter rerouter, and you can count at least five Treknobabble modulation units around its perimeter.

For objects which are immovable (because of a lock) and have no attached actions, only the DESC field needs to be set. If anyone can pick it up or put it down, the SUCC, OSUCC, DROP and ODROP strings should also be set. The final two strings, FAIL and OFAIL, will be discussed alongside Locks.

If you now examine your Sample Thing as you did at the end of the last section, you'll see that the data has grown to list the five strings you set on it in this section.

If you ever want to delete any of these strings, just set it to the empty string:

@fail thing=

(The FAIL and OFAIL strings will be discussed in conjunction with Locking.)

A little advice for when you meet others on the Muck: don't forget to describe yourself! When other people look at you, they are looking at your DESC string. If you describe yourself with the following:

@desc me=You are looking at a sample character with very little personality.

others can

lookPlayer

(where Player is your player's name) and know that you are a simple character with very little personality. Take the time to look at other characters' DESC strings. Some of them are quite creative.

Creating rooms

The second type of object you can create is a room. Room objects can contain all other types of object, including other rooms. In fact, the whole Muck is one big room, with smaller rooms inside it. The implications of having rooms inside rooms will be discussed in Inheritance below.

Rooms are created using the @dig command. Make yourself a home room with the following command:

@dig Tiny Room

The Muck responds that a room has been created and presents you with its dbref. Write this number down! Until you make some exits leading to the room you can only refer to it by its dbref. Creating a room also costs you ten pennies.

While the room has been created, you are still in the same room you were in before. You can take yourself to your new room using a command called @teleport. @teleport (often abbreviated to @tel) will move an object you own to a room or to yourself. Let's say that your room had a dbref of #5160 (this is actually Ariel's room which is used in several examples). You could move yourself there using the command:

@tel me=#5160

Note the use of the name "me", which always refers to yourself. You could just as easily type in your name or your dbref if you prefer. The name on the right of the "=" sign is the destination, in this case your new room, but it could easily be "here" if you want to bring an object you own to your current location, or "me" if you want to instantly hold it.

(Another command which would do the same thing is

jump 5160

"jump" is a program that is available in all rooms on FDCMuck. If you give it a number it will take you to the room with the dbref the same as that number. But it is useful to introduce you to the @tel command because it is more general and will also be referred to later in Inheritance.) Now that you are in your new room, don't forget to take a look around.

look

There is very little to see at the moment because you have not described it. It is time to use those seven strings introduced in the previous section, or at least three of them. The basic description of the room should go in the DESC field, naturally. Be inventive in your descriptions. Here is an example:

@desc here=You are standing, or rather crouching, in a small closet-like room. Light creeps in from a window on the far wall, but it is lost in the gloom before it is half way to you. A few tufts of fluff are tangled beneath your feet. You can't help but think that the room could do with a decent coat of paint.

So that now when you look, you see that:

Tiny Room You are standing, or rather crouching, in a small closet-like room. Light creeps in from a window on the far wall, but it is lost in the gloom before it is half way to you. A few tufts of fluff are tangled beneath your feet. You can't help but think that the room could do with a decent coat of paint.

If you still have your Sample Thing with you, drop it in the room, and you will see that when you look in the room you can see objects that you leave there.

The other two strings that you will find useful are SUCC and OSUCC. The former is printed after the description every time you look. This isn't particularly useful in itself, since you could just put it all into the DESC, but in the following section you will see another use to which the SUCC field can be put.

The OSUCC message is printed to everyone else's screen when you look in the room (or when you arrive in the room, because every time you arrive in the room you do an implicit look). If you set the room's OSUCC message like this:

@osucc here=brushes aside some cobwebs.

and if another character called Visitor looks in you room, everyone else (including you) will see:

Visitor brushes aside some cobwebs.

Doing this can be fun but it can be somewhat annoying if there are twenty people in the room, all looking at once. Use this feature sparingly.

Creating actions and exits

Now that you know how to create and describe things and rooms, you would probably like to be able to make them do things. This is where the third type of object that regular players can make becomes useful.

Exits are, with the exception of programs, perhaps the most different of objects. They cannot have contents, unlike players and rooms, and they can be linked to more than one object. Some of the flags have different meanings for exits. Exits are also interpreted differently; they are more like verbs, other objects are more like nouns. Finally, you will note that many of the commands that operate on other objects (such as @tel) have different versions for exits (such as @attach).

Actions

For a walk-through example, pick up your Sample Thing you made earlier. You are going to make a simple action and attach it to this object. Naturally, the one thing a Sample Thing needs is a Silly Action. Create one and make it part of the Thing with the following command (this costs a penny):

@action Silly Action=Sample Thing

The syntax is much the same as for other commands: name on the left of the "=", existing object on the right. Examine your Sample Thing in the usual way and you will see that it now has an action attached. You now have to say what the action does. When an action is performed, its SUCC string is printed to you and its OSUCC message to everybody else. That is, the action "succeeds". Set a couple of appropriately silly messages:

@succ silly action=You toss the Thing into the air and it goes, "Sproing!" @osucc silly action=is alarmed at the Sample Thing's liveliness.

There is absolutely no reason to make the SUCC and OSUCC strings even remotely related. Creative use of this can make people think you have more than one action on the object. Now that you've set some messages on the action, try it out:

silly action

The Muck responds with:

You can't go that way.

Huh? You don't want to "go" anywhere! What happened?

Well, one little intricacy of the Muck is that actions (and exits, naturally) have to be linked to an object before they work. But what object should you link the action to?

Linking

There is a lot to say about linking of actions and exits; indeed the entire tutorial, Object/Action Trickery, covers just that. So for the moment take it as given that about the only way you can have your action do nothing but print the SUCC and OSUCC strings is to link it to a program, and have the program do nothing. Since as a player you can't write programs, one has already been written for this purpose and is called dummy-for-exits. Knowing this name isn't very helpful, however, since the program object isn't in the current room or being held by you, so you have to use its dbref. On the FDCMuck this program has dbref #56. This is also something you will have to take as given. There is no way for a player to find a dbref of an object belonging to another player given its name.

Linking is accomplished with the @link command, with a syntax that should be becoming familiar by now. To make this link, do:

@link silly action=#56

The Muck reports that it has linked the exit to dummy-for-exits, and has charged you another penny. Now when you try out your action as before, you get the desired response:

You toss the Thing into the air and it goes, "Sproing!"

Three things to note about what happened before you linked the action: first, it printed, "You can't go that way." This probably seems like an odd way to tell the player that the action has not been linked, but remember that actions and exits are the same objects, and the only difference is a conceptual one based on what sort of object one is linked to, be it a player or room (exit), or a program, thing or another action/exit (action). Since the action hadn't been linked at that point, the Muck was making the assumption that you were going to use it as an exit rather than an action. This assumption is mainly historical; in early versions of TinyMuck, exits could only be used as room exits. Which brings up the second point. In fact, the "You can't go that way." message is only a default. Specifically, it is the default FAIL string. FAIL and OFAIL are the only two of the seven text string "properties" that have not been discussed. They are the converse of SUCC and OSUCC. As you would expect, the strings are set with the @fail and @ofail commands. Whenever any task you perform as a player (get an object or use an action or exit) cannot succeed, the FAIL string is printed instead of the SUCC string, and the OFAIL string is printed to everyone else's screen instead of OSUCC. How to control success or failure selectively is discussed later in Locks. This brings us to the third point to consider. If you think about it, for an action which just prints words onto the screen, there is no need to link it at all. You could leave it unlinked and, instead of using the SUCC and OSUCC strings, set the FAIL and OFAIL strings. The results would be identical and you would have saved yourself a penny! However, while this may seem sound, there are reasons why not linking an exit may not be a good idea. This and many other aspects of actions and linking is covered in the second part of the tutorial, Object/Action Trickery. Exits Now that you have used an exit to perform an action, it is time to use an exit to function as an exit. If you are not in your Tiny Room that you created, go back there. Much of the discussion relating to the Silly Action that you created applies to making passages between rooms. First, you need to make the action: @action [W]est;W=here This needs a little explaining. You attached the action to the current room ("here"); this makes sense: you want the exit to work whevener a player is in the room. But why name the exit "[W]est;W"? A feature of actions is that you can give one several names, so that if a player types any of the names, the action is performed. You just name the action with all of the possible names separated by semicolons. In this case, a player typing either "W" or "[W]est" (square brackets included) will use this exit. Order is unimportant, but it is a good idea to put the most descriptive one first, as you will see shortly. You can't use the exit until you've linked it. If you try the exit now, you'll be told that "You can't go that way." So you have to pick an object to link it to. Which object? If you link an exit to a room object, then using the exit will teleport you to that room. In other words, it makes a one-way passage to the other room. The other room has to have a flag called "LINK_OK" set on it if its owner allows other people to link to it. (This goes for everything, not just rooms; that's what LINK_OK means.) However, most of the Muck's hub rooms are set LINK_OK, so pick one. A good one to try at first is the Information Superhighway. You will again have to use the link destination's dbref because it isn't in the current room, so take it as given that the Information Superhighway is #232. So, link your exit with the command: @link w=#232. Note that you can still give abbreviated names for exits, just as for other objects. This link costs a penny, just as other links do. Now, it is so common to create an action, attach it to (that is, make it part of the contents of) the current room, and link it to another room, that there is a shorthand command for doing it. The following command: @open [W]est;W=#232 is exactly equivalent to @action [W]est;W=here @link [W]est;W=#232 and both cost two pennies to complete. Try your new exit now. With a simple W you find yourself on the Information Superhighway. So how do you get back? For that, you'll need a second exit, located in the Information Superhighway and linked back to your Tiny Room. But, since you don't own the Information Superhighway, you can't create an exit in this room. To do that, you will have to ask the room's owner to make an exit and link it to your own room. This problem does not arise if you own both rooms, naturally. This is a security feature that not only stops you messing up the rooms of someone else, but it helps ensure that only inspected, certified rooms make it onto the main part of the Muck. Now, the seven string "properties" aren't wasted on room exits. They have particular meanings for exits to rooms just as they do for other objects. How do those seven text strings relate to exits to other rooms? As you might expect, you see the SUCC message when you use the exit, the FAIL message when you can't use it, and everyone else in the room you are leaving sees OSUCC or OFAIL. You can describe any exit with the DESC string, so that if someone says look W they might be given a bit of information about what's at the other end of the exit. The odd one is ODROP. When you set the ODROP string, the message is printed to the screens of everybody who is in the destination room (when you "drop" in, so to speak). The DROP string is mostly irrelevant in exits between rooms; it acts as a sort of second SUCC string, but normally you can simply use SUCC to print arrival text to your own screen. Set a few reasonable strings for the exit (teleport back to the Tiny Room before you do this): @desc W=There is a very loud traffic noise emanating from the door to the west. @succ W=You head west, blocking your ears against the noise. To your surprise, you see: @osucc W=wanders out the door to the west. @odrop W=arrives from the Tiny Room in a daze. Now, if you use the exit, you will see: You head west, blocking your ears against the noise. To your surprise, you see: followed by the room's description; everyone in the Tiny Room will see: Player wanders out the door to the west. and everyone in the Information Superhighway will see: Player arrives from the Tiny Room in a daze. Listing exits It is only common courtesy when you build a room to list the exits from it when they look in it. One way to do this would be to put them in the DESC string of the room. While this works fine, it has the disadvantage of you having to retype the whole description every time you add an exit. A simpler way relies on a program to automatically display all exits whenever you look. To illustrate this, if you are unsure of the exits from a room, there is a global command which you can type to list the exits. Go back to your Tiny Room again, and type: exits The Muck responds with: Exits: [W]est, ... exits is a program that prints all objects of type "EXIT" connected to the current room, even if they are not linked or connected to other rooms. Notice that the command only prints an exit's name up to the first semicolon. This is why the exit was named "[W]est;W" - the exit can be activated with "W" but it displays as "[W]est". You would like the Muck to print "Exits: [W]est, ..." every time you look in the room. But how do you make the look command run a program? One feature of some of the seven descriptive text strings (specifically this works for the DESC, SUCC and FAIL strings only) is that if they start with an "@" followed by a number, and that number is the same as the dbref of a program, then that program is run. If there is any text following the number, it is presented to the program as if it were typed after the program name. The dbref for exits is #506, and you can change the text it prints instead of "Exits:" by including it on the command line after the command name. So, you need to put into one of the seven strings, this: @506 Cramped doors lead: Recall that when you look in a room, you are given the DESC string followed by the SUCC string. Since the DESC string is already used, and you want the exits to be listed after the description, the SUCC string (which is presently unused) is a prime place to put the exits command call. Do it like this: @succ here=@506 Cramped doors lead: Note that the two "@" signs have very different purposes. The first one is part of the @succ command. The second one is the first character of the SUCC string, which will be interpreted specially when it is to be printed. Now, if you look in the Tiny Room, you get this: Tiny Room You are standing, or rather crouching, in a small closet-like room. Light creeps in from a window on the far wall, but it is lost in the gloom before it is half way to you. A few tufts of fluff are tangled beneath your feet. You can't help but think that the room could do with a decent coat of paint. Cramped doors lead: [W]est, ... And your room is complete. Fill it with objects that do neat things (study other rooms or this tutorial for more ideas), have it inspected and you can have it connected to the rest of the Muck's rooms. Substitutions Up to now, the wording in the seven descriptive strings has been such that it could work for anybody. But let's say you want an action a player performs to say to everyone else: Visitor squeezes the lemon, and juice squirts in her face. This is all very nice, but chances are a male player will perform the action eventually, and it will look plain silly. Two ways around this that you might consider are: careful use of locks, which are covered later, and using a gender-neutral pronoun. English doesn't have very good pronouns for this purpose, however. You could try the oft-misused plural "their", which rapidly seems to be becoming a de facto non-specific gender-neutral third-person singular pronoun ("Someone left their pen behind"), but it looks silly when you are referring to a particular person ("Gerald brushes their teeth"). Much the same argument goes for "its". Thankfully, the Muck has a third alternative which is sure to produce the right text. But first, a little lesson in English grammar. Pronouns English has three third-person singular pronoun forms: masculine, feminine and neuter. While the pronouns are different, they have no effect on the words around them. This is fairly common in European languages; once the pronoun is fixed as being third-person singular, it doesn't matter to the other words if it is masculine, feminine or neuter. This means that any change to the text is very local and within the abilities of a simple computer program. You might think that you only have to worry about generating "he", "she" or "it". However, in English, like all other European languages, personal pronouns change depending on their function in the sentence. There are five roles pronouns can have in speech. Since in the third person singular, words are often repeated, the unambiguous first person singular is given for each as reference. Subject Often called the nominative case by linguists, the subject is the noun that performs the verb. The three subject pronouns are "he", "she" and "it". For reference, the first-person singular is "I". Regular nouns are unchanged. He pressed the red button. She wore a blue dress. It rained for forty days and forty nights. The dog ate a bone. Object Often called the accusative case by linguists, the object is the noun that is the object of the verb. The three object pronouns are "him", "her" and "it". For reference, the first-person singular is "me". Note that if there is a preposition preceding the object, many languages suddenly use the dative case, but English does not really have a dative case. Regular nouns are unchanged. A klaxon sounded back at him. The dress suited her well. There seemed to be no end to it. Bones made the dog happy. Reflexive When the subject and object are the same, often the object is changed to the reflexive form to emphasise the fact. In the third person singular, the reflexive is just the accusative with a "self" appended. The three reflexive pronouns are "himself", "herself" and "itself". For reference, the first-person singular is "myself". The reflexive is often overused in spoken English; only if the subject and object of the same verb are the same should it be used. Otherwise, use the object form. Regular nouns are unchanged, but using the noun twice usually looks odd. He had never pressed the button himself before. She always imagined herself in blue. Noah hoped the storm would blow itself out in a few days. The dog dug the dog a hole for the bone. Possessive Often called the genitive case by linguists, the possessive is used to indicate that the subject or object is owned by something else. The three possessive pronouns are "his" "her" and "its". Note that the feminine is the same as if it were an object. Which it is must be determined from context. For reference, the first-person singular is "my". Regular nouns have "'s" appended. Note that only nouns have the apostrophe, not "his" or "its". "It's" means "it is" or "it has" and is not a possessive. If you really want to contract an "is" or "has" you should be using the subject form followed by "'s". The noise made his head ache. It was much nicer than any of her other dresses. Despite its ferocity, the storm failed to harm the ark. The dog's bone remained buried for years. Absolute The absolute is related to the possessive. It is used when the object has already been mentioned, and all that remains is to explain whose it is. The three absolute forms are "his", "hers" and "its". Note that the masculine and netuer forms are the same as if they were possessives. It is easy to determine which they are from context. For reference, the first-person singular is "mine". Regular nouns again have "'s" appended. The same warnings apply here as they do to possessives about the use of apostrophes. He knew the responsibility was all his. Hers was the prettiest dress at the ball. The ark was strong; the best survival chance was its. "It is all the dog's," the disgusted owners said when the dog finally exhumed the bone. Substituting pronouns Now that you know how to differentiate between each of the five pronoun usages, it's time to show how to put them in a string. Only the three strings OSUCC, OFAIL and ODROP perform this substitution. The reasoning is that since the other four strings are usually directed towards the person who typed the command, they should be in the second person which has only one pronoun ("you") anyway. Any time that a "%" sign appears in one of these strings, the following character is examined. If it is a letter that indicates a pronoun, the typist's sex property is examined. Depending on what it contains, the two characters ("%" and following letter) are replaced with the proper pronoun. This table shows all possibilities: Code Meaning sex:male sex:female sex:neuter sex:<other> ------------------------------------------------------------------ %s subject he she it <name> %o object him her it <name> %r reflexive himself herself itself <name> %p possessive his her its <name>'s %a absolute his hers its <name>'s %n name <name> <name> <name> <name> %% % sign % % % % A few things to note about this table: "%%" is clearly needed in case you really do need to have a "%" sign in your string. "%n" always prints the player's name. This is in case you want to refer to the player by name again. If the sex property is not set to a meaningful value, the Muck does the best it can and just prints the player's name. This can look odd if a lot of pronouns are present. Finally, it may be that a pronoun starts a sentence. In this case, you want the pronoun to begin with a capital letter. To do this, use "%S", "%O", "%R" and so on. If you are still carrying your Sample Thing, try changing the OSUCC string to this: @osucc Sample Thing=gently takes a Sample Thing in %p hands. %S wonders to %r just what it could be. This is pronoun overkill but it gives you the idea. There is a possessive, a subject (beginning a sentence) and a reflexive pronoun. If a male player picks up the Sample Thing, you will see: Man gently takes a Sample Thing in his hands. He wonders to himself just what it could be. and if a female player takes it, you will see: Woman gently takes a Sample Thing in her hands. She wonders to herself just what it could be. While the FDCMuck doesn't have many neuter or other players, the possibility is there for those who want it. Object housekeeping After you have started creating objects, you will rapidly come to need tools for manipulating them all. These tools are described in this section. Renaming The simplest task you will probably want to do is to rename an object. To do this, you need to be able to refer to the object by its present name - that is, it has to be held by you, in the current room, or an exit attached to one of these two places. If you can't move to its location, you can bring it to you with the @teleport command, explained next. You then rename your object with the following command: @name old name=new name You can use the object's dbref as the old name, but the restriction on the object's location in relation to you still applies. The @name command also renames exits. If you want to add an alias to the exit, just separate the various activating phrases with semicolons, as in Exits above. You can't use @name to rename a player unless you are a wizard. Moving Moving objects from one place to another is done with the @teleport command. You simply tell it what object to move and where to move it to. @tel me=#100 @tel sample thing=me (#100 is the FDC Player Start room on the FDCMuck.) There is no restriction about using dbrefs instead of names as there is for @name. @teleport will complain if you try to move an object to a place it can't go, such as a thing to a thing or a room to a person. You can teleport an object with @teleport if: You own the object you are moving, and the destination is either owned by you or has its JUMP_OK flag set; You own the room containing the thing you are moving, or you are holding it, and you are sending it home (like in zap); You are teleporting a player and both the source and destination rooms are either JUMP_OK or owned by the person being moved; or You are teleporting a non-player, and the source room is either JUMP_OK or not owned by the object's owner, and the same for the destination room. In short this rule forbids teleporting an object a player owns out of its own room if the room is !JUMP_OK. Flags are discussed in Flags below. If you try @teleport on an action, you will discover that it doesn't work. There is a different command for actions: @attach. Otherwise it is the same. @attach silly action=me @attach w=sample thing. @attach can't refer to objects by dbref if it can't see them in the current room or on you. If you want to move an action to a different room, attach it to yourself, go to the other room and attach it there. Note that @attach and @link are very different commands. @attach controls where the action is; @link controls where the action goes. Inheritance Recall that rooms can contain all other types of object, including other rooms. What use is this? Imagine that you type the command jump. The Muck first looks through the actions and programs you are holding to see if there is a command called jump there. If it finds one, the action is performed. If not, it then looks at the actions attached to the things you are holding. If it still hasn't found it, the Muck searches the room and its contents. Whenever the Muck finds an action or program by that name, the search stops and the action or program is performed. But most rooms don't have a jump object, and yet you can quite clearly use jump anywhere. It so happens that the room you are in, like all other rooms, is inside a bigger room, and all the global commands are stored in the bigger room. If the Muck can't find a command in the current room, it looks in the parent room, and then to that room's parent, until the search can proceed no more because it has reached the ultimate parent room, dbref #0. Only then will the Muck tell you that it couldn't find the command. This searching behaviour means that you can easily override a global command with a local one. In fact, you have already done that with your exit "[W]est;W" - the "W" part has overridden an abbreviation for the whisper global command. The primary use of inheritance by rooms is to make a room full of useful commands and then put all your own rooms inside that room, so that the commands are all accessible from any of these rooms. Recycling You will find after a very short while that you are beginning to have too many objects and want to delete some that you no longer need. To do this, use the @recycle command (usually shortened to @rec): @rec Silly Action For all object types except things, you will be reimbursed for all creation, locking and linking charges. For things, you only get back one penny even though it cost ten to make. Recycling can use object dbrefs, like most other commands, and is very permanent. There is no "retrieve" command to bring back a recycled object. It is very responsible to recycle objects you don't need. The more objects in a Muck's database, the slower it becomes. By recycling objects you are helping to keep the database small. Making a home Initially, your player's home (#100) is a fairly dull impersonal room. Whenever you type home or gohome or zap me you are sent back there. One of the first things most players do when they begin building is to make a home room for themselves to stay in while they are disconnected from the Muck. Let's say that you want to make your Tiny Room your home. All you need to do is take yourself to the room and type: @link me=here Note that while this is the same @link command that works on exits, and while it uses the same data structure spot as exits do, it performs quite a different job. Now, whenever you type home, you are taken to this room. But beware! All the things you are carrying have a home too, and if you go home, they all go home too! If you want them to stay with you, you have to set their home to be you: @link sample thing=me Now you can safely go home and your Sample Thing will stay with you. In fact, if anyone else is holding it and goes home, it will magically appear in your inventory. The gohome and zap commands don't suffer from this problem, so most players prefer them. Another way of going home is mentioned in Object/Action Trickery. Unlinking At some time you might discover that you have linked an exit incorrectly, or that you want to link it to something else, or remove the link completely. This is where the @unlink command is used. @unlink W You are returned a penny - the usual cost of linking - when you unlink an action. Unlinking is performed automatically if you recycle the action it belongs to. You cannot link an action to an object if it is already linked. Trying to do so will neither replace the current link nor add to it. You have to remove the current link first. This is especially important to know if you are trying to make multiple links (see the section on multiple links in Object/Action Trickery). Finding Everybody loses objects. Sometimes they are hard to find. But there are commands that keep track of all your objects and can tell you where they are. You can get a list of every single object you own with the @owned command: @owned me If you are just starting to build the list will be short - but already there should be about four items on the list (you, your Sample Thing, the Tiny Room, and the exit you made - plus another if you didn't recycle the Silly Action). Beside each object is its dbref. To find one, note its dbref (say it was #7900), and ask the Muck where it is. where #7900 The Muck tells you which room object #7900 is in. If it lists the room's dbref, you can simply teleport yourself there and pick it up. Otherwise, you can try to teleport it to you if it is not an exit. Exits that are not connected to rooms you own (and can thus see the dbref for) are rare. In such a case you can try to examine the object remotely by referring to its dbref and see where it is located. The biggest problem with @owned is that it prints all objects you own. Many players have in excess of 200 objects to their name. A more useful command for most objects is @find. This command allows you to search on a substring. @find thing The Muck will report any object you have with "thing" in its name. From there you can try to locate it as before. The major drawback of @find is that it ignores exits. To locate an exit you will have to used the @owned command and sift through the spam. Owning There exists a very simple mechanism for transferring ownership of objects. The command @chown allows you to make any object yours, if the current owner lets you. First, the current owner must have set the object's CHOWN_OK flag, to signal that anyone can change the ownership of the object to themselves. Flags are covered more fully in a later section. As soon as the object has its CHOWN_OK flag set, everyone can see its dbref. This is to aid you in referring to the object. To make the object yours, use the following: @chown object=me Normal players can only transfer the ownership to themselves, not others. Of course, now that the object is yours, you can examine it, change it, and remove the CHOWN_OK flag so that no one else can use @chown on it. If you are constructing a gift on the Muck to give to someone else, it is considered proper etiquette to make all objects in it CHOWN_OK, so that the recipient can use @chown to make it their own. This allows them to set the home of the object (or to recycle it if they don't like it!). Properties All objects have a set of variables local to them that can be used for any purpose you desire. These variables, or properties, can have almost any name and any value. There is also no limit to how many properties an object can have. Properties are widely used by programs to control behaviour and by locked actions to control destination links. You have already been introduced to one property, sex. if you examine yourself, you'll see your sex listed. If, for some reason, you want to change this value - say, you are testing how the other half will cope with a particular lock you created (see Locks below) - all you have to do is set your sex property and it will overwrite the previous value. (It is not recommended to change your sex in public - while it might be fun it is disorienting to others.) Let's create a useless property on your Sample Thing as an example. The syntax for setting a property is a bit arcane, so pay attention: @set sample thing=power:on This sets the property called power to the value "on" for the object "Sample Thing". You could substitute any strings for "power" and "on" with the one exception that the property name can't contain a colon, for obvious reasons. If you now examine your Thing, you'll see the property has been set. To clear the property, give it an empty value: @set sample thing=power: The colon is needed or the Muck will think you are setting a flag. For a more realistic use of properties, see the example in the next section. Locks Up until now, any object you make could be picked up, and any person can use any exit on your objects. Indeed, the only time a FAIL string was printed was when you tried to use an exit you hadn't linked. There is a way to selectively forbid certain actions based on various criteria, using a system of locks. All types of object have a lock, but it is usually only useful to lock things and exits. When you lock a thing, only the players who can pass the lock's criteria are allowed to pick it up. When you lock an exit, only those who pass can use it. If the player passes the lock, the SUCC string is shown to the player; otherwise the FAIL string is shown and nothing else happens. Here is a very simple lock: me That is, unless a player is you, that player can't use the object. Here is how to set this lock on your Sample Thing: @lock thing=me The name of the object goes on the left side of the "=", as always, and the value of the lock goes on the right. Now, if anyone tries to pick up your Sample Thing, the Muck will tell them You can't pick that up. Or the FAIL string on the thing, if you have set it. If you have set the OFAIL string, everyone else will know that the player couldn't pick it up either. As a general rule, if you have set a lock, you should set the FAIL and OFAIL strings. To remove a lock from any object, use the @unlock command: @unlock thing Now anyone can again pick up your Sample Thing. Locks can become far more complicated than just a single player. In fact, the type of object included in the lock changes the behaviour of the lock, as this table shows: Lock Locks if and only if player player attempting is said player. thing player attempting is holding said thing. room player attempting is in said room. program program leaves nonzero value on top of stack. prop:val player, or anything player holds, has property prop set and equal to val. *name player attempting has said name (costs a penny to create lock). (l) lock l succeeds (used for grouping). !l lock l fails (logical not). l1&l2 both locks l1 and l2 succeed (logical and). l1|l2 either or both of locks l1 and l2 succeed (logical or). As you can see, you can group locks together with the boolean functions "and" ("&") and "or" ("|"). "&" has higher precendence than "|", but you can group them using parentheses if you need. For a more complex example of locking, try making the following lock on your "W" exit from the Tiny Room: "Only allow female characters carrying the Sample Thing to pass, but allow me to pass always." In lock terminology, this would become: @lock w=(sex:female&thing)|me The parentheses are not needed in this case but are left there for clarity. Now, if anyone but you tries the exit, they will be unable to pass unless they are both female and holding the Sample Thing. However, it is fairly easy to circumvent one of the conditions: that of being female. If you create an object that has the property sex set to "female", then even if you are male, you are carrying something that passes the lock "sex:female". This has repercussions that are covered in the "Multiple Actions" section in Object/Action Trickery. Locks this complex are rarely useful, and forbidding half the population to use an exit is certain to be considered an unfriendly act by that half, but it shows how to make rather complex rules for what can and can't be done. For a Real Muck Example, take a look in Ariel's Room (#5160). All objects in that room have a property _ariel_own set to "yes". The only exit from the room has the lock "!_ariel_own:yes". This stops visitors to the room from inadvertently taking Ariel's possessions with them. (The reason this property starts with an underscore is one of security. MUF programs cannot change properties beginning with "_" on objects not belonging to them. But for somethine as simple as this, it really isn't particularly necessary.) One extremely useful lock is this one: me&!me This Zen-like lock succeeds if the player attempting it is both you and not you. In other words, it always fails. This is the Muck's most concise way of indicating boolean falsehood. If you lock a thing with this, no one, not even you, can pick it up. Locking has very little to do with linking, by the way. Just because you have locked an object doesn't mean you don't still have to link it. Flags The only member of the long structure that forms an object that hasn't yet been discussed is flags. Every object has flags, but some objects interpret them differently. A flag is simply a marker that can be set or not. It has no value; the only important thing is if it is there. You can set most of these flags on objects you own. To set a flag, use the @set command (as you used when setting properties): @set here=ABODE and to remove a flag: @set here=!ABODE Since all flags have differing initial letters, you can abbreviate "ABODE" to just "a" in this case. Note that the only difference between setting a flag and setting a property is the absence of a colon here. Flags include: ABODE When set on a room, allows any player to link themselves or a thing they own to that room, making it the object's home. This is unlike the LINK_OK flag, which allows exits to be linked to the room. ABODE also allows people to use @teleport to set that room as a parent. For all other objects, ABODE has no effect except to make the dbref visible to everybody. BUILDER Only meaningful for players, where it allows the use of building commands (those beginning with "@"). All non-guest players on the FDCMuck have this flag set. Only wizards can set or clear this flag. CHOWN_OK When set on any object, allows anyone holding it to use the @chown command to transfer ownership to themselves. Only wizards can transfer ownership to others, regardless of the value of CHOWN_OK. DARK When set on a room, hides all objects in the room. Connect, disconnect, arrival and departure messages are not displayed. On the FDCMuck, the FDC Player Start room (#100) is dark, so that you cannot see all the players who still use it as their home and are disconnected. When set on a program, becomes DEBUG and allows the programmer to do a stgack trace on the code. For all other objects, hides the object from view. Regular players can only set rooms DARK. Muckers can set programs DEBUG. Wizzes and the owner of a room can always see in it, even if it is DARK. HAVEN Set this flag on you if you do not want to be disturbed. The page and cb programs respect this flag and will not page a player set HAVEN. The HAVEN flag has other purposes if the kill command is functioning, but it is disabled on the FDCMuck. The flag has no meaning for other objects, but exits set HAVEN are omitted from the exits list on a room. This is a way of making the exit partly "DARK". JUMP_OK When set on a thing, person or room, allows the object's owner to use @teleport to move the object to any other location with either the LINK_OK or JUMP_OK flags set. The exact rules for allowing teleporting are complicated and rely on ownership of things and the rooms they are in. Some programs, such as jump also respect this flag. LINK_OK When set on any object, allows any other player to link any exit to it. By setting this on a room, you are allowing anyone to make an exit lead into the room; you will still be the only player who can make an exit leading out of the room. Also, you are allowing people to use @teleport to set the room as a parent, as with ABODE. By setting LINK_OK on yourself, you allow others to make an exit leading to yourself. Players who have an exit leading to you can teleport to your location using the exit (you still must have your JUMP_OK flag set). Setting things LINK_OK allows players to link to the thing with an action, even though they do not own it (for examples of linking to things, see "Toggles" in Object/Action Trickery). The LINK_OK flag does not permit setting a home (linking a thing or person to a room). For that, see the ABODE flag above. MUCKER This flag specifies whether a player is allowed to program in MUF. Most FDCMuck players do not have this flag set. When set on a room, the flag becomes MURKY. MURKY rooms are partly dark; their objects are not displayed, but OSUCC, OFAIL, ODROP, arrival and departure messages are still shown. Only a wizard can set a MUCKER or MURKY flag, though there is a Wizard-owned global murk which toggles a room's murkiness for you. QUELL Wizards, by default, can do unspeakably powerful things (see the @toad command for an example). To protect themselves and other players from accidents, wizards usually set the QUELL flag on themselves so that they only seem as powerful as a regular player unless otherwise necessary. The QUELL flag is otherwise useless and can only be set by a wizard. STICKY When set on a thing, if the object is dropped, it does not remain in the current room but goes to its home. When set on an action attached to an thing and linked to a thing, does not sent the former object home when the action is performed (see "Summoning objects" in Object/Action trickery for an explanation of this). When set on a program, becomes the SETUID flag. Programs run with the permissions and privileges of the owner of the program. WIZARD The administrators of a Muck are wizards. As such they have almost unlimited powers. Only the head wizard (with dbref #1) can set and clear this flag. Getting Help If you ever find yourself needing more help on a topic, the first place to look is the online help. Just type help and you will be presented with an index of the topics available. If you want help on the @chown command, type help @chown If you need more personal help, find a cast member or wizard, with either of the commands: hosts wizzes and ask them what you need. There are also a number of unqualified yet highly experienced players on the Muck. Most seasoned players will be able to point you in the right direction. Learning more There is a sequel to this tutorial called Object/Action Trickery. You should probably understand most of what has been said in this tutorial before reading its sequel.