Note that a MultiLoc object appears *in its entirety* in each of its locations. This means that MultiLoc is most suitable for a couple of specific situations:
- several locations overlap slightly so that they include a common object: a large statue at the center of a public square, for example;
- an object forms a sense connection among its location: a window;
- a distant object that is seen in its entirety from several locations: the moon, say, or a mountain range.
Note that MultiLoc is NOT suitable for cases where an object spans several locations but isn't contained entirely in any one of them: it's not good for something like a rope or a river, for example. MultiLoc also isn't good for cases where you simply want to avoid creating a bunch of repeated decorations in different locations. MultiLoc isn't good for these cases because a MultiLoc is treated as though it exists ENTIRELY and SIMULTANEOUSLY in all of its locations, which means that all of its sense information and internal state is shared among all of its locations.
MultiInstance is better than MultiLoc for cases where you want to share a decoration object across several locations. MultiInstance is better because it creates individual copies of the object in the different locations, so each copy has its own separate sense information and its own separate identity.
MultiFaceted is better for objects that span several locations, such as a river or a long rope. Like MultiInstance, MultiFaceted creates a separate copy in each location; in addition, MultiFaceted relates the copies together as "facets" of the same object, so that the parser knows they're all actually parts of one larger object.
MultiLoc : BaseMultiLoc
A MultiLoc does not, by default, connect its multiple locations together. This means that if we're traversing in from a point of view outside the MultiLoc object, we don't add any of our other containers to the connection table. However, the MultiLoc itself, and its contents, *can* see out to all of its locations; so if we're traversing from a point of view inside self, we will add all of our containers to the connection list.
Note that when we don't have a path, or there's no container of ours preceding us in the path, the object being dropped must be starting inside us. It would be highly unusual for this to happen with a multi-location object, because MutliLoc isn't designed for use as a "nested room" or the like. However, it's not an impossible situation; if the game does want to create such a scenario, then the game simply needs to override this routine so that it does whatever makes sense in the game scenario. There's no general way to handle such situations, but it should be possible to determine the correct handling for specific scenarios.
Note that this doesn't trigger any moveInto notifications. This routine is a re-initialization rather than an in-game action, so it's not meant to behave as though an actor in the game were walking around moving the MultiLoc around; thus no notifications are sent. Note also that we attempt to minimize our work by computing the "delta" from the old state - hence we only move the MultiLoc into containers it wasn't in previously, and we only remove it from existing containers that it's no longer in.