# Adv3Lite Task Topical Guide

## Introduction

This Topical Guide is provided as a kind of annotated topic index to the Library Manual. Its aim is to help guide you to the relevant section of the Library Manual for the task you're trying to perform (or the feature you're interested in), especially when neither this manual's Table of Contents nor its Alphabetical Index seems able to do the job. To use this Topical Guide, first look down its table of contents immediately below to find the link to the appropriate topic; this will either take you to a brief discussion pointing you to the relevant part of this manual, or (where more appropriate) directly to the relevant manual chapter. If that fails to help you locate what you're looking for, you could try using your brower's search function (quite likely triggered by CTRL-F) to search on a term you hope will take you to the topic you want.

## Contents

1. Creating a New Game
2. Laying out the Map
   - Rooms and Regions
   - Directions
   - Connectors and Barriers
   - Doors, Passages and Stairs
   - Pathfinding
   - Room Descriptions
3. Populating the Map

- Basic Portable Objects - Things
- Vocab (how to use the vocab property on Things)
- Containment and Containers
- Fixtures, Fittings and Furniture
- Locks and Keys
- Gadgets, Controls and Devices
- Vehicles and PushTravelers
- Attachables and Attachments
- Unthings and MinorItems
- CollectiveGroups and Collectives

4. Senses, Sensing and Sensory Connections

- Senses in Adv3Lite
- Sensory Scope and Sensory Connections
- Reachability
- Light and Darkness

5. Time

- The Passage of Time
- Scenes
- Events — Fuses, Daemons etc.

6. Other Abstract Entities

- Topics
- TopicEntries
- Thoughts
- Knowledge
- Facts

7. Commands and Actions

- Overview
- Tweaking the Player's Input — Preparsing and SpecialVerbs
- Influencing the Parser's Choice of Objects
- Doers
- Customizing Action Messages (i.e. Textual Responses)
- Customising the Results of Actions
- Synthesizing or Redirecting Actions
- Dealing with Vague or Incomplete Commands
- Defining New Actions
- Literal and Numeric Actions
- Topic Actions
- Reacting to Actions
- Implicit Actions
- Debugging Commands
- List of Commands, Actions and Related Thing Properties

8. Non-Player Characters (NPCs)

- Overview
- Actors and Actor States
- Actor Agendas
- Conversation
- Giving Orders to NPCs
- Following NPCs
- Moods and Stances
- String Tags and Object Tags

9. Beginnings and Endings

- Start of Play
- Ending the Game

10. Helping the Player

- Hints (requested by the player)
- Extra Hints (offered by the game)
- Instructions on Playing Interactive Fiction
- Help for New Players
- Additional Hand-holding for New Players (The Command Help Extension)
- Pathfinding

11. Miscellany

- Banner Windows
- Changing the Player Character to another Actor
- EventLists
- Examples and Exercises
- Extensions
- Lists and Listers
- Macros
- Menus
- Output and Input Issues
- Scoring
- Typographical Quotation Marks
- Utility Functions
- Web User Interface

12. The TADS3 Language

- System Manual
- Object Definitions
- Expressions and Operators
- Procedural Code
- List
- String

## Creating a new Game

To start a new game you need to create a new source file, that defines a gameMain object, a versionInfo object, a starting location, and the player character. You also need to ensure you include the adv3Lite library and the appropriate header files. This is all explained in the section on Starting Out. You may wish to pay particular attention to some further considerations on defining the Player Character.
Back to top

## Laying out the Map

For an example of defining a map, see the sample game Exercise 11.

### Rooms and Regions

At a minimum, laying out the map involves the creation of one or more Rooms. Rooms can be grouped in Regions, which are allowed to overlap. Normally, once defined in your game, the list of rooms making up a region cannot be changed during the course of play. If you need regions that can change, you can use the Dynamic Region extension. A Room is normally a discrete unit of space, isolated from other rooms (apart from the possibility of travelling to them). To establish sensory connections (sight, sound and smell) between rooms you can use a SenseRegion

Rooms come with a floor object provided by default. If you want your rooms also to have a ceiling and walls you can use the Room Parts extension.

