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.


Creating Random Results With MPI

MPI allows you to make descriptions that vary according to the circumstances, or create actions that yield different responses. Often you'll want to control what the resulting message says, but sometimes you might want all or part of the message to be random. In this tutorial you'll learn how to use two MPI functions related to random results. To get the most out of this tutorial, be sure to read Lists and MPI before reading this one.

Say you have an object representing a pile of sticks. You could describe the object as 'You see a pile of sticks lying on the ground', but it's just as easy to specify an undetermined number of sticks. For example:
Two MPI functions were used here. The first, Dice, has the form {dice:x} and is used to generate a number from 1 to x. In this example, x is 4, so {dice:4} will return a number from 1 to 4. We want at least a few sticks lying around (one stick would get lonely and start pining), so the example uses the Add function to add 1 to the result for a range of 2 to 5 sticks. Add takes the form {add:x,y} and returns x + y. When someone looks at the pile, they might see something like: 'You see a pile of 3 sticks lying on the ground.'

Here's the same idea used to create a pair of dice. In this case, we'll create an action called 'roll' which will have a random result:
The above example uses a different form of Dice, {dice:x,y}, which is like saying 'generate y random numbers with a range of 1 to x and add them together'. In games, this is commonly written as ydx. In the above example, we're using 2d6, the same as tossing two 6-sided dice as you would in the game of craps. Dice has a third useful variation, {dice:x,y,z} which yields ydx+z.

You can do only so much with random numbers. Sometimes you want random text results. You can use the dice function to randomly pick from several properties on an object to complete a description. Here's an example that improves on the pile of sticks:
In this example we've created four properties, one for each numerical result. The dice function is used to generate a number from 2 to 5, which is then used to build the property to choose: sticks2, sticks3, sticks4, or sticks5. The Prop function has the form {prop:propname}. It returns the value of the named property, which is then substituted into the description. Now a typical response might read: 'You see a pile of three sticks lying on the ground.'

The above example works, but it's a bit limiting because you need to generate and maintain three unrelated properties which can be a pain if the number of properties gets large. Here's where a property list can be handy. You can use Lsedit to build a property list containing the variable properties, and use the Rand function to select one of the components from the list and return the property's value. This is a fairly powerful utility. Rand has the form {rand:propname}. It takes the name of a property list as its argument and returns the value of a random property in the list.

For an example, say you have a room called 'myplace' and you want part of the room's description to include a random component describing a flight of birds overhead. You can use Lsedit to build a property list called 'birds':
Of course you can also build the property list by hand rather than use Lsedit:
Now let's add a description to the room that includes a random reference to the flight of birds:
That's all there is to it. If you use this technique, make sure that all your random sentence components fit well with their position in the sentence.

Using these ideas, here's how you can make a magic eight ball, complete with authentic magic eight ball responses:
Typically Rand has the form {rand:propname} which works fine when the property is on the triggering object. In this case, the property we're looking for isn't on the triggering object (the 'consult' action), but on the owning eight ball object. We need to use Rand's second form {rand:propname,object} so we can tell Rand to look for the property name on another object. Many MPI functions have this ability.

The construction {loc:this} uses the MPI Location function to find the 'consult' action's owning object. 'this' is a standard MPI value referring to the object that triggered the MPI call, in this case the 'consult' action. Remember that we need to do this because the random results are saved on the ball object, not the action object. We could use the dbref of the ball: {rand:_result,#1234}, but that requires us to know what the dbref is, which might not always be handy. Using {loc:this} instead of a dbref saves us from having to remember dbrefs.

Notice that others are told that the eight ball was consulted but they don't see the result. What if you want others to see the eight ball's wise and knowing answer? At first glance, the following approach might seem like a good solution:
Can you spot the problem with this? Each time Rand is called, it will return a different result. So what the user sees and what others see are very likely to be different. To solve this problem, generate a random response first, and store it as a temporary property on the 'consult' action which can be used by all messages later. Here's one way to do this:
I hope you're now comfortable with two of MPI's random functions, Dice and Rand, and maybe you can think of a few applications for your own projects. There's another MPI function related to randomness, Lrand, which I talk about in the tutorial Building A Complex MPI Function: Random Character Selection. Good luck, and have some random fun!