Color Guide:
Red indicates a command (or commands) you enter into the MUCK.
Navy indicates text returned by the MUCK, usually a result of a command you typed.


Lists And MPI

This tutorial will teach you what a list is and how it can be a powerful tool in your MPI coding. We'll use a list and a little MPI to show how you can greatly enhance the MUCK's object description property. It will be helpful if you are familiar with object properties and how to view and manipulate them. It will also be helpful if you know the basic concepts of MPI, although we'll be doing only simple coding here.

First let's create an object to play with:
Now let's examine the properties of the flower object:
OK, so there aren't any yet. Let's give it one.

You could also set the description by:
@desc is just a pre-defined shorthand way to set the _/de property of an object. I will generally use the @set method in these tutorials, because it reinforces the idea of what we're doing and it can be used to set any property. Now let's look at the flower object again.
When you 'look' at an object, the MUCK responds with what is contained in the special _/de property:
Very nice, but so what? This flower may need only a short description, but some objects may require long descriptions. Descriptions are limited in length. In A Bug's Muck, the limit is approximately 1024 characters. While you don't want to generate a novel when someone looks at your object, a thousand characters is more limiting than it may seem. So let's look at a solution for this problem.

Instead of a single-line description, we're going to use several properties to hold multiple lines and use the _/de property to point to them. When we do this we're building a special kind of property structure (propdir) called a list. You may have used the list editor 'lsedit' before. What lsedit does is allow an easy way to create or edit a list. Here's how to use it to create a more advanced data structure for our flower that will eventually hold a more complex description. Lsedit is used like this: lsedit object = list name. Our object is 'flower' and we'll choose 'desc' for the property name of the list we're going to build.
Let's see what lsedit built:
So a list is just an organized group of properties with the following structure:
If you aren't familiar with lsedit or don't want to fire it up for a simple change, you can edit the list with @set commands. In fact, you can build the entire list using only @set commands, like this:
If you edit a list by hand and alter the number of lines in the list, make sure you also edit the list property that displays the number of lines, or you may get strange results when using the list. I use @set if I want to change the contents of a single line of a list, and lsedit when I am doing a more complex edit that will change the number of lines.

What are the {nl} functions? These are simple MPI functions that generate the two hidden ASCII characters necessary to force text to wrap to a new line. Two consecutive {nl} functions can be used to make a paragraph break.

Now that you know lists a bit, let's see how they can be useful. Let's change the flower's primary description property _/de to re-direct it to display our new list when someone does a 'look':
Let's look at the flower again:
MPI functions in the special _/de property are automatically executed, so when 'look' encounters the lexec function, it knows to run the function instead of diplaying the literal string '{lexec:desc}'. In this case, lexec tells the MUCK to display the the list called 'desc'. and execute any MPI functions found in the 'desc' list.

This is a simple demonstration of using lists. The idea is that you can use a list to add as many paragraphs as you wish to your description. If your description really will be as short as the one for this flower, stick with leaving the entire description in the _/de: property; it's faster and more efficient.

We could have done this: @set flower=_/de:{list:desc}. This works a little faster, but would have the following result:
The MPI {nl} functions didn't generate line break characters, and worse, the functions themselves are showing up in the flower's description. By default, MPI functions are executed only in special descriptive properties, such as _/de, _/sc, _/osc, _/dr, _/odr. So MPI in the 'desc' properties wasn't executed. By using {lexec:list} we can force the MUCK to execute any MPI code embedded in the list properties. This has some really cool implications. It means that a line in a list might not be description at all, but MPI code that dynamically builds some component of the description. Having code living all by itself on a single line can make things easier than embedding code in a description string. In a later tutorial I'll show how lists can be used to break up a more complex MPI program into a series of easy to follow steps.

I'll end this tutorial with the following example that uses a list for a room description. This description has 3 fixed paragraphs, and a 4th paragraph that varies based on certain room conditions. See if you can figure out what it's doing.