TravelConnector class | travel.t[775]

A Travel Connector is a special connection interface that allows for travel from one location to another. Most actor movement, except for movement between locations related by containment (such as from a room to sitting in a chair within the room) are handled through travel connector objects.

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.

`class TravelConnector : Thing`

Superclass Tree (in declaration order)

`TravelConnector`
`Thing`
`VocabObject`
`object`

Subclass Tree

`TravelConnector`
`AskConnector`
`DefaultAskConnector`
`Passage`
`Stairway`
`StairwayDown`
`StairwayUp`
`ThroughPassage`
`BasicDoor`
`Door`
`AutoClosingDoor`
`SecretDoor`
`HiddenDoor`
`ExitOnlyPassage`
`PathPassage`
`RoomConnector`
`OneWayRoomConnector`
`RoomAutoConnector`
`Room`
`DarkRoom`
`FloorlessRoom`
`OutdoorRoom`
`ShipboardRoom`
`TravelMessage`
`DeadEndConnector`
`NoTravelMessage`
`FakeConnector`

Global Objects

`noTravel`

Summary of Properties

`connectorStagingLocation isCircularPassage isConnectorListed rememberCircularPassage travelBarrier travelMemory`

Inherited from `Thing` :
`actorInAName actorInName actorInPrep actorIntoName actorOutOfName actorOutOfPrep aDisambigName allStates aName brightness bulk canBeHeard canBeSeen canBeSmelled canBeTouched canMatchHer canMatchHim canMatchIt canMatchThem circularlyInMessage collectiveGroup collectiveGroups contents contentsListed contentsListedInExamine contentsListedSeparately contentsLister descContentsLister described disambigEquivName disambigName distantDesc distantInitSpecialDesc distantSpecialDesc distinguishers dummyName effectiveFollowLocation equivalenceKey equivalentGrouper equivalentGrouperClass equivalentGrouperTable esEndingPat explicitVisualSenseInfo getState globalParamName holdingIndex iesEndingPat initDesc initNominalRoomPartLocation initSpecialDesc inlineContentsLister isEquivalent isHer isHim isInInitState isKnown isLikelyCommandTarget isListedAboardVehicle isMassNoun isPlural isProperName isQualifiedName isThingConstructed isTopLevel listName listWith location lookInLister moved name nameDoes nameSays nameSees notTravelReadyMsg objectNotifyList objInPrep obscuredInitSpecialDesc obscuredSpecialDesc owner patElevenEighteen patIsAlpha patLeadingTagOrQuote patOfPhrase patOneLetterAnWord patOneLetterWord patSingleApostropheS patTagOrQuoteChar patUpperOrDigit patVowelY pluralDisambigName pluralName pronounSelector roomDarkName roomLocation roomName seen sightPresence sightSize smellPresence smellSize soundPresence soundSize specialContentsLister specialDesc specialDescBeforeContents specialDescListWith specialDescOrder specialNominalRoomPartLocation suppressAutoSeen takeFromNotInMessage theDisambigName theName theNamePossNoun tmpAmbient_ tmpAmbientFill_ tmpAmbientWithin_ tmpFillMedium_ tmpObstructor_ tmpObstructorWithin_ tmpPathIsIn_ tmpTrans_ tmpTransWithin_ touchPresence touchSize verbCan verbCannot verbCant verbEndingSD verbEndingSEd verbEndingSMessageBuilder_ verbMust verbToCome verbToDo verbToGo verbToLeave verbToSay verbToSee verbWill verbWont weight`

Inherited from `VocabObject` :
`canResolvePossessive disambigPromptOrder pluralOrder vocabLikelihood vocabWords weakTokens`

Summary of Methods

`actorTravelPreCond canTravelerPass checkTravelBarriers connectorBack connectorGetConnectorTo connectorTravelPreCond createUnlistedProxy darkTravel describeArrival describeDeparture describeLocalArrival describeLocalDeparture describeRemoteTravel dobjFor(TravelVia) explainTravelBarrier fixedSource getApparentDestination getDestination isConnectorApparent isConnectorPassable isConnectorVisibleInDark noteTraversal rememberTravel`

