My vector of actors who are accompanying me.

This is for internal bookkeeping only, and it applies to the current travel only. This is NOT a general "follow mode" setting, and it shouldn't be used to get me to follow another actor or another actor to follow me. To make me accompany another actor, simply override accompanyTravel() so that it returns a suitable ActorState object.

our list of registered actor notification items

The actor's "agenda." This is a list of AgendaItem objects that describe things the actor wants to do of its own volition on its own turn.

Antecedent lookup table. Each actor keeps its own table of antecedents indexed by pronoun type, so that we can simultaneously have different antecedents for different pronouns.

our special "boredom" agenda item - this makes us initiate an end to an active conversation when the PC has ignored us for a given number of consecutive turns

Our conversational "boredom" counter. While we're in a conversation, this tracks the number of turns since the last conversational command from the actor we're talking to.

Note that this state is part of the actor, even though it's usually managed by the InConversationState object. The state is stored with the actor rather than with the state object because it really describes the condition of the actor, not of the state object.

You can limit the cumulative amount of bulk an actor can hold, and the maximum bulk of any one object the actor can hold, using bulkCapacity and maxSingleBulk. These properties are analogous to the same ones in Container.

A word of caution on these is in order. Many authors worry that it's unrealistic if the player character can carry too much at one time, so they'll fiddle with these properties to impose a carrying limit that seems realistic. Be advised that authors love this sort of "realism" a whole lot more than players do. Players almost universally don't care about it, and in fact tend to hate the inventory juggling it inevitably leads to. Juggling inventory isn't any fun for the player. Don't fool yourself about this - the thoughts in the mind of a player who's tediously carting objects back and forth three at a time will not include admiration of your prowess at simulational realism. In contrast, if you set the carrying limit to infinity, it's a rare player who will even notice, and a much rarer player who'll complain about it.

If you really must insist on inventory limits, refer to the BagOfHolding class for a solution that can salvage most of the "realism" that the accountancy-inclined author craves, without creating undue inconvenience for the player. BagOfHolding makes inventory limits palatable for the player by essentially automating the required inventory juggling. In fact, for most players, an inventory limit in conjunction with a bag of holding is actually better than an unlimited inventory, since it improves readability by keeping the direct inventory list to a manageable size.

Test to see if we can match a third-person pronoun ('it', 'him', 'her', 'them'). We can unless we're the player character and the player character is referred to in the first or second person.

Test to see if we can match the third-person pronouns. We'll match these if our inherited test says we match them AND we can be referred to in the third person.

The referral person of the current command targeting the actor. This is meaningful only when a command is being directed to this actor, and this actor is an NPC.

The referral person depends on the specifics of the language. In English, a command like "bob, go north" is a second-person command, while "tell bob to go north" is a third-person command. The only reason this is important is in interpreting what "you" means if it's used as an object in the command. "tell bob to hit you" probably means that Bob should hit the player character, while "bob, hit you" probably means that Bob should hit himself.

Communication senses: these are the senses through which the actor can communicate directly with other actors through commands and messages.

Conceptually, these senses are intended to be only those senses that the actors would *naturally* use to communicate, because senses in this list allow direct communications via the most ordinary game commands, such as "bob, go east".

If some form of indirect communication is possible via a sense, but that form is not something the actor would think of as the most natural, default form of communication, it should *not* be in this list. For example, two sighted persons who can see one another but cannot hear one another could still communicate by writing messages on pieces of paper, but they would ordinarily communicate by talking. In such a case, sound should be in the list but sight should not be, because sight is not a natural, default form of communications for the actors.

the contents of an actor aren't listed in a room's description

conversation manager ID - this is assigned by the conversation manager to map to and from output stream references to the actor; this is only for internal use by the conversation manager

Our table of conversation nodes. At initialization, the conversation manager scans all ConvNode instances and adds each one to its actor's table. This table is keyed by the name of node, and the value for each entry is the ConvNode object - this lets us look up the ConvNode object by name. Because each actor has its own lookup table, ConvNode names only have to be unique within the actor's set of ConvNodes.

Our current conversation node. This is a ConvNode object that keeps track of the flow of the conversation.

Our current state. This is an ActorState object representing what we're currently doing. Whenever the actor changes to a new state (for example, because of a scripted activity), this can be changed to reflect the actor's new state. The state object groups the parts of the actor's description and other methods that tend to vary according to what the actor's doing; it's easier to keep everything related to scripted activities together in a state object than it is to handle all of the variability with switch() statements of the like in methods directly in the actor.

It's not necessary to initialize this if the actor doesn't take advantage of the ActorState mechanism. If this isn't initialized for a particular actor, we'll automatically create a default ActorState object during pre-initialization.

