Travel connectors are used in the directional link properties in rooms - north, south, east, west, in, out, etc. A room direction link property is always set to a travel connector - but note that a room is itself a travel connector, so a travel link in one room can simply be set to point directly to another room. In many cases, rooms themselves serve as travel connectors, so that one room can point a direction link property directly to another room.
Some travel connectors are physical objects in the simulation, such as doors or stairways; other connectors are just abstract objects that represent connections, but don't appear as manipulable objects in the game.
A travel connector provides several types of information about travel through its connection:
- For actors actually traveling, the connector provides a method that moves an actor through the connector. This method can trigger any side effects of the travel.
- For automatic map builders, actor scripts, and other callers who want to learn what can be known about the link without actually traversing it, the connector provides an "apparent destination" method. This method returns the destination of travel through the connector that a given actor would expect just by looking at the connector. The important thing about this routine is that it doesn't trigger any side effects, but simply indicates whether travel is apparently possible, and if so what the destination of the travel would be.
TravelConnector : Thing
Circular passages don't often occur in ordinary settings; these are mostly useful in disorienting environments, such as twisty cave networks, where a passage between locations can change direction and even loop back on itself.
Note that this indicates if listing is ALLOWED - it doesn't guarantee that listing actually occurs. A connector can be listed only if this is true, AND the point-of-view actor for the listing can perceive the exit (which means that isConnectorApparent must return true, and there must be sufficient light to see the exit).
We keep this information by default, which is why we statically create the table here. Keeping this information does involve some overhead, so some authors might want to get rid of this table (by setting the property to nil) if the game doesn't make any use of the information. Note that this table is stored just once, in the TravelConnector class itself - there's not a separate table per connector.
By default, we require actors to be "travel ready" before traversing a connector. The exact meaning of "travel ready" is provided by the actor's immediate location, but it usually simply means that the actor is standing. This ensures that the actor isn't sitting in a chair or lying down or something like that. Some connectors might not require this, so this routine can be overridden per connector.
Note that this will only be called when an actor is the traveler. When a vehicle or other kind of traveler is doing the travel, this will not be invoked.
This is called from checkTravelBarriers() to check any conditions coded directly into the TravelConnector. By default, we simply return true; subclasses can override this to apply special conditions.
If an override wants to disallow travel, it should return nil here, and then provide an override for explainTravelBarrier() to provide a descriptive message explaining why the travel isn't allowed.
Conditions here serve essentially the same purpose as barrier conditions. The purpose of providing this additional place for the same type of conditions is simply to improve the convenience of defining travel conditions for cases where barriers are unnecessary. The main benefit of using a barrier is that the same barrier object can be re-used with multiple connectors, so if the same set of travel conditions apply to several different connectors, barriers allow the logic to be defined once in a single barrier object and then re-used easily in each place it's needed. However, when a particular condition is needed in only one place, creating a barrier to represent the condition is a bit verbose; in such cases, the condition can be placed in this method more conveniently.
The purpose of this routine is to identify the connector by which the traveler arrives in the new location. This can be used, for example, to generate a connector-specific message describing the traveler's emergence from the connector (so we can say one thing if the traveler arrives via a door, and another if the traveler arrives by climing up a ladder).
By default, we'll try to find a travel link in the destination that links us back to this same connector, in which case we'll return 'self' as the connector from which the traveler emerges in the new location. Failing that, we'll look for a travel link whose apparent source is the origin location.
This should be overridden for any connector with an explicit complementary connector. For example, it is common to implement a door using a pair of objects, one representing each side of the door; in such cases, each door object would simply return its twin here. Note that a complementary connector doesn't actually have to go anywhere, since it's still useful to have a connector back simply for describing travelers arriving on the connector.
This *must* be overridden when the destination location doesn't have a simple connector whose apparent source is this connector, because in such cases we won't be able to find the reverse connector with our direction search.
By default, we simply return 'self' if our destination is the given destination, or nil if not.
Some subclasses might encapsulate one or more "secondary" connectors - that is, the main connector might choose among multiple other connectors. In these cases, the secondary connectors typically won't be linked to directions on their own, so the room can't see them directly - it can only find them through us, since we're effectively a wrapper for the secondary connectors. In these cases, we won't have any single destination ourself, so getDestination() will have to return nil. But we *can* work backwards: given a destination, we can find the secondary connector that points to that destination. That's what this routine is for.
By default, we will prohibit dark-to-dark travel by calling the location's darkTravel handler. Individual connectors can override this to allow such travel or apply different handling.
Note that this is called on the connector that reverses the travel, NOT on the connector the actor is actually traversing - that is, 'self' is the backwards connector, leading from the destination back to the origin location. So, if we have two sides to a door, and the actor traverses the first side, this will be called on the second side - the one that links the destination back to the origin.
Since the default canTravelerPass() always allows travel, the default implementation of this method does nothing. Whenever canTravelerPass() is overridden to return nil, this should also be overridden to provide an appropriate explanation.
The purpose of this routine is to find complementary connectors for simple static map connections. This is especially useful for direct room-to-room connections.
When a connector relationship other than a simple static mapping exists, the connectors must generally override connectorBack(), in which case this routine will not be needed (at least, this routine won't be needed as long as the overridden connectorBack() doesn't call it). Whenever it is not clear how to implement this routine, don't - implement connectorBack() instead.
Note that this method does NOT necessarily return the actual destination, because we obviously can't know the destination for certain until we traverse the connection. Rather, the point of this routine is to return as much information as the actor is supposed to have. This can be used for purposes like auto-mapping, where we'd want to show what the player character knows of the map, and NPC goal-seeking, where an NPC tries to figure out how to get from one point to another based on the NPC's knowledge of the map. In these sorts of applications, it's important to use only knowledge that the actor is supposed to have within the parameters of the simulation.
Callers should always test isConnectorApparent() before calling this routine. This routine does not check to ensure that the connector is apparent, so it could return misleading information if used independently of isConnectorApparent(); for example, if the connector *formerly* worked but has now disappeared, and the actor has a memory of the former destination, we'll return the remembered destination.
The actor can know the destination by a number of means:
1. The location is familiar to the character. For example, if the setting is the character's own house, the character would obviously know the house well, so would know where you'd end up going east from the living room or south from the kitchen. We use the origin method actorKnowsDestination() to determine this.
2. The destination is readily visible from the origin location, or is clearly marked. For example, in an outdoor setting, it might be clear that going east from the field takes you to the hilltop. In an indoor setting, an open passage might make it clear that going east from the living room takes you to the dining room. We use the origin method actorKnowsDestination() to determine this.
3. The actor has been through the connector already in the course of the game, and so remembers the connection by virtue of recent experience. If our travelMemory class property is set to a non-nil lookup table object, then we'll automatically use the lookup table to remember the destination each time an actor travels via a connector, and use this information by default to provide apparent destination information.
This method is required to return the current destination for the travel. If the connector doesn't go anywhere, this should return nil. The results of this method must be stable for the extent of a turn, up until the time travel actually occurs; in other words, it must be possible to call this routine simply for information purposes, to determine where the travel will end up.
This method should not trigger any side effects, since it's necessary to be able to call this method more than once in the course of a given travel command. If it's necessary to trigger side effects when the connector is actually traversed, apply the side effects in noteTraversal().
For auto-mapping and the like, note that getApparentDestination() is a better choice, since this method has internal information that might not be apparent to the characters in the game and thus shouldn't be revealed through something like an auto-map. This method is intended for internal use in the course of processing a travel action, since it knows the true destination of the travel.
A closed door, for example, would return true, because even a closed door makes it clear that travel is possible in the direction, even if it's not possible currently. A secret door, on the other hand, would return nil while closed, because it would not be apparent to the actor that the object is a door at all.
This information is intended to help game code probing the structure of the map. This information is NOT used in actor travel; for actor travel, we rely on custom checks in the connector's TravelVia handler to enforce the conditions of travel. Actor travel uses TravelVia customizations rather than this method because that allows better specificity in reporting failures. This method lets game code get at the same information, but in a more coarse-grained fashion.
This is used to determine if the actor can travel from the given origin via this connector when the actor (in the origin location) is in darkness.
By default, we implement the usual convention, which is that travel from a dark room is possible only when the destination is lit. If we can't determine our destination, we will assume that the connector is not visible.
This is called from Traveler.travelerTravelTo() on successful travel. We're called for each actor participating in the travel.