Inherited from `Thing` :
`acceptCommand addAllContents addDirectConnections addObjectNotifyItem addToContents addToSenseInfoTable adjustLookAroundTable adjustThrowDestination afterAction afterTravel allContents aNameFrom aNameObj aNameOwnerLoc announceDefaultObject appendHeldContents atmosphereList baseMoveInto basicExamine basicExamineFeel basicExamineListen basicExamineSmell basicExamineTaste beforeAction beforeTravel buildContainmentPaths cacheAmbientInfo cacheSenseInfo cacheSensePath canBeHeardBy canBeSeenBy canBeSensed canBeSmelledBy canBeTouchedBy canDetailsBeSensed canHear canMatchPronounType canMoveViaPath cannotGoShowExits cannotReachObject cannotSeeSmellSource cannotSeeSoundSource canOwn canSee canSmell canThrowViaPath canTouch canTouchViaPath checkActorOutOfNested checkBulkChange checkBulkChangeWithin checkMoveViaPath checkStagingLocation checkThrowViaPath checkTouchViaPath checkTravelerDirectlyInRoom childInName childInNameGen childInNameWithOwner childInRemoteName clearSenseInfo cloneForMultiInstanceContents cloneMultiInstanceContents conjugateRegularVerb connectionTable construct contentsInFixedIn countDisambigName countListName countName countNameFrom countNameOwnerLoc darkRoomContentsLister defaultDistantDesc defaultObscuredDesc desc directionForConnector distantSmellDesc distantSoundDesc dobjFor(AskAbout) dobjFor(AskFor) dobjFor(AskVague) dobjFor(AttachTo) dobjFor(Attack) dobjFor(AttackWith) dobjFor(Board) dobjFor(Break) dobjFor(Burn) dobjFor(BurnWith) dobjFor(Clean) dobjFor(CleanWith) dobjFor(Climb) dobjFor(ClimbDown) dobjFor(ClimbUp) dobjFor(Close) dobjFor(Consult) dobjFor(ConsultAbout) dobjFor(CutWith) dobjFor(Detach) dobjFor(DetachFrom) dobjFor(Dig) dobjFor(DigWith) dobjFor(Doff) dobjFor(Drink) dobjFor(Drop) dobjFor(Eat) dobjFor(Enter) dobjFor(EnterOn) dobjFor(Examine) dobjFor(Extinguish) dobjFor(Fasten) dobjFor(FastenTo) dobjFor(Feel) dobjFor(Flip) dobjFor(Follow) dobjFor(GetOffOf) dobjFor(GetOutOf) dobjFor(GiveTo) dobjFor(GoThrough) dobjFor(JumpOff) dobjFor(JumpOver) dobjFor(Kiss) dobjFor(LieOn) dobjFor(Light) dobjFor(ListenTo) dobjFor(Lock) dobjFor(LockWith) dobjFor(LookBehind) dobjFor(LookIn) dobjFor(LookThrough) dobjFor(LookUnder) dobjFor(Move) dobjFor(MoveTo) dobjFor(MoveWith) dobjFor(Open) dobjFor(PlugIn) dobjFor(PlugInto) dobjFor(Pour) dobjFor(PourInto) dobjFor(PourOnto) dobjFor(Pull) dobjFor(Push) dobjFor(PushTravel) dobjFor(PutBehind) dobjFor(PutIn) dobjFor(PutOn) dobjFor(PutUnder) dobjFor(Read) dobjFor(Remove) dobjFor(Screw) dobjFor(ScrewWith) dobjFor(Search) dobjFor(Set) dobjFor(SetTo) dobjFor(ShowTo) dobjFor(SitOn) dobjFor(Smell) dobjFor(StandOn) dobjFor(Strike) dobjFor(Switch) dobjFor(Take) dobjFor(TakeFrom) dobjFor(TalkTo) dobjFor(Taste) dobjFor(TellAbout) dobjFor(TellVague) dobjFor(Throw) dobjFor(ThrowAt) dobjFor(ThrowDir) dobjFor(ThrowTo) dobjFor(Turn) dobjFor(TurnOff) dobjFor(TurnOn) dobjFor(TurnTo) dobjFor(TurnWith) dobjFor(TypeLiteralOn) dobjFor(TypeOn) dobjFor(Unfasten) dobjFor(UnfastenFrom) dobjFor(Unlock) dobjFor(UnlockWith) dobjFor(Unplug) dobjFor(UnplugFrom) dobjFor(Unscrew) dobjFor(UnscrewWith) dobjFor(Wear) examineListContents examineListContentsWith examineSpecialContents examineStatus failCheck feelDesc fillMedium findOpaqueObstructor findTouchObstructor forEachConnectedContainer forEachContainer fromPOV getAllForTakeFrom getAllPathsTo getAnnouncementDistinguisher getBagAffinities getBagsOfHolding getBestDistinguisher getBulk getBulkWithin getCarryingActor getCommonContainer getCommonDirectContainer getConnectedContainers getConnectorTo getContentsForExamine getDestName getDropDestination getEncumberingBulk getEncumberingWeight getExtraScopeItems getHitFallDestination getIdentityObject getInScopeDistinguisher getListedContents getLocPushTraveler getLocTraveler getMovePathTo getNoise getNominalDropDestination getNominalOwner getObjectNotifyList getOdor getOutermostRoom getOutermostVisibleRoom getRoomNotifyList getRoomPartLocation getStateWithInfo getStatuslineExitsHeight getThrowPathTo getTouchPathTo getTravelConnector getVisualSenseInfo getWeight hasCollectiveGroup hideFromAll hideFromDefault initializeEquivalent initializeLocation initializeThing inRoomName iobjFor(AttachTo) iobjFor(AttackWith) iobjFor(BurnWith) iobjFor(CleanWith) iobjFor(CutWith) iobjFor(DetachFrom) iobjFor(DigWith) iobjFor(FastenTo) iobjFor(GiveTo) iobjFor(LockWith) iobjFor(MoveWith) iobjFor(PlugInto) iobjFor(PourInto) iobjFor(PourOnto) iobjFor(PutBehind) iobjFor(PutIn) iobjFor(PutOn) iobjFor(PutUnder) iobjFor(ScrewWith) iobjFor(ShowTo) iobjFor(TakeFrom) iobjFor(ThrowAt) iobjFor(ThrowTo) iobjFor(TurnWith) iobjFor(UnfastenFrom) iobjFor(UnlockWith) iobjFor(UnplugFrom) iobjFor(UnscrewWith) isActorTravelReady isComponentOf isDirectlyIn isHeldBy isIn isInFixedIn isListed isListedInContents isListedInInventory isListedInRoomPart isLookAroundCeiling isNominallyIn isNominallyInRoomPart isOccludedBy isOrIsIn isOwnedBy isShipboard isVocabEquivalent itIs itNom itObj itPossAdj itPossNoun itVerb listCardinality localDirectionLinkForConnector lookAround lookAroundPov lookAroundWithin lookAroundWithinContents lookAroundWithinDesc lookAroundWithinName lookAroundWithinSense lookAroundWithinShowExits lookInDesc mainExamine mainMoveInto mapPushTravelHandlers mapPushTravelHandlers mapPushTravelHandlers mapPushTravelHandlers mapPushTravelHandlers meetsObjHeld mergeSenseInfo mergeSenseInfoTable moveInto moveIntoForTravel moveIntoNotifyPath mustMoveObjInto nameIs nameIsnt nameVerb normalizePath notePromptByOwnerLoc notePromptByPossAdj noteSeenBy notifyInsert notifyMoveInto notifyMoveViaPath notifyRemove obscuredDesc obscuredSmellDesc obscuredSoundDesc pluralNameFrom processThrow propHidesProp propWithPresent putInName receiveDrop remoteDesc remoteInitSpecialDesc remoteRoomContentsLister remoteSpecialDesc removeFromContents removeObjectNotifyItem restoreLocation roomActorThereDesc roomContentsLister roomDaemon roomDarkDesc roomDesc roomFirstDesc roomRemoteDesc roomTravelPreCond saveLocation selectPathTo sendNotifyInsert sendNotifyRemove senseAmbientMax senseInfoTable senseObj sensePathFromWithin sensePathFromWithout sensePathToContents sensePathToLoc sensePresenceList setAllSeenBy setContentsSeenBy setGlobalParamName setVisualSenseInfo shineFromWithin shineFromWithout shineOnContents shineOnLoc showDistantSpecialDesc showDistantSpecialDescInContents showInventoryContents showInventoryItem showInventoryItemCounted showListItem showListItemCounted showListItemCountedGen showListItemGen showObjectContents showObscuredSpecialDesc showObscuredSpecialDescInContents showRemoteSpecialDesc showRemoteSpecialDescInContents showSpecialDesc showSpecialDescInContents showSpecialDescInContentsWithInfo showSpecialDescWithInfo showStatuslineExits showWornItem showWornItemCounted smellDesc smellHereDesc soundDesc soundHereDesc specialDescList specialPathFrom statusName stopThrowViaPath superHidesSuper tasteDesc thatNom thatObj theNameFrom theNameObj theNameOwnerLoc theNameWithOwner throwTargetCatch throwTargetHitWith throwViaPath transmitAmbient transSensingIn transSensingOut traversePath tryHolding tryImplicitRemoveObstructor tryMovingObjInto useInitDesc useInitSpecialDesc useSpecialDesc useSpecialDescInContents useSpecialDescInRoom useSpecialDescInRoomPart verbEndingEs verbEndingIes verbEndingS verbToHave verbWas verifyFollowable verifyInsert verifyMoveTo verifyRemove whatIf whatIfHeldBy withVisualSenseInfo`