Our list of objects explicitly excluded from 'look around'. These objects will be suppressed from any sort of listing (including in the room's contents list and in special descriptions) in 'look around' when this actor is doing the looking.

Our list of followable information. Each entry in this list is a FollowInfo object that tracks a particular followable.

If we're following an actor, this keeps track of the actor we're following. NPC's can use this to follow around another actor whenever possible.

Get the actors involved in travel, when we're acting in our role as a Traveler. When the Traveler is simply the Actor, the only actor involved in the travel is 'self'.

we're the self-motive actor doing the travel

Hearing-like senses. These are senses that the actor can use to hear objects.

The Lister for inventory listings, for use in a full description of the actor. By default, we use the "long form" inventory lister, on the assumption that most actors have relatively lengthy descriptive text. This can be overridden to use other formats; the short-form lister, for example, is useful for actors with only brief descriptions.

The Lister object that we use for inventory listings. By default, we use actorInventoryLister, but this can be overridden if desired to use a different listing style.

flag: we're an actor

By default, all actors are likely command targets. This should be overridden for actors who are obviously not likely to accept commands of any kind.

This is used to disambiguate target actors in commands, so this should provide an indication of what should be obvious to a player, because the purpose of this information is to guess what the player is likely to take for granted in specifying a target actor.

Actors are not listed with the ordinary objects in a room's description. However, an actor is listed as part of an inventory description.

by default, actors are listed when they arrive aboard a vehicle

Flag: we wait for commands issued to other actors to complete before we get another turn. If this is true, then whenever we issue a command to another actor ("bob, go north"), we will not get another turn until the other actor has finished executing the full set of commands we issued.

By default, this is true, which means that we wait for other actors to finish all of the commands we issue before we take another turn.

If this is set to nil, we'll continue to take turns while the other actor carries out our commands. In this case, the only time cost to us of issuing a command is given by orderingTime(), which normally takes one turn for issuing a command, regardless of the command's complexity. Some games might wish to use this mode for interesting effects with NPC's carrying out commands in parallel with the player, but it's an unconventional style that some players might find confusing, so we don't use this mode by default.

My 'known' property. By default, this is simply 'known', which means that we don't distinguish who knows what.

As with 'seenProp' above, if you want to keep track of each NPC's knowledge separately, you must override this property for each NPC who's to have its own knowledge base to use a separate property name. For example, if you want to keep track of what Bob knows individually, you could define 'knownProp = &bobKnows' in Bob.

the object we most recently consulted

game-clock time (Schedulable.gameClockTime) of the last conversational command addressed to us by the player character

the last door I traversed

The most recent actor that we've interacted with through a conversational command (ASK, TELL, GIVE, SHOW, etc).

the destination and back connector for our last travel

conditions we noted in noteConditionsBefore()

the action the actor performed most recently

by default, use my pronoun for my name

Next available "holding index" value. Each time we pick up an item, we'll assign it our current holding index value and then increment our value. This gives us a simple way to keep track of the order in which we picked up items we're carrying.

Note that we make the simplifying assumption that an object can be held by only one actor at a time (multi-location items are generally not portable), which means that we can use a simple property in each object being held to store its holding index.

let the actor have a turn as soon as the game starts

by default, refer to the player character in the second person

pending commands - this is a list of PendingCommandInfo objects

Our list of pending conversation initiators. In our takeTurn() processing, we'll check this list for conversations that we can initiate.

pending response - this is a single PendingResponseInfo object, which we'll deliver as soon as the issuing actor is in a position to hear us

Possessive anaphor lookup table. In almost all cases, the possessive anaphor for a given pronoun will be the same as the corresponding regular pronoun: HIS indicates possession by HIM, for example. In a few cases, though, the anaphoric quality of possessives takes precedence, and these will differ. For example, in TELL BOB TO DROP HIS BOOK, "his" refers back to Bob, while in TELL BOB TO HIT HIM, "him" refers to whatever it referred to before the command.

My current "posture," which specifies how we're positioned with respect to our container; this is one of the standard library posture enum values (Standing, etc.) or another posture added by the game.

Flag indicating whether or not we've set a ConvNode in the course of the current response. This is for use by the converstaion manager.

Flag: the "target actor" of the command line automatically reverts to this actor at the end of a sentence, when this actor is the issuer of a command. If this flag is nil, an explicit target actor stays in effect until the next explicit target actor (or the end of the entire command line, if no other explicit target actors are named); if this flag is true, a target actor is in effect only until the end of a sentence.

Consider this command line:

>Bob, go north and get fuel cell. Get log tape.

If this flag is nil, then the second sentence ("get log tape") is interpreted as a command to Bob, because Bob is explicitly designated as the target of the command, and this remains in effect until the end of the entire command line.

If this flag is true, on the other hand, then the second sentence is interpreted as a command to the player character, because the target actor designation ("Bob,") lasts only until the end of the sentence. Once a new sentence begins, we revert to the issuing actor (the player character, since the command came from the player via the keyboard).

Scheduling order - this determines the order of execution when several items are schedulable at the same game clock time.

We choose a scheduling order that schedules actors in this relative order:

100 player character, ready to execute
200 NPC, ready to execute
300 player character, idle
400 NPC, idle

An "idle" actor is one that is waiting for another character to complete a command, or an NPC with no pending commands to perform. (For the player character, it doesn't matter whether or not there's a pending command, because if the PC has no pending command, we ask the player for one.)

This ordering ensures that each actor gets a chance to run each turn, but that actors with work to do go first, and other things being equal, the player character goes ahead of NPC's.

The senses that determine scope for this actor. An actor might possess only a subset of the defined sense.

By default, we give each actor all of the human senses that we define, except touch. In general, merely being able to touch an object doesn't put the object in scope, because if an object isn't noticed through some other sense, touch would only make an object accessible if it's within arm's reach, which for our purposes means that the object is being held directly by the actor. Imagine an actor in a dark room: lots of things might be touchable in the sense that there's no physical barrier to touching them, but without some other sense to locate the objects, the actor wouldn't have any way of knowing where to reach to touch things, so they're not in scope. So, touch isn't a scope sense.

My 'seen' property. By default, this is simply 'seen', which means that we don't distinguish who's seen what - in other words, there's a single, global 'seen' flag per object, and if anyone's ever seen something, then we consider that to mean everyone has seen it.

Some games might want to track each NPC's sight memory separately, or at least they might want to track it individually for a few specific NPC's. You can do this by making up a new property name for each NPC whose sight memory you want to keep separate, and simply setting 'seenProp' to that property name for each such NPC. For example, for Bob, you could make the property bobHasSeen, so in Bob you'd define 'sightProp = &bobHasSeen'.

"Sight-like" senses: these are the senses that operate like sight for the actor, and which the actor can use to determine the names of objects and the spatial relationships between objects. These senses should operate passively, in the sense that they should tend to collect sensory input continuously and without explicit action by the actor, the way sight does and the way touch, for example, does not. These senses should also operate instantly, in the sense that the sense can reasonably take in most or all of a location at one time.

These senses are used to determine what objects should be listed in room descriptions, for example.

By default, the only sight-like sense is sight, since other human senses don't normally provide a clear picture of the spatial relationships among objects. (Touch could with some degree of effort, but it can't operate passively or instantly, since deliberate and time-consuming action would be necessary.)

An actor can have more than one sight-like sense, in which case the senses will act effectively as one sense that can reach the union of objects reachable through the individual senses.

