A Nested Room is any object that isn't a room but which can contain an actor: chairs, beds, platforms, vehicles, and the like.

An important property of nested rooms is that they're not full-fledged rooms for the purposes of actor arrivals and departures. Specifically, an actor moving from a room to a nested room within the room does not trigger an actor.travelTo invocation, but simply moves the actor from the containing room to the nested room. Moving from the nested room to the containing room likewise triggers no actor.travelTo invocation. The travelTo method is not applicable for intra-room travel because no TravelConnector objects are traversed in such travel; we simply move in and out of contained objects. To mitigate this loss of notification, we instead call actor.travelWithin() when moving among nested locations.

By default, an actor attempting to travel from a nested location via a directional command will simply attempt the travel as though the actor were in the enclosing location.

By default, 'out' within a nested room should take us out of the nested room itself. The easy way to accomplish this is to set up a 'nestedRoomOut' connector for the nested room, which will automatically try a GET OUT command. If we didn't do this, we'd *usually* pick up the noTravelOut from our enclosing room, but only when the enclosing room didn't override 'out' to point somewhere else. Explicitly setting up a 'noTravelOut' here ensures that we'll consistently GET OUT of the nested room even if the enclosing room has its own 'out' destination.

Note that nestedRoomOut shows as a listed exit in exit listings (for the EXITS command and in the status line). If you don't want OUT to be listed as an available exit for the nested room, you should override this to use noTravelOut instead.

Our interior room name. This is the status line name we display when an actor is within this object and can't see out to the enclosing room. Since we can't rely on the enclosing room's status line name if we can't see the enclosing room, we must provide one of our own.

The valid "staging locations" for this nested room. This is a list of the rooms from which an actor can DIRECTLY reach this nested room; in other words, the actor will be allowed to enter 'self', with no intervening travel, if the actor is directly in any of these locations.

If the list is empty, there are no valid staging locations.

The point of listing staging locations is to make certain that the actor has to go through one of these locations in order to get into this nested room. This ensures that we enforce any conditions or trigger any side effects of moving through the staging locations, so that a player can't bypass a puzzle by trying to move directly from one location to another without going through the required intermediate steps. Since we always require that an actor go through one of our staging locations in order to enter this nested room, and since we carry out the travel to the staging location using implied commands (which are just ordinary commands, entered and executed automatically by the parser), we can avoid having to code any checks redudantly in both the staging locations and any other nearby locations.

By default, an actor can only enter a nested room from the room's direct container. For example, if a chair is on a stage, an actor must be standing on the stage before the actor can sit on the chair.

Report that we are unable to move an actor out of this nested room, because there's no valid 'exit destination'. This is called when we attempt to GET OUT OF the nested room, and the 'exitDestination' property is nil.

Report that we are unable to move an actor to any staging location for this nested room. By default, we'll generate the message "you can't do that from here," but this can overridden to provide a more specific if desired.

Check, using precondition rules, that the actor is in a valid "staging location" for entering this nested room. We'll ensure that the actor is directly in one of the locations in our stagingLocations list, running an appropriate implicit command to move the actor to the first item in that list if the actor isn't in any of them.

Check, using pre-condition rules, that the actor is removed from this nested location and moved to my immediate location. This is used to enforce a precondition that the actor is in the enclosing location.

Try moving the actor into this location. This is used to move the actor into this location as part of meeting preconditions, and we use the normal precondition check protocol: we return nil if the condition (actor is in this room) is already met; we return true if we successfully execute an implied command to meet the condition; and we report a failure message and terminate the command with 'exit' if we don't know how to meet the condition or the implied command we try to execute fails or fails to satisfy the condition.

Choose an intermediate staging location, given the actor's current location. This routine is called when the actor is attempting to move into 'self', but isn't in any of the allowed staging locations for 'self'; this routine's purpose is to choose the staging location that the actor should implicitly try to reach on the way to 'self'.

By default, we'll attempt to find the first of our staging locations that indirectly contains the actor. (We know none of the staging locations directly contains the actor, because if one did, we wouldn't be called in the first place - we're only called when the actor isn't already directly in one of our staging locations.) This approach is appropriate when nested rooms are related purely by containment: if an actor is in a nested room within one of our staging locations, we can reach that staging location by having the actor get out of the more deeply nested room.

However, this default approach is not appropriate when nested rooms are related in some way other than simple containment. We don't have any general framework for other types of nested room relationships, so this routine must be overridden in such a case with special-purpose code defining the special relationship.

If we fail to find any staging location indirectly containing the actor, we'll return the result of defaultStagingLocation().

The default staging location for this nested room. This is the staging location we'll attempt to reach implicitly if the actor isn't in any of the rooms in the stagingLocations list already. We'll return the first element of our stagingLocations list for which isStagingLocationKnown returns true.

Is the given staging location "known"? This returns true if the staging location is usable as a default, nil if not. If this returns true, then the location can be used in an implied command to move the actor to the staging location in order to move the actor into self.

If this returns nil, no implied command will be attempted for this possible staging location. This doesn't mean that an actor gets a free pass through the staging location; on the contrary, it simply means that we won't try any automatic command to move an actor to the staging location, hence travel from a non-staging location to this nested room will simply fail. This can be used when part of the puzzle is to figure out that moving to the staging location is required in the first place: if we allowed an implied command in such cases, we'd give away the puzzle by solving it automatically.

Replace the current action with one that removes the actor from this nested room. This is used to implement the GET OUT command when the actor is directly in this nested room. In most cases, this should simply be implemented with a call to replaceAction() with the appropriate command.

Get the travel preconditions for an actor in this location. By default, if we have a container, and the actor can see the container, we'll return its travel preconditions; otherwise, we'll use our inherited preconditions.

Try an implied command to move the actor from outside of this nested room into this nested room. This must be overridden in subclasses to carry out the appropriate implied command. Returns the result of tryImplicitAction().

This is called when we need to move an actor into this location as part of an implied command. We use an overridable method because different kinds of nested rooms have different commands for entering: SIT ON CHAIR, LIE ON BED, GET IN CAR, RIDE BIKE, and so on. This should be normally be overridden imply by calling tryImplicitAction() with the appropriate command for the specific type of nested room, and returning the result.

Try an implied command to remove an actor from this location and place the actor in my immediate containing location. This must be overridden in subclasses to carry out the appropriate implied command. Returns the result of tryImplicitAction().

This is essentially the reverse of tryMovingIntoNested(), and should in most cases be implemented by calling tryImplicitAction() with the appropriate command to get out of the room, and returning the result.