Crashcourse - Part 01

[Table of contents] [next part]

In this course we will try to make ourself a simple, yet useful object. You will, hopefully, learn the structure of the objects and what you need to do to make them work.

Let's first look at normal items. 'man item' will give you the basics of these objects. As an example, we will try to make ourselves a ruby.

FILENAME: ruby.c

Comments are placed inside '/* */'s and are ignored by the mud. You can also add comments using '//'. This will make the mud ignore everything after '//' on that line. As you can see in ruby.c, we have used both methods to provide an example. However, if you start coding longer functions I recommand to use '//' instead of '/* */' inside them. If you would have used '//' and you want to comment some code out you can easily do that with placing '/*' on front and '*/' at the end of the part. Guess what happens if you would have used '/* */' inside that part ;-)

The two characters: '\n' equals line feed (carriage return) in strings (Just like in normal C). The first thing we should do is include a file called mudlib.h. This should be done in ALL your codefiles. This file contains a lot of useful defines that make your life a bit easier. For instance, if you are making a monster you can now inherit I_MONSTER instead of inheriting the file directly ("/std/monster.c"). This will also help a lot if we, for some unknown reason, should choose to rename or move the monster.c file. If you have used the define, nothing will have to be done with your file, only mudlib.h will have to be updated to point at the new file and that is done be the mudlib arches.

NOTE! The include directive is a special compiler directive that will make the compiler add the file into your own file. This directive, along with the other compiler directives like 'define', must be preceeded with #.
When referring to a filename, you should normally encapsulate it in "'s. But, the mudlib.h is a special header made available as a system header in a special dir. Therefore we use <> to tell the compiler that it is a system dir and not a full path.

After we have included the header file (mudlib.h), it's time to inherit the standard item file. It is done with the inherit call. When we inherit another file, we automatically get all the functions of that file. In this case, we inherit I_ITEM, which gives the ruby normal item functions, like set_weight(), set_value(), etc. If you look at I_ITEM ("/std/item.c"), you will notice that it too inherits a file, namely I_OBJECT, which is the basic of every object in the mud. This inheritance system makes it much easier for us to code, as we don't have to worry about the very basics of each object.
Now we need to tell the compiler what's supposed to happen when the object is created. Therefore we make ourselves a create() function. This function is a standard function for objects that is called once when an object is created. Usually, only this function is neccessary for simple object. We also need to make sure that the inherited create() is called before we start altering the object to suit our needs ('::create();'). This must be done to ensure that all inherited files (or rather objects), are properly initialized before we start to use our item. In this case, ::create() will first call create() in I_ITEM, which will in turn call create() in I_OBJECT. This ensures that all levels of inheritance are properly setup.
Now, we're ready to start changing the object to suit our needs. We give it a name using the set_name() function. We give it an extra identity by using add_id(). This must be done so that we can use 'ruby' as the name. These two functions are standard for almost all objects.

NOTE! It is important that you try to cover all the combinations of the identities given for an object in the set_long(). If the long of an object is: "This is a shining red ruby", we have to give the ruby the following identities: "ruby", "red ruby", "shining ruby", "shining red ruby" and "red shining ruby". If we don't add these and the player types 'look at shining ruby', the player will get the message 'There is no shining ruby here', which is not correct. Therefore, try to use add_id() to give an object all the identities possible. Look at ruby.c for an example of how to use add_id(). Also, the argument passed to set_name() and set_short() will be to the identity list.

If you compare the set_name() call and the add_id() call, you can clearly see that we haven't used the same type of argument. That is because add_id() adds several ids in one go. To achieve this, it uses an array type. 

add_id("ruby");                          // Just one id added.
add_id( ({"shining ruby","red ruby"}) ); // Two ids added using an array.

And don't worry about spaces or tabs in your code, either. They are ignored unless inside "'s. Use them to make your code look nicer.

set_short() and set_long() are also standard for almost all objects. The first one sets a short description for the object. This description is the description you see if the object is laying on the ground or if you look at your inventory.

The long description is what you see if you look at the object itself.

NOTE: There's often a bit of confusion about the use of set_name, add_id, set_short and set_long. Sometimes the case of the output will be strange (uppercase letters in the middle of a sentence). So, when coding your items please remember the following rules:

set_name() requires the name of the object WITHOUT an article (lowercase if not a specific name)
set_short() requires a short description WITH lowercased article ('a' or 'an')
set_long() requires a full sentence (the complete description) beginning with a capital letter.
add_id() takes a string or array of ids, lowercased.

Since we said that the ruby was shining in the descriptions, we should make the object glow softly. For this we use the function called set_light(). It adds some light to the specified object. The next function we call is set_weight() and tells the mudlib how heavy this object is. All standard objects must have at least a weight of 1! Next is set_value(). This value the tells the mudlib how valuable the object is. We have given the ruby the value of 200 gold coins. Meaning that you get 200 gold coins if you sell it in the shop.

Properties are a very important part of objects. They tell the mudlib what the objects are made out of. For instance a golden crown must have the property 'gold' set. The standard properties are usually set in an object if you inherit the right file, but you still have to tell the mudlib if there is something special about the object and what it is made out of. To take a look at the various properties on this mud, you should use the command 'prop'. Use 'prop <property name>' to get detailed info about a property.

Now we have come to the end of the code and we finish it off with the function replace_program(). This function is written to preserve memory and make the mud more memory efficient. Therefore, it is very important to use this function a lot.
BUT, it is also important to know where you can use it. If you make an object which consist ONLY of the create() function, then you can replace-program the file. But, what if you later need special functions that are not in the inherited file? Relax, you can still use it. All you have to do, is move all functions except create() out into a seperate functionfile. You will learn more about this in a later course. When you replace-program a file, it is important that you replace it with the file you inherited earlier in the file.

And, voila, you now have a ruby. If you want to test it, type: 'clone ruby'. Now, it should be inside your inventory and you can look at it. To remove it just type 'dest ruby'. I do not recommend that you copy the file if you want to make your own, but rather make your own from scratch. If you have to, you can always take a peek at the other one while you're making your own, you know. ;-) It's much easier to remember it if you do it from scratch and only peek at it if neccessary.

NOTE! The functions we are going through in the earlier courses are all RESERVED functions and should only be used for the purpose described. 'man functionname' would mostly give you a description of that. It is also important to note that some manual pages are written together in one file. For instance, all the standard functions for items are found in 'man item', for rooms in 'man room', etc. So take your time to read these manual pages.

WRITTEN: 30-Sep-1996 - Gunner
LAST UPDATE: 20-Dec-2003 - Ghorwin
HTML Version: 31-Jan-2000 - Ghorwin

[to the top] [Table of contents] [next part]