Smell-like senses. These are senses that the actor can use to smell objects.

By default, show the special description for an actor in the group of special descriptions that come *after* the room's portable contents listing. An actor's presence is usually a dynamic feature of a room, and so we don't want to suggest that the actor is a permanent feature of the room by describing the actor directly with the room's main description.

By default, put all of the actor special descriptions after the special descriptions of ordinary objects, by giving actors a higher listing order value.

our special traveler

show a "take from" message as indicating I don't have the dobj

Synchronous command processing: the target actor and dummy pending command we're waiting for. When these are non-nil, we won't take another turn until the given PendingCommandInfo has been removed from the given target actor's command queue.

An actor can limit the cumulative amount of weight being held, using weightCapacity. By default we make this so large that there is effectively no limit to how much weight an actor can carry.

Determine if we should accept a command. 'issuingActor' is the actor who issued the command: if the player typed the command on the command line, this will be the player character actor.

This routine performs only the simplest check, since it doesn't have access to the specific action being performed. This is intended as a first check, to allow us to bypass noun resolution if the actor simply won't accept any command from the issuer.

Returns true to accept a command, nil to reject it. If this routine returns nil, and the command came from the player character, a suitable message should be displayed.

Note that most actors should not override this routine simply to express the will of the actor to accept a command, since this routine performs a number of checks for the physical ability of the actor to execute a command from the issuer. To determine whether or not the actor should obey physically valid commands from the issuer, override obeyCommand().

Check to see if I'm busy with pending commands, and if so, whether or not I should accept a new command. Returns true if we should accept a command, nil if not. If we return nil, we must notify the issuer of the rejection.

By default, we won't accept a command if we have any work pending.

Perform any actor-specific processing for an action. The main command processor invokes this on gActor after notifying nearby objects via beforeAction(), but before carrying out the main action of the command.

Carry out a "follow" command being performed by this actor.

Actor "I am here" description. This is displayed as part of the description of a room - it describes the actor as being present in the room. By default, we let the "nominal actor container" provide the description.

Get my listing group for my special description as part of a room description. By default, we'll let our immediate location decide how we're grouped.

Show our status, as an addendum to the given room's name (this is the room title, shown at the start of a room description and on the status line). By default, we'll let our nominal actor container provide the status, to indicate when we're standing/sitting/lying in a nested room.

In concrete terms, this generally adds a message such as "(sitting on the chair)" to the name of a room if we're in a nested room within the room. When we're standing in the main room, this generally adds nothing.

Note that we pass the room we're describing as the "container to ignore" parameter, because we don't want to say something like "Phone Booth (standing in the phone booth)" - that is, we don't want to mention the nominal container again if the nominal container is what we're naming in the first place.

Actor's "I am over there" description. This is displayed in the room description when the actor is visible, but is either in a separate top-level room or is at a distance. By default, we let the "nominal actor container" provide the description.

Receive notification that I'm initiating travel. This is called on the actor performing the travel action before the travel is actually carried out.

Verify a "follow" command being performed by this actor.

Add the given actor to the list of actors accompanying my travel on the current turn. This does NOT set an actor in "follow mode" or "accompany mode" or anything like that - don't use this to make an actor follow me around. Instead, this makes the given actor go with us for the CURRENT travel only - the travel we're already in the process of performing to process the current TravelVia action.

Add an item to our registered notification items. These items are to receive notifications when we're the actor performing a command.

Items can be added here if they must be notified of actions performed by the actor even when the items aren't connected by containment with the actor at the time of the action. All items connected to the actor by containment are automatically notified of each action; only items that must receive notification even when not in scope need to be registered here.

Add busy time. An action calls this when we are the actor performing the action, and the action consumes game time. This marks us as busy for the given time units.

Insert a resolved action at the start of our pending command list. The new command is specified as a resolved Action object; it is added before any commands already in our list.

Insert a command at the head of our pending command list. The new command is specified as a list of tokens to parse, and it is inserted into our pending command list before any commands already in the list.

Add a resolved action to our pending command list. The new command is specified as a resolved Action object; it is added after any commands already in our list.

Add a command to our pending command list. The new command is specified as a list of tokens to be parsed, and it is added after any commands already in our pending list.

add an agenda item

add an object to my contents

Adjust a table of visible objects for 'look around'. By default, we remove any explicitly excluded objects.

Receive notification that a command has just been carried out in our presence.

receive a notification that someone has just traveled here

Get the name with an indefinite article. Use the same rules of referral person as for definite articles.

aName in objective case

Receive notification that a command is being carried out in our presence.

receive a notification that someone is about to travel

Get the best (most transparent) sense information for one of our visual senses to the given object.

calculate the scheduling order

Determine whether or not I can understand an attempt by another actor to talk to me. 'talker' is the actor doing the talking. 'sense' is the sense we're testing; this will always be a sense in our communicationSenses list, and will always be a communications sense we have in common with the other actor. 'info' is a SenseInfo object giving information on the clarity of the sense path to the other actor.

We return true if we can understand the communication, nil if not. There is no middle ground where we can partially understand; we can either understand or not.

Note that this routine is concerned only with our ability to sense the communication. The result here should NOT pay any attention to whether or not we can actually communicate given a clear sense path - for example, this routine should not reflect whether or not we have a spoken language in common with the other actor.

This is a service method for canTalkTo. This is broken out as a separate method so that individual actors can override the necessary conditions for communications in particular senses.

Determine if I can hear the given object.

Handle a situation where we're trying to follow an actor but can't. By default, this simply cancels our follow mode.

Actors might want to override this to be more tolerant. For example, an actor might want to wait until five turns elapse to give up on following, in case the target actor returns after a brief digression; or an actor could stay in follow mode until it received other instructions, or found something better to do.

We have a parser error to report to the player, but we cannot respond at the moment because the player is not capable of hearing us (there is no sense path for our communications senses from us to the player actor). Defer reporting the message until later.

Can I own the given object? By default, an actor can own anything.

Determine if I can see the given object. This returns true if the object can be sensed at all in one of my sight-like senses, nil if not.