### Directions

If your game contains more than one room, you will need to define connections between the different rooms to allow travel between them. The simplest method is to connect rooms direcly to each other according to their direction from each other. The directions defined by the library are the eight compass directions (north, northeast, eaat, etc.), the four shipboard directions (port, starboard, fore and aft), and the special directions in, out, up, down. In any room you can specify whether compass directions or shipboard directions are allowed. You can also define additional directions (e.g., northnortheast, or left and right) if you need them in your game.

### Connectors and Barriers

While travel connections can be made directly between rooms, they can also be made via various kinds of TravelConnector. In addition to providing travel connections between locations, TravelConnectors can carry out the side-effects of travel, such as displaying a message describing it, or impose conditional barriers to travel. The base TravelConnector is one way (RoomA to RoomB but not back) but there is also a two-way DSTravelConnector. Various types of physical travel connector are described immediately below.

### Doors, Passages and Stairs

Doors, passages and stairs are types of TravelConnector that have physical presence in the game world.

A Door can be open and closed, and optionally lockable, with or without a matching Key. If the two sides of a door are substantially different you can define the two sides of the door using a linked pair of Door objects. If they are reasonably similar you can define the door as a single DSDoor object. A SecretDoor is a Door that only acts like a Door when it's open. When it's closed it's either totally invisible, or it appears to be something else, such as a bookcase or a panel.

Passage represents a physical object (such as a passage, corridor or archway) through which an actor must pass to get from one location to another. A PathPassage is a special kind of Passage that can be used to implement something like a path, track or road that a playey might try to FOLLOW, or GO DOWN or TAKE as synonyms for going through. A stairway is something the player character can go up (StairwayUp) or down (StairwayDown), typically a flight of stairs but also any other climbable object such as a mast, tree or hillside.

Like doors, the Passage, PathPassage and StairwayUp/Stairway down classes define only one side of the travel connection. For their two-way equivalents use the DSPassage, DSPathPassage and DSStairway classess. While all these classes implement two-way connections, they don't automate the connection back (for example, if you define the east property of the hall as pointing to a DSDoor that leads to the study, you still have to define the west property of the study as pointing to the same DSDoor. If you want two-way connectors that automate the setting up of reverse connections, you can use the SymConnector extension.

An Enterable is a fixture representing an object that can be entered, such as a house, hut or forest. The library mostly takes care of any pathfinding issues (the use of the GO TO command to navigate round the map) issues that might otherwise arise with Enterables that share a name with the location to which they lead.

### Pathfinding

Adv3Lite provides pathfinding as standard in the main library. This enables the player/player character to travel round the map using the GO TO command (provided the player character has already traversed the route). Pathfinding can also be used to control the movement of NPCs (non-player characters).

### Room Descriptions

The basic description of a Room is defined on its desc property. The roomFirstDesc property can be used to describe a room for the first time, and darkDesc to describe it in the absence of light. Although not strictly part of the business of laying out the map, now might be a convenient point to mention that several ways exist to customize how the contents of rooms are described. If two or more rooms are in the same SenseRegion you can also customize how item are listed and described remotely.
Back to top.

## Populating the Map

### Portable Objects - Things

All physical objects (including rooms) defined in an Adv3Lite game are either a Thing or of class that descends from Thing.

The basic properties you need to define for a Thing in adv3Lite are its name, the vocabulary used to describe it, and its description. You may also need to attend to some of the broadly name-related properties that can affect how a Thing is referred to or how it's selected by the parser (although the most commonly used of these can be defined through the vocab property).

The vocabulary (which defines how the player can refer to the object) is defined on the vocab property. Although this normally remains fixed during the course of play, there are ways of changing it during a game. More control over what is matched by a Thing's vocab (e.g. to distinguish the green bottle from the dark green bottle, or the broad green bean from the green broad bean, when one set of words is a subset of the other or the same words are used but in a different order), you can use Phrase Matching.

By default all objects defined with the base Thing class are portable (that is, they can be picked up and carried around by the player character and other actors in the game). This can be changed by overriding isFixed to true on the Thing in question but is more usual to use one of the Fixture classes discussed below.

