A "multi-instance" object is a simple way of creating copies of an object in several places. This is often useful for decorations and other features that recur in a whole group of rooms.

You define a multi-instance object in two parts.

First, you define a MultiInstance object, which is just a hollow shell of an object that sets up the location relationships. This shell object doesn't have any presence in the game world; it's just a programming abstraction.

Second, as part of the shell object, you define an example of the object that will actually show up in the game in each of the multiple locations. You do this by defining a nested object under the 'instanceObject' property of the shell object. This is otherwise a perfectly ordinary object. In most cases, you'll want to make this a Decoration, Fixture, or some other non-portable object class, since the "cloned" nature of these objects means that you usually won't want them moving around (if they did, you might run into situations where you had several of them in the same place, leading to disambiguation headaches for the player).

Here's an example of how you set up a multi-instance object:

trees: MultiInstance
locationList = [forest1, forest2, forest3]
instanceObject: Fixture { 'tree/trees' 'trees'
"Many tall, old trees grow here. "
isPlural = true
}
;

Note that the instanceObject itself has no location, because it doesn't appear in the game-world model itself - it's just a template for the real objects.

During initialization, the library will automatically create several instances (i.e., subclasses) of the example object - one instance per location, to be exact. These instances are the real objects that show up in the game world.

MultiInstance has one more helpful feature: it lets you dynamically change the set of locations where the instances appear. You do this using the same interface that you use to move around MultiLoc objects - moveInto(), moveIntoAdd(), moveOutOf(). When you call these routines on the MultiInstance shell object, it will add and remove object instances as needed to keep everything consistent. Thanks to a little manipulation we do on the instance objects when we set them up, you can also move the instance objects around directly using moveInto(), and they'll update the MultiInstance parent to keep its location list consistent.

class MultiInstance :   BaseMultiLoc