Determine if I can smell the given object.

Determine if I can communicate with the given character via a natural, default form of communication that we share with the other character. This determines if I can talk to the other character. We'll return true if I can talk to the other actor, nil if not.

In order for the player character to issue a command to a non-player character (as in "bob, go east"), the NPC must be able to sense the PC via at least one communication sense that the two actors have in common.

Likewise, in order for a non-player character to say something to the player, the player must be able to sense the NPC via at least one communication sense that the two actors have in common.

Check a bulk change of one of my direct contents.

Check for travel in the dark. If we're in a dark room, and our destination is a dark room, ask the connector for guidance.

Travel connectors normally call this before invoking our travelTo() method to carry out the travel. The darkness check usually must be made before any barrier checks.

Try moving the actor into the given room in preparation for travel, using pre-condition rules.

Check to ensure the actor is ready to enter the given nested room, using pre-condition rules. By default, we'll ask the given nested room to handle it.

use a custom message for cases where we're holding a destination object for BOARD, ENTER, etc

Check to see if we want to allow another actor to take something from my inventory. By default, we won't allow it - we'll always fail the command.

Check to see if we're waiting for another actor to do something. Return true if so, nil if not. If we've been waiting for another actor, and the actor has finished the task we've been waiting for since the last time we checked, we'll clean up our internal state relating to the wait and return nil.

Conjugate a regular verb in the present or past tense for our person and number.

In the present tense, this is pretty easy: we add an 's' for the third person singular, and leave the verb unchanged for every other case. The only complication is that we must check some special cases to add the -s suffix: -y -> -ies, -o -> -oes.

In the past tense, we use the inherited handling since the past tense ending doesn't vary with person.

Did we engage in any conversation on the current turn? This can be used as a quick check in background activity scripts when we want to run a step only in the absence of any conversation on the same turn.

Copy pronoun antecedents from the given actor. This should be called whenever an actor issues a command to us, so that pronouns in the command are properly resolved relative to the issuer.

the default response for ASK FOR

Show the default answer to a question - this is called when we're the actor in ASK <actor> ABOUT <topic>, and we can't find a more specific response for the given topic.

By default, we'll show the basic "there's no response" message. This isn't a very good message in most cases, because it makes an actor pretty frustratingly un-interactive, which gives the actor the appearance of a cardboard cut-out. But there's not much better that the library can do; the potential range of actors makes a more specific default response impossible. If the default response were "I don't know about that," it wouldn't work very well if the actor is someone who only speaks Italian. So, the best we can do is this generally rather poor default. But that doesn't mean that authors should resign themselves to a poor default answer; instead, it means that actors should take care to override this when defining an actor, because it's usually possible to find a much better default for a *specific* actor.

The *usual* way of providing a default response is to define a DefaultAskTopic (or a DefaultAskTellTopic) and put it in the actor's topic database.

default refusal of a command

Show a default response to a conversational action. By default, we'll show the default response for our conversation type.

the default response for GIVE TO

show our default goodbye message

Show our default greeting message - this is used when the given another actor greets us with HELLO or TALK TO, and we don't otherwise handle it (such as via a topic database entry).

By default, we'll just show "there's no response" as a default message. We'll show this in default mode, so that if the caller is going to show a list of suggested conversation topics (which the 'hello' and 'talk to' commands will normally try to do), the topic list will override the "there's no response" default. In other words, we'll have one of these two types of exchanges:

>talk to bob
There's no response

>talk to bill
You could ask him about the candle, the book, or the bell, or
tell him about the crypt.

default response to being told NO

the default response for SHOW TO

Show the default response to being told of a topic - this is called when we're the actor in TELL <actor> ABOUT <topic>, and we can't find a more specific response for the topic.

As with defaultAskResponse, this should almost always be overridden by each actor, since the default response ("there's no response") doesn't make the actor seem very dynamic.

The usual way of providing a default response is to define a DefaultTellTopic (or a DefaultAskTellTopic) and put it in the actor's topic database.

default response to being told YES

Describe the actor via the "nominal actor container." The nominal container is determined by our direct location.

'contToIgnore' is a container to ignore. If our nominal container is the same as this object, we'll generate a description without a mention of a container at all.

The reason we have the 'contToIgnore' parameter is that the caller might already have reported our general location, and now merely wants to add that we're standing or standing or whatever. In these cases, if we were to say that we're sitting on or standing on that same object, it would be redundant information: "Bob is in the garden, sitting in the garden." The 'contToIgnore' parameter tells us the object that the caller has already mentioned as our general location so that we don't re-report the same thing. We need to know the actual object, rather than just the fact that the caller mentioned a general location, because our general location and the specific place we're standing or sitting or whatever might not be the same: "Bob is in the garden, sitting in the lawn chair."

Disembark. This is used by the 'Get out' action to carry out the command. By default, we'll let the room handle it.

also mark the visible contents of the object as having been seen

cannot kiss oneself

do the normal work

treat PUT SELF IN FOO as GET IN FOO

For the basic physical manipulation verbs (TAKE, DROP, PUT ON, etc), it's illogical to operate on myself, so check for this in verify(). Otherwise, handle these as we would ordinary objects, since we might be able to manipulate other actors in the normal manner, especially actors small enough that we can pick them up.

let the state object handle it

let our state object handle it

Break off our current conversation, of the NPC's own volition. This is the opposite number of initiateConversation: this causes the NPC to effectively say BYE on its own, rather than waiting for the PC to decide to end the conversation.

This call is mostly useful when the actor's current state is an InConversationState, since the main function of this routine is to switch to an out-of-conversation state.

examine my contents specially

show our status

Add an object to the 'look around' exclusion list. Returns true if the object was already in the list, nil if not.

The main processing for an actor's turn. In most cases, subclasses should override this method (rather than executeTurn) to specialize an actor's turn processing.

Execute the next item in our agenda, if there are any items in the agenda that are ready to execute. We'll return true if we found an item to execute, nil if not.

Execute one "turn" - this is a unit of time passing. The player character generally is allowed to execute one command in the course of a turn; a non-player character with a programmed task can perform an increment of the task.