### Containment and Containers

The containment model allows things to be put in, on, under, or behind under things. This can be defined using various containment properties on Thing. The type of containment can be defined using the contType property, but is more usually dealt with by using one of the Container sublasses of Thing.

How much can be put in, on, under, or behind something is usually controlled by the bulk and bulkCapacity properties of the objects concerned. If you also want to model weight and weight capacity, this can be done using the weight extension.

If you want your container to have door (a cupboard door or safe door, for example), you can use the ContainerDoor class to implement it.

If you simply want to hide things in, under, and behind other things that wouldn't normally contain them, you can do so using the properties hiddenIn, hiddenUnder and hiddenBehind.

With that exception, each Thing can normally only implement one kind of containment (in or on or under or behind); you can, however, model multiple types of containing on the same object by using the remapXXX properties.

You can test for containment (what's in what and what contains what) using the relevant properties of Thing.

Usually (as you might expect), objects can only be in one place at a time — only one object can contain them at a time. You can however use the MultiLoc class to create objects that are in several places (usually rooms) at once. This can be useful for objects on the border of two different rooms, or for distant objects like the sun that are visible from multiple locations, or effectively identical decorations that occur across several rooms, such as trees in a forest.

For a short sample game illustrating various types of container see the Kitchen sample game.
Back to top

### Fixtures, Fittings, and Furniture

Non-portable items are usually defined using the Fixture class, or its close relative, the Heavy class, the former being used for items that are fixed in place and the latter for those that are too heavy to lift.

Your game may contain a number of objects referred to in room descriptions, or in descrptions of other objects, or simply likely to be present (the sky in an outdoor location or trees in a forest) which the player may try to refer to but doesn't in fact need to interact with. These can be implemented using the Decoration class or its subclass Distant (used to model objects that are too far away for the player character to do anything but look at. These are normally very simple objects but you may occasionally want to apply some customization. By default the only commands Decoration objects respond to beyond saying "The whatever is not important" are EXAMINE and GOTO, but you can vary this in their decorationActions property. You may also want to tweak whether or not Decorations (or indeed other objects) are included in the list of objects acted on when the player types a command acting on ALL (e.g., EXAMINE ALL or TAKE ALL). This can be done with the hideFromAll() method.

If your game contains a lot of decorations, you can create set of decoration objects more succinctly using the Scenery class.

An Enterable is a fixture representing an object that can be entered, such as a house, hut or forest. The library mostly takes care of any pathfinding issues (the use of the GO TO command to navigate round the map) issues that might otherwise arise with Enterables that share a name with the location to which they lead.

Furniture (not least in the sense of things that the player character can get in or on) may or may not be fixed-in-place or too heavy to lift (it may often be, but some chairs could be readily portable, for instance). If the player is meant to be able to get in or on a piece of furniture it will need to be defined as a Booth or a Platform. You may then wish to define the reachability behaviour of such objects (controlling whether an actor located in a Booth or Platform can reach an object located outside it and whether and under what conditions one can reach an object or its contents). Adv3Lite does not keep track of actors' postures (standing, sitting, or lying), unless you include the postures extension, but does provide pseudo-postural properties that let you define which objects can be sat on, stood on, or laid on.

For an example of a sample game demonstrating various types of furniture and reachability, see the Bedsitterland sample game.

Back to top.

### Locks and Keys

Doors and Containers may be made lockable by defining their lockability property. If a door or container is defined to be lockableWithKey, it is likely to require one or more matching keys. You can use the KeyedContainer class to define an OpenableContainer that can be locked or unlocked with a key. See Exercise 19 for a brief example game implementing various kinds of lock.

### Gadgets, Controls and Devices

The adv3Lite library defines a number of controls and gadgets that can be used for a variety of purposes, including Button, Lever, Settables and Dials, Switch and Flashlight, the last of which being any kind of light source that can be turned on and off, but never runs out of fuel or battery power. To implement a Flashlight or other device that can run out of power you can use the FueledLightSource mix-in class from the Fueled Light Source extension. Exercise 19 also contains examples of many of these classes in the context of a small sample game.

For a computer the player character can look things up on (or book to look things up in) you can use the Consultable class (together with associated TopicEntries). For a mobile phone or computer with video chat software that can be used for the player character to talk to actors in remote locations, you can use commLink. For a CCTV or window overlooking a remote location, you can use the Viewport extension.

### Vehicles and PushTravelers

A Vehicle is an object that an actor get in or on and which then moves around carrying the actor in response to movement commands (such as GO NORTH). To create a vehicle, first define an object of the Booth or Platform class and the set its isVehicle property to true.

A PushTraveler is an object that can be pushed or pulled from place to place. To create a PushTraveler create an object of the appropiate class, such as Heavy, and set its canPushTravel to true.

The sample game Exercise 11 contains examples of both a vehicle (a bike) and a PushTraveler (a trolley).

### Attachables and Attachments

An Attachable is something that can be attached to something else or have other things attached to it, in either case with the possibility that the objects might become detached again at some point. For something that's permamently attached to its parent object, it's usually better to use the Component class. For examples of Attachables see the Attachment sample game.

### Unthings and MinorItems

An Unthing can be used to report the absence of something, either something that's just been reported as leaving the area or going missing (like a key dropped down the drain or a ship that's just sailed out of sight), or possibly something that the player might expect to be there but it isn't (the moon when it's new on a cloudy night, for instance).