Inherited from `VocabObject` :
`addToDictionary expandPronounList filterResolveList getFacets inheritVocab initializeVocab initializeVocabWith matchName matchNameCommon matchNameDisambig throwNoMatchForLocation throwNoMatchForPossessive throwNothingInLocation`

Properties

`connectorStagingLocation` | `travel.t[815]`

The "staging location" for travel through this connector. By default, if we have a location, that's our staging location; if we don't have a location (in which case we probably an outermost room), we don't have a staging location.

`isCircularPassage` | `travel.t[1218]`

Is this a "circular" passage? A circular passage is one that explicitly connects back to its origin, so that traveling through the connector leaves us where we started. When a passage is marked as circular, we'll describe travel through the passage exactly as though we had actually gone somewhere. By default, if traveling through a passage leaves us where we started, we assume that nothing happened, so we don't describe any travel.

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.

`isConnectorListed` | `travel.t[963]`

Is this connector listed? This indicates whether or not the exit is allowed to be displayed in lists of exits, such as in the status line or in "you can't go that way" messages. By default, all exits are allowed to appear in listings.

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).

`rememberCircularPassage` | `travel.t[1227]`

Should we remember a circular trip through this passage? By default, we remember the destination of a passage that takes us back to our origin only if we're explicitly marked as a circular passage; in other cases, we assume that the travel was blocked somehow instead.