We set up an ActorTurnAction environment and invoke our executeActorTurn() method. In most cases, subclasses should override executeActorTurn() rather than this method, since overriding executeTurn() directly will lose the action environment.

Find the object that prevents us from seeing the given object.

invoke a callback on each actor traveling with the traveler

forget the possessive anaphors

Get the library message object for action responses. This is used to generate library responses to verbs.

Build a list of the objects that are explicitly registered to receive notification when I'm the actor in a command.

Calculate the amount of bulk I'm holding directly. By default, we'll simply add up the "actor-encumbering bulk" of each of our direct contents.

Note that we don't differentiate here based on whether or not an item is being worn, or anything else - we deliberately leave such distinctions up to the getEncumberingBulk routine, so that only the objects are in the business of deciding how bulky they are under different circumstances.

Get the current interlocutor. By default, we'll address new conversational commands (ASK ABOUT, TELL ABOUT, SHOW TO) to the last conversational partner, if that actor is still within range.

Get the default interlocutor. If there's a current interlocutor, and we can still talk to that actor, then that's the default interlocutor. If not, we'll return whatever actor is the default for a TALK TO command. Note that TALK TO won't necessarily have a default actor; if it doesn't, we'll simply return nil.

Get the location into which objects should be moved when the actor drops them with an explicit 'drop' command. By default, we return the drop destination of our current container.

Get the list of objects I can follow. This is a list of all of the objects which I have seen departing a location - these are all in scope for 'follow' commands.

Get information on what to do to make this actor follow the given object. This returns a FollowInfo object that reports our last knowledge of the given object's location and departure, or nil if we don't know anything about how to follow the actor.

Get my "look around" location name as a string. This returns a string containing the location name that we display in the status line or at the start of a "look around" description of my location.

Get the deferred library message object for a parser message addressed to the player character. We only use this to generate messages deferred from non-player characters.

get the library message object for a parser message addressed to the player character

get a possessive anaphor value

look up a pronoun's value

Get the "push traveler" for the actor. This is the nominal traveler that we want to use when the actor enters a command like PUSH BOX NORTH. 'obj' is the object we're trying to push.

we are the owner of any TopicEntry objects contained within us

Get the object that's actually going to move when this actor travels via the given connector. In most cases this is simply the actor; but when the actor is in a vehicle, travel commands move the vehicle, not the actor: the actor stays in the vehicle while the vehicle moves to a new location. We determine this by asking our immediate location what it thinks about the situation.

If we have a special traveler explicitly set, it overrides the traveler indicated by the location.

Get the ambient light level in the visual senses at this actor. This is the ambient level at the actor.

Calculate the total weight I'm holding. By default, we'll add up the "actor-encumbering weight" of each of our direct contents.

Note that we deliberately only consider our direct contents. If any of the items we are directly holding contain further items, getEncumberingWeight will take their weights into account; this frees us from needing any special knowledge of the internal structure of any items we're holding, and puts that knowledge in the individual items where it belongs.

Go to sleep. This is used by the 'Sleep' action to carry out the command. By default, we simply say that we're not sleepy; actors can override this to cause other actions.

Handle a conversational command. All of the conversational actions (HELLO, GOODBYE, YES, NO, ASK ABOUT, ASK FOR, TELL ABOUT, SHOW TO, GIVE TO) are routed here when we're the target of the action (for example, we're BOB in ASK BOB ABOUT TOPIC) AND the ActorState doesn't want to handle the action.

determine if I've ever seen the given object

Hide actors from 'all' by default. The kinds of actions that normally apply to 'all' and the kinds that normally apply to actors have pretty low overlap.

If a particular actor looks a lot like an inanimate object, it might want to override this to participate in 'all' for most or all actions.

don't hide actors from defaulting, though - it's frequently convenient and appropriate to assume an actor by default, especially for commands like GIVE TO and SHOW TO

When it's our turn and we don't have any command to perform, we'll call this routine, which can perform a scripted operation if desired.

Implicit command handling style for this actor. There are two styles for handling implied commands: "player" and "NPC", indicated by the enum codes ModePlayer and ModeNPC, respectively.

In "player" mode, each implied command is announced with a description of the command to be performed; DEFAULT responses are suppressed; and failures are shown. Furthermore, interactive requests for more information from the parser are allowed. Transcripts like this result:

>open door
(first opening the door)
(first unlocking the door)
What do you want to unlock it with?

In "NPC" mode, implied commands are treated as complete and separate commands. They are not announced; default responses are shown; failures are NOT shown; and interactive requests for more information are not allowed. When an implied command fails in NPC mode, the parser acts as though the command had never been attempted.

By default, we return ModePlayer if we're the player character, ModeNPC if not (thus the respective names of the modes). Some authors might prefer to use "player mode" for NPC's as well as for the player character, which is why the various parts of the parser that care about this mode consult this method rather than simply testing the PC/NPC status of the actor.

Perform library pre-initialization on the actor

Initiate a conversation with the player character. This lets the NPC initiate a conversation, in response to something the player character does, or as part of the NPC's scripted activity. This is only be used for situations where the NPC initiates the conversation - if the player character initiates conversation with TALK TO, ASK, TELL, etc., we handle the conversation through our normal handlers for those commands.

'state' is the ActorState to switch to for the conversation. This will normally be an InConversationState object, but doesn't have to be.

You can pass nil for 'state' to use the current state's implied conversational state. The implied conversational state of a ConversationReadyState is the associated InConversationState; the implied conversation state of any other state is simply the same state.

'node' is a ConvNode object, or a string naming a ConvNode object. We'll make this our current conversation node. A valid conversation node is required because we use this to generate the initial NPC greeting of the conversation. In most cases, when the NPC initiates a conversation, it's because the NPC wants to ask a question or otherwise say something specific, so there should always be a conversational context implied, thus the need for a ConvNode. If there's no need for a conversational context, the NPC script code might just as well display the conversational exchange as a plain old message, and not bother going to all this trouble.

