MultiInstance class | objects.t[3049]

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`

Superclass Tree (in declaration order)

`MultiInstance`
`BaseMultiLoc`
`object`

Subclass Tree

`MultiInstance`
`MultiFaceted`

Global Objects

(none)

Summary of Properties

`instanceList instanceMixIn instanceObject`

Inherited from `BaseMultiLoc` :
`initialLocationClass locationList`

Summary of Methods

`addInstance addToContents getInstanceIn initializeLocation moveInto moveIntoAdd moveOutOf removeFromContents`

Inherited from `BaseMultiLoc` :
`buildLocationList isDirectlyIn isIn isInitiallyIn isListedInContents isOrIsIn`

Properties

`instanceList` | `objects.t[3159]`

our vector of active instance objects

`instanceMixIn` | `objects.t[3156]`

the mix-in superclass for our instance objects

`instanceObject` | `objects.t[3051]`

the template object

Methods

`addInstance (loc)` | `objects.t[3119]`

internal service routine - add an instance for a given location

`addToContents (obj)` | `objects.t[3147]`

If any contents are added to the MultiInstance object, they must be contents of the template object, so add them to the template object instead of the MultiInstance parent.

`getInstanceIn (loc)` | `objects.t[3115]`

get our instance object (if any) that's in the given location

`initializeLocation ( )` | `objects.t[3054]`

initialize my locations

`moveInto (loc)` | `objects.t[3065]`

Move the MultiInstance into the given location. This removes us from any other existing locations and adds us (if we're not already there) to the given location.

`moveIntoAdd (loc)` | `objects.t[3091]`

Add the new location to our set of locations. Any existing locations are unaffected.

`moveOutOf (loc)` | `objects.t[3102]`

Remove me from the given location. Other locations are unaffected.

`removeFromContents (obj)` | `objects.t[3153]`

remove an object from our contents - we'll delegate this to our template object just like we delegate addToContents

TADS 3 Library Manual
Generated on 8/21/2012 from TADS version 3.1.2