A MinorItem is an unobtrusive and possibly unimportant portable object (minor item) that's worth implementing in the game but sufficiently minor as to be not worth mentioning in response to X or FOO ALL unless it's either directly held by the player character or directly in the enclosing room or directly in the actor's location. Note that this is different from a Decoration, which is normally fixed in place and can only be examined.

### CollectiveGroups and Collectives

A CollectiveGroup can be used to represent a collection of objects for certain actions (usually just examined), such as a row of buttons or bank of switches, each of which is implemented separately, but which you'd like to summarize into a single description in response to X BUTTONS or X SWITCHES. The CollectiveGroup class should only be used for things that are fixed in place. For a portable collective group use the MobileCollectiveGroup extension.

A Collective, on the other hand, means one object (such as a bunch of grapes) from which you might take one or more individual objects (in this case, grapes), which could lead to all sorts of disambiguation issues. For this situation you can use the Collective and or DispensingCollective class implemented in the Collective extension.

Back to top

## Senses, Sensing, and Sensory Connections

### Senses in Adv3Lite

AdvLite makes provision for five senses: sight, sound, smell, taste and touch, with by far the bulk of the attention given to the first of these. At the most basic, the other four are catered for through the Sensory Properties of the Thing class (and hence all its descendent classes), which provide simple responses to LISTEN TO, SMELL, TASTE or TOUCH whatever.

The standard library also provides basic Sensory Emanation Classes called Noise and Odor to represented sounds and smells. If your game needs a more sophisticated handling of sounds and smells than these classes offer, you may want to consider including the Sensory extension.

### Sensory Scope and Sensory Connections

By default, the player character can only sense what is in the same room in which he/she/it is currently located. In addition, the player character cannot see through a closed container, unless it has been declared to be transparent (by defining isTransparent=true on the container).