Initiate a conversation based on the given simulation object. We'll look for an InitiateTopic matching the given object, and if we can find one, we'll show its topic response.

Add to an inventory description a list of things we notice through a specific sense.

Build a lookup table of the objects that can be sensed for the purposes of taking inventory. We'll include everything in the normal visual sense table, plus everything directly held.

handle it as a 'hello' topic

let the state object handle it

customize the message for THROW TO <actor>

is an actor traveling with us?

Determine if the given object is a likely topic for a conversational action performed by this actor. By default, we'll return true if the topic is known, nil if not.

Determine if my location is lit for my sight-like senses.

determine if I'm the player character

Determine if I know about the given object. I know about an object if it's specifically marked as known to me; I also know about the object if I can see it now, or if I've ever seen it in the past.

Determine if the actor recognizes the given object as a "topic," which is an object that represents some knowledge the actor can use in conversations, consultations, and the like.

By default, we'll recognize any Topic object marked as known, and we'll recognize any game object for which our knowsAbout(obj) returns true. Games might wish to override this in some cases to limit or expand an actor's knowledge according to what the actor has experienced of the setting or story. Note that it's often easier to control actor knowledge using the lower-level knowsAbout() and setKnowsAbout() methods, though.

Describe the actor as part of the EXAMINE description of a nested room containing the actor. 'povActor' is the actor doing the looking.

Display a description of the actor's location from the actor's point of view.

If 'verbose' is true, then we'll show the full description in all cases. Otherwise, we'll show the full description if the actor hasn't seen the location before, or the terse description if the actor has previously seen the location.

Set our posture to the given status. By default, we'll simply set our posture property to the new status, but actors can override this to handle side effects of the change.

We meet the objHeld precondition for ourself - that is, for any verb that requires holding an object, we can be considered to be holding ourself.

desribe our containment of an object as carrying the object

Receive notification that this is a non-idle turn. This is called whenever a command in our pending command queue is about to be executed.

This method need not do anything at all, since the caller will take care of running the pending command. The purpose of this method is to take care of any changes an actor wants to make when it receives an explicit command, as opposed to running its own autonomous activity.

By default, we cancel follow mode if it's in effect. It usually makes sense for an explicit command to interrupt follow mode; follow mode is usually started by an explicit command in the first place, so it is usually sensible for a new command to replace the one that started follow mode.

Note conditions after an action or other event. By default, if we are still in the same location we were in when noteConditionsBefore() was last called, and the light/dark status has changed, we'll mention the change in light/dark status.

Note conditions before an action or other event. By default, we note our location and light/dark status, so that we comment on any change in the light/dark status after the event if we're still in the same location.

note that we're consulting an item

Note that we're taking part in a conversational action with another character. This is symmetrical - it could mean we're the initiator of the conversation action or the target. We'll remember the person we're talking to, and reset our conversation time counters so we know we've conversed on this turn.

Note that we're performing a conversational command targeting the given actor. We'll make the actors point at each other with their 'lastInterlocutor' properties. This is called on the character performing the conversation command: if the player types ASK BOB ABOUT BOOK, this will be called on the player character actor, with 'other' set to Bob.

Note that another actor is issuing a conversational command targeting us. For example, if the player types ASK BOB ABOUT BOOK, then this will be called on Bob, with the player character actor as 'other'.

Note that the given object has been explicitly shown to me. By default, we'll mark the object and its visible contents as having been seen by me. This is called whenever we're the target of a SHOW TO or GIVE TO, since presumably such an explicit act of calling our attention to an object would make us consider the object as having been seen in the future.

receive notification that another actor is observing us

Receive notification that a command we sent to another NPC failed. This is only called when one NPC sends a command to another NPC; this is called on the issuer to let the issuer know that the target can't perform the command because of the given resolution failure.

By default, we don't do anything here, because we don't have any default code to send a command from one NPC to another. Any custom NPC actor that sends a command to another NPC actor might want to use this to deal with problems in processing those commands.

Notify an issuer that a command sent to us resulted in a parsing failure. We are meant to reply to the issuer to let the issuer know about the problem. messageProp is the libGlobal message property describing the error, and args is a list with the (varargs) arguments to the message property.

Receive notification that a TopicEntry response in our database is being invoked. We'll just pass this along to our current state.

Show the description of this actor when this actor is a non-player character.

This description should include only the constant, fixed description of the character. Do not include information on what the actor is doing right now, because that belongs in the ActorState object instead. When we display the actor's description, we'll show this text, and then we'll show the ActorState description as well; this combination approach makes it easier to keep the description synchronized with any scripted activities the actor is performing.

By default, we'll show this as a "default descriptive report," since it simply says that there's nothing special to say. However, whenever this is overridden with an actual description, you shouldn't bother to use defaultDescReport - simply display the descriptive message directly:

npcDesc = "He's wearing a gorilla costume. "

Determine whether or not we want to obey a command from the given actor to perform the given action. We only get this far when we determine that it's possible for us to accept a command, given the sense connections between us and the issuing actor, and given our pending command queue.

When this routine is called, the action has been determined, and the noun phrases have been resolved. However, we haven't actually started processing the action yet, so the globals for the noun slots (gDobj, gIobj, etc) are NOT available. If the routine needs to know which objects are involved, it must obtain the full list of resolved objects from the action (using, for example, getResolvedDobjList()).

When there's a list of objects to be processed (as in GET ALL), we haven't started working on any one of them yet - this check is made once for the entire command, and applies to the entire list of objects. If the actor wants to respond specially to individual objects, you can do that by overriding actorAction() instead of this routine.

This routine should display an appropriate message and return nil if the command is not to be accepted, and should simply return true to accept the command.

By default, we'll let our state object handle this.

Note that actors that override this might also need to override wantsFollowInfo(), since an actor that accepts "follow" commands will need to keep track of the movements of other actors if it is to carry out any following.

Get a default acknowledgment of a change to our posture. This should acknowledge the posture so that it tells us the current posture. This is used for a command such as "stand up" from a chair, so that we can report the appropriate posture status in our acknowledgment; we might end up being inside another nested container after standing up from the chair, so we might not simply be standing when we're done.