`travelBarrier` | `travel.t[852]`

Barrier or barriers to travel. This property can be set to a single TravelBarrier object or to a list of TravelBarrier objects. checkTravelBarriers() checks each barrier specified here.

`travelMemory` | `travel.t[1202]`

Our "travel memory" table. If this contains a non-nil lookup table object, we'll store a record of each successful traversal of a travel connector here - we'll record the destination keyed by the combination of actor, origin, and connector, so that we can later check to see if the actor has any memory of where a given connector goes from a given origin.

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.

Methods

`actorTravelPreCond (actor)` | `travel.t[836]`

Get the travel preconditions that this connector requires for travel by the given actor. In most cases, this won't depend on the actor, but it's provided as a parameter anyway; in most cases, this will just apply the conditions that are relevant to actors as travelers.

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.

`canTravelerPass (traveler)` | `travel.t[936]`

Check to see if the Traveler object is allowed to travel through this connector. Returns true if travel is allowed, nil if not.

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.

`checkTravelBarriers (dest)` | `travel.t[858]`

Check barriers. The TravelVia check() routine must call this to enforce barriers.

`connectorBack (traveler, dest)` | `travel.t[1400]`

Find a connector in the destination location that connects back as the source of travel from the given connector when traversed from the source location. Returns nil if there is no such connector. This must be called while the traveler is still in the source location; we'll attempt to find the connector back to the traveler's current location.

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.

`connectorGetConnectorTo (origin, traveler, dest)` | `travel.t[1145]`

Get the travel connector leading to the given destination from the given origin and for the given travel. Return nil if we don't know a connector leading there.

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.

`connectorTravelPreCond ( )` | `travel.t[780]`

Get any connector-specific pre-conditions for travel via this connector.

`createUnlistedProxy ( )` | `travel.t[970]`

Get an unlisted proxy for this connector. This is normally called from the asExit() macro to set up one room exit direction as an unlisted synonym for another.

`darkTravel (actor, dest)` | `travel.t[1541]`