To determine what objects can be sensed (seen, heard, smelt, or touched) by another you can use the relevant sensory methods on Thing (canSee(obj), canHear(obj), canSmell(obj), canTouch(obj)), or, of course, on any subclass of Thing, such as an actor or the player character. This should suffice for most purposes, but if you need to customise the behaviour of these methods, you need to know that they work by calling the corresponding methods of the Q object (so called because it's used to answer question about the game state), which in turn farms them out to the relevant Special. You can need to define your own Special to adjust the library's normal behaviour, perhaps under special conditions.

For adjusting definitions and behaviour of reachability/touchability (what the player character or another actor can touch), including customizing the failure message shown when touch is ruled out, you may need to pay attention to issues concerning the interaction of Specials and the touchObj precondition

The Q object (and hence the currently active Special) also defines what is currently in Scope. There are various ways of changing what's in scope.

To allow the player character (and other actors) to see, hear and smell objects in neighbouring location, the rooms need to be grouped together in a SenseRegion. This class also lets you control what can be perceived through which sense and how it is to be described from a remote point of view.

For a mobile phone or computer that can be used for the player character to talk to (or videoconference with) actors in remote locations, you can use commLink. For a CCTV or window overlooking a remote location, you can use the Viewport extension.

The sample game Sense and Sensibility contains a number of examples of senses, sensing and sense regions.

### Reachability

Reachability concerns which objects an actor can reach (to touch or otherwise physically handle). By default all objects in the actor's current room are reachable unless they are in a closed container. Reachability is only enforced for actions that require the touchObj precondition.

Reachability can be controlled in a number of ways. For most cases you would use one or more of the reachability methods: checkReach(actor), checkReachIn(actor, target?), allowReachOut(obj) and autoGetOutToReach.

To determine what objects can be reached/touched by another you can use the relevant canTouch(obj) method on Thing or any of its subclasses. This method calls the corresponding method on the Q object , which in turn farms them out to the relevant Special. You can need to define your own Special to adjust the library's normal behaviour, perhaps under special conditions.

To customize the failure message shown when touch is ruled out, you may need to pay attention to issues concerning the interaction of Specials and the touchObj precondition

### Light and Darkness

In adv3Lite rooms are either light (isLit = true) or dark (isLit = nil). An object can also be made into a light source by defining or changing its isLit property to true. If the room or any visible object in the room is lit, then everything in the room can be seen and described (provided it's not hidden in a closed container or the like). If the room is dark and there is no light source, then by default nothing can be seen at all.

Adv3Lite also has some provision for semi-darkness. A room that is in near-darkness might still have some barely discernible features; the room class provides a number of properties that can be used to define what the room is called and how it is described in the dark, and what happens when the player character attempts travel in the dark, along with methods to test whether the room is illuminated. The Thing class provides a pair of properties for items that might be dimly discerned in a dark room: visibleInDark and inDarkDesc.

If you need to model a greater range of light levels than this (total darkness, near total darkness, and full light) you can use the Brightness extension, which you can use to implement as many different lighting levels as you like.

To provide lightsources in your game, you can create objects whose isLit property is always or conditionally true. For a switchable light source use the Flashlight class, which implements any kind of light source that can be turned on and off, but never runs out of fuel or battery power. To implement a Flashlight or other device that can run out of power you can use the FueledLightSource mix-in class from the Fueled Light Source extension. Light Sources is a small sample game that contains examples of several of these classes along with a number of dark locations.

Back to top

## Time

### The Passage of Time

The basic measure of the passage of time in an Adv3Lite game is the number of turns. To get at the current turn count you can use the macro gTurns.

If you wish to keep track of clock time (date and/or time of day) in your game you can use either the Objective Time extension or the Subjective Time extension. The former allows you to advance the clock each turn (by whatever amount you like); the latter lets you specify the time at which certain points in your game are reached and interpolates between them.

### Scenes

Scenes can be use to define spans of time in your game during which special conditions may obtain or simply as a way of keeping track of significant plot developments or game/story states. A Scene is mainly a way of checking whether a particular phase of your interactive story is currently in progress or has already occurred, and can be used to control how other aspects of the game work

### Events — Fuses, Daemons etc.

To make something occur once in the future (a certain number of turns time), you can use a Fuse. To make something happen each turn, or every so many turns, use a Daemon.

For examples of Fuses and Daemons see the listing of the Bomb Disposal sample game.

To create a sensory event (a sound, smell or visible occurrence) that actors or other objects can be programmed to react to, you can use the Sensory extension to set up a SensoryEvent.

To set up a sequence of events occuring in sequential or random order you can use an EventList. For some examples of this see the sample game An Eventful Walk.

Back to top

## Other Abstract Entities

### Topics

A Topic is something that might be referred to in your game (such as the weather or Julius Caeser) that is not implemented as a physical object in your game. This allows you do deal with commands such as LOOK UP JULIUS CAESAR IN HISTORY TEXTBOOK or ASK MAVIS ABOUT THE WEATHER.

### Topic Entries

A TopicEntry is an object that encapsulates the response to looking up, talking about, or thinking about a particular topic.

### Thoughts

A Thought is an object that can be used to implement responses to commands like THING ABOUT AUNT MAVIS.

### Knowledge

Knowledge in adv3Lite can be knowledge of the existence of an object or topic (tested by the actor's knowsAbout(obj) method) or knowledge of a fact revealed of a fact that's been revealed (typically through a <.revealed> or <.informed> tag. Both types of knowledge can effect which topics are reachable in conversation. The Thing class defines a number of properties and methods relating to knowledge. There is also a Fact class that extends the functionality of <.revealed> or <.informed> tags to enable facts to be listed in response to queries and keep track of who imparted various facts to the player character, and a Fact Relations extension that uses relations to extend what can be done with Facts.

Back to top

## Commands and Actions

### Overview

A command is something entered by the player at the command prompt, e.g. LOOK, EXAMINE THE COIN, or PUT THE POTATO IN POT. The parser does its best to interpret this command and stores the result in a Command object. This is then passed to a Doer, which normally passes the command straight on to the appropriate Action for handling, but you can if you wish intervene at this point by providing a custom Doer. For an action that involves no physical objects (i.e. Things) the action is then handled entirely on the relevant Action object (for the various action types see the taxonomy of actions). Otherwise it is handled on the direct and indirect (if any) objects of the command. For a fuller account of the action cycle see here.

To rule out an action because the player character is incapacitated in some way (e.g., tied up, bound and gagged or paralysed) you can use either the actorAction() method or the preAction(lst) method (depending on at what stage you wish the action to be stopped).

To see which commands trigger which actions, consult the Action Reference

### Preparsing

To (if you wish, conditionally) alter the text of the player's command before the parser attempts to interpret it, you can use a StringPreParser

If your aim is to change what the player typed from one command to another command to meet special circumstances (e.g. you want RING BELL to mean PUSH BELL when the bell is the only object to which RING would apply in your game, you can use a SpecialVerb.

### Influencing the Parser's Choice of Objects

The parser will attempt to choose the direct and indirect objects (if any) of the command by finding the best match with the player's input. You can influence the parser's choice in a number of ways: adjusting scope, using the filterResolvedList method to tweak the list of candidate objects the parser is choosing between, adjusting the vocabLikelihood property or more of Things potentially involved, defining matchPhrases on them, and, probably most commonly of all, using/defining/overriding the appropriate verify methods.

### Customizing Action Messages (i.e. Textual Responses)

If all you want to customize is the textual output of an action (e.g., "You really can\'t do that with the sky" in response to PUSH SKY or "You put the vase down very carefully" in response to DROP VASE, it may just be a matter of overriding the appropriate message property on the object concerned. You can look up the name of the message properties associated with various actions in the Action Reference.

For a fuller account of action messages, including the use of the BMsg() and DMsg() functions and Message Substitution Parameters, see the chapter on Messages.

### Customising the Results of Actions

Sometimes, customising the result of an action can be as simple as overriding the appropriate property such as (canSitOnMe or lookThroughMsg) on Thing or the subclass or object(s) in question. Some of these behavioural properties are documented in the chapter on the Thing class. A fuller list is provided in the Action Reference.

Anything more sophisticated will require overriding the execAction() method of any Action not involving a Thing as one of its objects, or one or more of the verify, preCond, Check, Action, Report, or Remap stages on the class or object in question. For the full story, see the chapter on Action Results. In some cases, you may prefer to use a Doer.

### Synthesizing or Redirecting Actions

The best way to redirect one action to another is to call the doNested() or doInstead() method on a Doer or in the Action section of a dobjFor(Whatever) block. There are also replaceAction() and nestedAction() macros, but these do not work so well if any of the objects involved in the new action is a Topic or a Literal, so it is recommended to use doNested() or doInstead() wherever possible (which is likely to be anywhere it's useful to do so).

To synthesize an action to be carried out by an actor other that the player character you will need to use nestedActorAction() or replaceActorAction(), e.g. nestedActorAction(bob, Jump) or replaceActorAction(bob, Take, pen) or replaceActorAction(bob, putOn, pen, desk). This can only be used with IActions, TActions or TIActions (i.e., actions that don't involve Topics or Literals).

## Dealing with Vague or Incomplete Commands

To handle a command that's vague or incomplete, such as ATTACK BLACK KNIGHT when attacking the black knight needs a weapon (e.g. ATTACK BLACK KNIGHT WITH SWORD) or WRITE without specifiying what it is to be written (although the second of these cases is handled by the library), you can use one of askForDobj(action), askForIobj(action) or askMissingLiteral(action, role).
Back to top

## Non-Player Characters (NPCs)

### Overview

A Non-Player Character (NPC) is any character than appears in your game other than your protagonist (or Player Character). Some NPCs may be so simple with such a restricted range of actions (like a guard or troll that does nothing but block a bridge until the player finds a way to remove them) that they could probably be implemented just with an object of the Immovable class. Here we are concerned with more sophisticated NPCs who can respond to conversational commands, and perhaps also move around the map and perform other actions under their own initiative. Such NPCs are normally implemented using the Actor class together with a number of supplementary objects located within the Actor.

If you need to, you can track what various NPCs know (and believe), and/or their current mood and/or stance towards the player character and other NPCs (their stance being how positively or negatively they feel towards the player character and, if you wish also to track it, towards other NPCS).

For illustrations of NPCs in a sample game, see the Lighthouse listing.

### Actors and Actor States

At the very least, an NPC needs to be defined as an object of the Actor class. Many actors may change their state (e.g., from attending to their own business to conversing with the Player Character), in which case the ways in which they are described and respond will often change accordingly. This can best be modelled through ActorStates

### Conversation

Conversation between the player character and NPCs is handled through ActorTopicEntries, which can be located in Actors, ActorStates or TopicGroups. These can be used to implement a basic ask/tell system (responding to commands like ASK FRED ABOUT THE TOWER or TELL MAVIS ABOUT YOURSELF), which can optionally be extended (in your game) in various ways. First, you can suggest topics of conversation to the player (as and when you see fit). Second you can implement more complex conversational exchanges through the use of SpecialTopics such as QueryTopics (which let the player ask questions like ASK WHY/HOW/WHEN/IF/WHO WHATEVER) and SayTopics, which let the player say virtually anything you define to an NPC. And third, you can locate certain TopicEntries within Conversation Nodes, which model points in the conversation (such as when the NPC has just asked a question) at which a limited range of responses may be apposite and their significance (e.g., what the player may be answering YES or NO to) highly context-dependent.

You can also, if you wish, implement greeting protocols (starting and ending conversations with hello and goodbye or whatever other greeting and farewell reponses you wish). You can also decide when a conversation is allowed to end.

There are a number of ways in which you can have an NPC initiate a conversation or seize the conversational initiative.

There is also a Fact class that extends the functionality of <.revealed> or <.informed> tags, which are often used in conversation. This functionality can be further advanced with with aid of the Fact Relations extension, for example to enable NPCs to steer conversations towards desired goals.

For a more basic conversation system that could be used for very simple NPCs see the oracle example that could be implemented in adv3Liter .

### Following NPCs

To have an NPC start or stope following the player character around, calls its startFollowing() or stopFollowing method.

To set up a situation in which the player character can follow an NPC (who leads the way but waits for the player character to follow), use a FollowAgendaItem.

Back to top

## Beginnings and Endings

### Start of Play

If you want to display introductory text you'd normally do this in gameMain.showIntro(). The same method can be used to start up any Fuses or Daemons you may want to be active from the start of play, or to display a menu of options to the player or request player input. Alternatively, you could use one or more for some of these tasks.

For other initialization tasks, such as performing initial calculations and setting up data structures, you probably want to use PreinitObjects.

InitObject and PreinitObject are part of the system library (rather than adv3Lite) and you can read about them in the "Program Initialization" section of the TADS 3 System Manual.

You may also want to implement an About Box for your game, using gameMain.setAboutBox() to set it up and gameMain.showAboutBox() to display it.

Back to top

adv3Lite Library Manual
Table of Contents | Final Moves > Task Topical Guide
Prev: Alphabetical Index