The amount of time, in game clock units, it takes me to issue an order to another actor. By default, it takes one unit (which is usually equal to one turn) to issue a command to another actor. However, if we are configured to wait for our issued commands to complete in full, the ordering time is zero; we don't need any extra wait time in this case because we'll wait the full length of the issued command to begin with.

The default description when we examine this actor and the actor is serving as the player character. This should generally not include any temporary status information; just show constant, fixed features.

Show my posture, as part of the full EXAMINE description of this actor. We'll let our nominal actor container handle it.

Determine if we're ready to do something on our turn. We're ready to do something if we're not waiting for another actor to finish doing something and either we're the player character or we already have a pending command in our command queue.

refer to the player character with my player character referral person, and refer to all other characters in the third person

Remember the last door I traveled through. We use this information for disambiguation, to boost the likelihood that an actor that just traveled through a door is referring to the same door in a subsequent "close" command.

Remember our most recent travel. If we know the back connector (i.e., the connector that reverses the travel we're performing), then we'll be able to accept a GO BACK command to attempt to return to the previous location.

remove an item from the registered notification list

remove an agenda item

Reverse the most recent travel. If we're still within the same destination we reached in the last travel, and we know the connector we arrived through (i.e., the "back connector" for the last travel, which reverses the connector we took to get here), then try traveling via the connector.

Travel arrival/departure messages. Defer to the current state object on all of these.

Say hello/goodbye/yes/no to the given actor. We'll greet the target actor is the target actor was specified (i.e., actor != self); otherwise, we'll greet our current default conversational partner, if we have one.

Handle the XSPCLTOPIC pseudo-command. This command is generated by the SpecialTopic pre-parser when it recognizes the player's input as matching an active SpecialTopic's custom syntax. Our job is to route this back to our current interlocutor's active ConvNode, so that it can find the SpecialTopic that it matched in pre-parsing and show its response.

handle one of the conversational addresses

Schedule initiation of conversation. This allows the caller to set up a conversation to start on a future turn. The conversation will start after (1) the given number of turns has elapsed, and (2) the player didn't target this actor with a conversational command on the same turn. This allows us to set the NPC so that it *wants* to start a conversation, and will do so as soon as it has a chance to get a word in.

If 'turns' is zero, the conversation can start the next time the actor takes a turn; so, if this is called during the PC's action processing, the conversation can start on the same turn. Note that if this is called during the actor's takeTurn() processing, it won't actually start the conversation until the next turn, because that's the next time we'll check the queue. If 'turns' is 1, then the player will get at least one more command before the conversation will begin, and so on with higher numbers.

Build a list of all of the objects of which an actor is aware.

An actor is aware of an object if the object is within reach of the actor's senses, and has some sort of presence in that sense. Note that both of these conditions must be true for at least one sense possessed by the actor; an object that is within earshot, but not within reach of any other sense, is in scope only if the object is making some kind of noise.

In addition, objects that the actor is holding (i.e., those contained by the actor directly) are always in scope, regardless of their reachability through any sense.

Perform scripted travel to the given adjacent location. This looks for a directional connector in our current location whose destination is the given location, and for a corresponding back-connector in the destination location. If we can find the connectors, we'll perform the travel using travelTo().

The purpose of this routine is to simplify scripted travel for simple cases where directional connectors are available for the desired travel. This routine is NOT suitable for intelligent goal-seeking NPC's who automatically try to find their own routes, for two reasons. First, this routine only lets an NPC move to an *adjacent* location; it won't try to find a path between arbitrary locations. Second, this routine is "omniscient": it doesn't take into account what the NPC knows about the connections between locations, but simply finds a connector that actually provides the desired travel.

What this routine *is* suitable for are cases where we have a pre-scripted series of NPC travel actions, where we have a list of rooms we want the NPC to visit in order. This routine simplifies this type of scripting by automatically finding the connectors; the script only has to specify the next location for the NPC to visit.

set the current conversation node

set the current conversation node, with a reason code

set the current state

mark the object to remember that I've seen it

set the antecedent for the feminine singular ("her")

set the antecedent for the masculine singular ("him")

set the antecedent for the neuter singular pronoun ("it" in English)

mark the object as known to me

set a possessive anaphor value

set a possessive anaphor

Set a pronoun antecedent to the given list of ResolveInfo objects. Pronoun handling is language-specific, so this implementation is part of the English library, not the generic library.

If only one object is present, we'll set the object to be the antecedent of 'it', 'him', or 'her', according to the object's gender. We'll also set the object as the single antecedent for 'them'.

If we have multiple objects present, we'll set the list to be the antecedent of 'them', and we'll forget about any antecedent for 'it'.

Note that the input is a list of ResolveInfo objects, so we must pull out the underlying game objects when setting the antecedents.

set a pronoun's antecedent value

Set a pronoun antecedent to the given ResolveInfo list, for the specified type of pronoun. We don't have to worry about setting other types of pronouns to this antecedent - we specifically want to set the given pronoun type. This is language-dependent because we still have to figure out the number (i.e. singular or plural) of the pronoun type.

Set a pronoun to refer to multiple potential antecedents. This is used when the verb has multiple noun slots - UNLOCK DOOR WITH KEY. For verbs like this, we have no way of knowing in advance whether a future pronoun will refer back to the direct object or the indirect object (etc) - we could just assume that 'it' will refer to the direct object, but this won't always be what the player intended. In natural English, pronoun antecedents must often be inferred from context at the time of use - so we use the same approach.

Pass an argument list consisting of ResolveInfo lists - that is, pass one argument per noun slot in the verb, and make each argument a list of ResolveInfo objects. In other words, you call this just as you would setPronoun(), except you can pass more than one list argument.

We'll store the multiple objects as antecedents. When we need to resolve a future singular pronoun, we'll figure out which of the multiple antecedents is the most logical choice in the context of the pronoun's usage.

Set a pronoun antecedent to the given simulation object (usually an object descended from Thing).

Set the "special traveler." When this is set, we explicitly perform travel through this object rather than through the traveler indicated by our location. Returns the old value, so that the old value can be restored when the caller has finished its need for the special traveler.

set the antecedent list for the ungendered plural pronoun ("them")

Show what the actor is carrying.

Show what the actor is carrying, using the given listers.

Note that this method must be overridden if the actor does not use a conventional 'contents' list property to store its full set of contents.

When we're asked to show a special description as part of the description of a containing object (which will usually be a nested room of some kind), just show our posture in our container, rather than showing our full "I am here" description.

Always list actors specially, rather than as ordinary items in contents listings. We'll send this to our current state object for processing, since our "I am here" description tends to vary by state.

Stand up. This is used by the 'Stand' action to carry out the command.

Suggest topics of conversation. This is called by the TOPICS command (in which case 'explicit' is true), and whenever we first engage a character in a stateful conversation (in which case 'explicit' is nil).

We'll show the list of suggested topics associated with our current conversational partner. If there are no topics, we'll say nothing unless 'explicit' is true, in which case we'll simply say that there are no topics that the player character is thinking about.

The purpose of this method is to let the game author keep an "inventory" of topics with this actor for a given conversational partner. This inventory is meant to represent the topics that on the player character's mind - things the player character wants to talk about with the other actor. Note that we're talking about what the player *character* is thinking about - obviously we don't know what's on the player's mind.

When we enter conversation, or when the player asks for advice, we'll show this inventory. The idea is to help guide the player through a conversation without the more heavy-handed device of a formal conversation menu system, so that conversations have a more free-form feel without leaving the player hunting in the dark for the magic ASK ABOUT topic.

The TOPICS system is entirely optional. If a game doesn't specify any SuggestedTopic objects, then this routine will simply never be called, and the TOPICS command won't be allowed. Some authors think it gives away too much to provide a list of topic suggestions like this, and others don't like anything that smacks of a menu system because they think it destroys the illusion created by the text-input command line that the game is boundless. Authors who feel this way can just ignore the TOPICS system. But be aware that the illusion of boundlessness isn't always a good thing for players; hunting around for ASK ABOUT topics can make the game's limits just as obvious, if not more so, by exposing the vast number of inputs for which the actor doesn't have a good response. Players aren't stupid - a string of variations on "I don't know about that" is just as obviously mechanistic as a numbered list of menu choices. Using the TOPICS system might be a good compromise for many authors, since the topic list can help guide the player to the right questions without making the player feel straitjacketed by a menu list.

Suggest topics that the given actor might want to talk to us about. The given actor is almost always the player character, since generally NPC's don't talk to one another using conversation commands (there'd be no point; they're simple programmed automata, not full-blown AI's).

Receive notification that an object is leaving its current location as a result of the action we're currently processing. Actors (and possibly other objects) will broadcast this notification to all Actor objects connected in any way by containment when they move under their own power (such as with Actor.travelTo) to a new location. We'll keep tracking information if we are configured to keep tracking information for the given object and we can see the given object. Note that this is called when the object is still at the source end of the travel - the important thing is that we see the object departing.

'obj' is the object that is seen to be leaving, and 'conn' is the TravelConnector it is taking.

'conn' is the connector being traversed. If we're simply being observed in this location (as in a call to setHasSeen), rather than being observed to leave the location, the connector will be nil.

'from' is the effective starting location of the travel. This isn't necessarily the departing object's location, since the departing object could be inside a vehicle or some other kind of traveler object.

Note that this notification is sent only to actors with some sort of containment connection to the object that's moving, because a containment connection is necessary for there to be a sense connection.

Show my name for an arrival/departure message. If we've been seen before by the player character, we'll show our definite name, otherwise our indefinite name.

Get the preconditions for travel. By default, we'll add the standard preconditions that the connector requires for actors.

Note that these preconditions apply only when the actor is the traveler. If the actor is in a vehicle, so that the vehicle is the traveler in a given travel operation, the vehicle's travelerPreCond conditions are used instead of ours.

Traveler interface: perform local travel, between nested rooms within a single top-level location.

Travel to a new location.

Travel within a location, as from a room to a contained nested room. This should generally be used in lieu of travelTo when traveling between locations that are related directly by containment rather than with TravelConnector objects.

Travel within a location is not restricted by darkness; we assume that if the nested objects are in scope at all, travel among them is allowed.

This type of travel does not trigger calls to travelerLeaving() or travelerArriving(). To mitigate this loss of notification, we call actorTravelingWithin() on the source and destination objects.

Try making room to hold the given object. This is called when checking the "room to hold object" pre-condition, such as for the "take" verb.

If holding the new object would exceed the our maximum holding capacity, we'll go through our inventory looking for objects that can reduce our held bulk with implicit commands. Objects with holding affinities - "bags of holding", keyrings, and the like - can implicitly shuffle the actor's possessions in a manner that is neutral as far as the actor is concerned, thereby reducing our active holding load.

Returns true if an implicit command was attempted, nil if not.

Try moving the given object into this object. For an actor, this will do one of two things. If 'self' is the actor performing the action that's triggering this implied command, then we can achieve the goal simply by taking the object. Otherwise, the way to get an object into my possession is to have the actor performing the command give me the object.

remove an object from the 'look around' exclusion list

By default, all actors are followable.

verify() handler to check against applying an action to 'self'

Build a table of full sensory information for all of the objects visible to the actor through the actor's sight-like senses. Returns a lookup table with the same set of information as senseInfoTable().

Build a table of full sensory information for all of the objects visible to me from a particular point of view through my sight-like senses.

Wait for completion of a command that we issued to another actor. The parser calls this routine after each time we issue a command to another actor.

If we're configured to wait for completion of orders given to other actors before we get another turn, we'll set ourselves up in waiting mode. Otherwise, we'll do nothing.

Do I track departing objects for following the given object?

By default, the player character tracks everyone, and NPC's track only the actor they're presently tasked to follow. Most NPC's will never accept 'follow' commands, so there's no need to track everyone all the time; for efficiency, we take advantage of this assumption so that we can avoid storing a bunch of tracking information that will never be used.