Handle travel in the dark. Specifically, this is called when an actor attempts travel from one dark location to another dark location. (We don't invoke this in any other case: light-to-light, light-to-dark, and dark-to-light travel are all allowed without any special checks.)

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.

`describeArrival (traveler, origin, dest)` | `travel.t[1287]`

Describe an actor's arrival through the connector from the given origin into the given destination. This description is from the point of view of another actor in the destination.

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.

`describeDeparture (traveler, origin, dest)` | `travel.t[1234]`

Describe an actor's departure through the connector from the given origin to the given destination. This description is from the point of view of another actor in the origin location.

`describeLocalArrival (traveler, origin, dest)` | `travel.t[1346]`

Describe a "local arrival" via this connector. This is called when the traveler moves around entirely within the field of view of the player character, and comes *closer* to the PC - that is, the traveler's origin is visible to the player character when we arrive in our destination, AND the destination's top-level location contains the PC. We'll describe the travel not in terms of truly arriving, since the traveler was already here to start with, but rather as entering the destination, but just in terms of moving closer.

`describeLocalDeparture (traveler, origin, dest)` | `travel.t[1329]`

Describe a "local departure" via this connector. This is called when a traveler moves around entirely within the field of view of the player character, and move *further away* from the PC - that is, the traveler's destination is visible to the PC when we're leaving our origin, AND the origin's top-level location contains the PC. We'll describe the travel not in terms of truly departing, but simply in terms of moving away.

`describeRemoteTravel (traveler, origin, dest)` | `travel.t[1360]`

Describe "remote travel" via this connector. This is called when the traveler moves around entirely within the field of view of the PC, but between two "remote" top-level locations - "remote" means "does not contain the PC." In this case, the traveler isn't arriving or departing, exactly; it's just moving laterally from one top-level location to another.

`dobjFor(TravelVia)` | `travel.t[1561]`

Action handler for the internal "TravelVia" action. This is not a real action, but is instead a pseudo-action that we implement generically for travel via the connector. Subclasses that want to handle real actions by traveling via the connector can use remapTo(TravelVia) to implement the real action handlers. Note that remapTo should be used (rather than, say, asDobjFor), since this will ensure that every type of travel through the connector actually looks like a TravelVia action, which is useful for intercepting travel actions generically in other code.

`explainTravelBarrier (traveler)` | `travel.t[948]`

Explain why canTravelerPass() returned nil. This is called to display an explanation of why travel is not allowed by self.canTravelerPass().

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.

`fixedSource (dest, traveler)` | `travel.t[1488]`

Get the "fixed" source for travelers emerging from this connector, if possible. This can return nil if the connector does not have a fixed relationship with another connector.

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.

`getApparentDestination (origin, actor)` | `travel.t[1063]`

Get the apparent destination of travel by the actor to the given origin. This returns the location to which the connector travels, AS FAR AS THE ACTOR KNOWS. If the actor does not know and cannot tell where the connector leads, this should return nil.

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.

`getDestination (origin, traveler)` | `travel.t[1123]`

Get our destination, given the traveler and the origin location.

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.

`isConnectorApparent (origin, actor)` | `travel.t[987]`

Determine if the travel connection is apparent - as a travel connector - to the actor in the given origin location. This doesn't indicate whether or not travel is possible, or where travel goes, or that the actor can tell where the passage goes; this merely indicates whether or not the actor should realize that the passage exists at all.

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.

`isConnectorPassable (origin, traveler)` | `travel.t[1007]`

Determine if the travel connection is passable by the given traveler in the current state. For example, a door would return true when open, nil when closed.

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.

`isConnectorVisibleInDark (origin, actor)` | `travel.t[1507]`

Can the given actor see this connector in the dark, looking from the given origin? Returns true if so, nil if not.

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.

`noteTraversal (traveler)` | `travel.t[1160]`

Note that the connector is being traversed. This is invoked just before the traveler is moved; this notification is fired after the other travel-related notifications (beforeTravel, actorTravel, travelerLeaving). This is a good place to display any special messages describing what happens during the travel, because any messages displayed here will come after any messages related to reactions from other objects.

`rememberTravel (origin, actor, dest)` | `travel.t[1173]`

Service routine: add a memory of a successful traversal of a travel connector. If we have a travel memory table, we'll add the traversal to the table, so that we can find it later.

This is called from Traveler.travelerTravelTo() on successful travel. We're called for each actor participating in the travel.

TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3