Conversation Builder by Chris Conley

Conversation Builder interactively drafts source code for use with the Threaded Conversation extension.

Chapter: Getting Started

NOTE to new users: This documentation assumes some familiarity with the workings of the Threaded Conversation extension -- please begin reading there!

Section: Quick Start Instructions

We begin by downloading and installing the Threaded Conversation extension from the Inform website, if we don't already have it installed. Conversation Builder depends on this. (And Conversation Framework by Eric Eve. Threaded Conversation also depends on that extension.)

We must also make sure that the Settings tab is set to compile to Glulx.

We may then begin with as little as a room and a character, such as

Include Conversation Builder by Chris Conley.

The Raven Tower is a room. The King is a man in the Raven Tower.

Once these are defined, we can begin with

>talk to king

and then a question or comment such as

>ask king whether he plans for war
>persuade king to make peace treaty
>say I represent the Ooambu tribe

CB will then invite us to answer a series of questions to define the new piece of conversation, or "quip".

We can repeat this process as much as we'd like; when we've written all the conversation we want to write on this iteration, we can quit, whereupon CB will print out the generated source.

We now copy the generated source from the game window; paste it into the source window (ideally in a special section of the code devoted to conversation quips and appearing towards the end of the game); make any editing touches we want (such as correcting typos); and re-compile the game.

If the newly compiled game starts with such feedback as

peace treaty is a subject.
Ooambu tribe is a subject.

we should copy these lines into the part of the source where we list subjects of conversation (ideally, these should appear before the quips are defined). This is also a good time to add alternative names to the new subjects, such as

Understand "accord" or "agreement" as peace treaty.

Then re-compile again.

When the new conversation compiles and produces no header warnings, it is safely incorporated into the game, and we can begin this process again.

Chapter: Detailed Overview

Conversation Builder is designed to generate source code for the Threaded Conversation extension. It is possible to write Threaded Conversation code by hand, of course; CB is chiefly intended to automate the more repetitive aspects of writing a sizable conversation; to produce source that is uniformly organized and easy to read (more of a factor when there is a large amount of data); and to avoid certain easily-avoided bugs and flaws by escaping object names that are likely to cause namespace clashes in Inform.

Section: Making a new quip

If we have Conversation Builder running, the game will detect when the player/author attempts to ask a question or make a remark that is not currently implemented. It also, rather ambitiously, assumes that all input it can't interpret at all -- anything generating a parser error -- is an attempt to use a performative quip, like "apologize to Fred" or "cheer Lily up".

For simplicity, the CB limits its syntax to three simple commands when generating new quips:

ASK { a new intended questioning quip's name }
TELL { a new intended informative quip's name }
{ a new intended performative quip's name }

When this happens, CB will create a new quip, escaping any instances of "with", "is", "are", "have", or "has" that might cause compilation problems in the finished source. Under most circumstances we can ignore this behavior entirely, but for more information see ESCAPING NAMES below.

Section: Adding items mentioned

Next, CB will prompt the player to list things mentioned by this quip.

As a rule, quips about objects or people in the game should mention those objects or people. This will ensure that the quip parses all of the viable names for those items, without our having to specifically type out all the alternatives. In fact, a good rule of thumb is to have a quip 'mention' something for every noun that appears in the quip -- whether those are in-game things like people, or subjects like "peace" or "freedom". This vastly simplifies the problem of making our conversation parse smoothly and consistently with the rest of the model world.

CB will also provide a list of subjects that are already defined, to jog our memory.

Section: Writing comment and reply properties

Now CB will ask for a comment and reply appropriate to this quip. Because pressing return will indicate the end of a comment or reply, we should use the "[paragraph break]" substitution if we want to introduce additional lines of spacing into the middle of one of these fields. A maximum length of 3000 characters is set for comments and replies, as determined by the LARGE_BUFFER_LENGTH constant.

There is nothing to stop the author/player from using "[one of] ... [or] ... [or] ... [stopping]" and similar text variation effects when defining what the player will say or how the character will respond; similarly, facts can be indicated in brackets as usual, as in "The prince tells you his feet smell funny[funny-foot-smell].". If these are new facts not previously defined, they will fail to compile through when the code is pasted in, but the author can add the facts to his fact table and proceed as normal.

Similarly, new quips from other characters can be queued up using the "[queue {quip name}]" substitution defined in Threaded Conversation.

Comments and replies may safely be written with either single or double quotes; all double-quotes will be converted back to a single quote before being saved in the source.

Section: Conversation threading

CB will next ask the player/author a couple of questions about how the quip relates to the current conversation context. It is assumed that the player/author wants to add new material to the conversation that's currently in progress, so it's a good idea to invoke this ability when the conversation is already at the stage we want to add to.

New conversation may be set to follow whatever quip the game used last (the current quip) OR whichever quip we ourselves just defined. This means that we can define a whole thread of questions and answers in a single editing session, before dumping source and recompiling; but CB is not designed for more complex editing than this in a single session.

Section: output

CB will then write appropriate code out to a file called "NewConversation".

At the end of play, before quitting, CB will print to screen all the source code it has written over the course of the editing session. This source code also remains stored in the file "NewConversation". In builds of an Inform project, "NewConversation" will be inside the top-level Inform/Projects folder; if we are running the game on an independent interpreter, "NewConversation" will appear in the same directory with the game file. We may also bring up this code mid-play by typing

SHOW SOURCE

To compile this code into the next session, we simply cut and paste it over to the appropriate place in the source window. This tends to work most effectively on a relatively short play-build-play cycle: we play the game for a bit, add five or ten new quips at various points in the conversation, then play again.

Conversation Builder assumes a certain amount of astuteness from the user. It is conceivable that if we have given a question a name that clashes with an existing quip, compilation will fail and we will have to modify the source somewhat; but under many circumstances the results will simply compile and play. It is also up to the user to make sure that, for instance, the subjects mentioned by any given quip correspond to the source code as desired; Inform will create new subjects if a quip mentions something that isn't listed elsewhere in the code, but this also means that typos and misremembered names will generate spurious subjects rather than conforming to existing ones.

Chapter: Advanced Features

Section: Escaping names

As mentioned earlier, CB catches and changes instances of "is", "are", and some common relation verbs in the names of quips, because they almost always cause compilation errors: given a sentence such as

John is fat is a quip.

Inform will try to understand (John) is (fat is a quip), and have trouble because it doesn't know what "fat is a quip" might be. Other common verbs cause trouble as well.

Where these words occur, they will be replaced according to the Table of Quip-Name Conversions, of which a representative sample is

Table of Quip-Name Conversions

topic	replacement	understanding	used
"is"	"seems"	"is"	0
"are"	"seem"	"are"	0
"with"	"alongside"	"with"	0

(The actual table is some lines longer, drawn from experience with problematic quip names.) If we find that we are very frequently running into compilation problems with other words, we may continue this table with our own replacements.

The escaping is done by the quip-name-management rulebook; currently it contains only one rule,

the get rid of dangerous verbs rule

but if we want to, we may add further quip-name-management rules as well. For most purposes, adding to the Table of Quip-Name Conversions will be adequate, but if not, we can write our own free-form code.

Another table, the Table of Quip-Name Understandings, does not alter the name of the quip as we have typed it, but it does add additional understand rules to a quip; this guarantees that, for instance, any instance of "himself" or "herself" will also match the name of the current interlocutor; or that quips containing "you are..." will also recognize "I am...".

CB then generates Understand... and printed name... instructions so that the quip will be printed and understood exactly as the player/author typed it. A rule called

the add understanding individual verbs rule

uses the "understanding" column of the table of quip-name conversions to add additional synonyms to the quip.

CB also stores the source name of the quip in the "true-name" property; this allows future use of Conversation Builder to build code that correctly refers back to this quip.

If we want to mingle code built by CB with code written by hand, we must remember to always define a "true-name" for every hand-written quip whose printed name differs from its source name.

Section: Adding special features to the conversation

Conversation Builder does not attempt to handle very complicated situations: there are many cases for which we will want to write our own custom plausibility and availability rules, for instance. For any of the following tasks, we should consult the documentation for Threaded Conversation:

(1) restricting some quips to occur only during specific scenes; starting and ending scenes based on quip status
(2) building other, arbitrarily complex rules regarding which quips may be displayed under which circumstances
(3) changing the output format so that the game presents the player with a menu rather than conversation choices
(4) turning off or modifying the printing of cues such as "You could ask about the peace treaty."
(5) making characters provide atypical replies to a whole set of quips under special circumstances (e.g., having a character who gets angry and responds rudely everything the player says)

and, in general, if there are things that Conversation Builder does not explain, we should probably turn to the documentation for Threaded Conversation, and to its accompanying examples.

Chapter: Customizing Conversation Builder

Section: Customizing CB for our own use

When constructing quip code, Conversation Builder follows a rulebook called the quip-building rules. If we wish to construct our quips differently, we may add to, replace, or remove rules from this rulebook. The existing quip-building rules can serve as a guide for constructing additions.

We may also stop Conversation Builder from being quite so enthusiastic in interpreting any input as a performative quip by turning off

the read all performative quips rule

Section: Customizing CB for collaborative design projects

Some authors may wish to use Conversation Builder in collaborative design projects, by releasing a game that includes CB and encouraging players to submit files of new conversation, by using CB to involve a dialogue-writer who isn't otherwise involved in code development, or by inviting beta-testers to submit additional lines for the player.

It is likely, in that case, that a somewhat stripped version of the code-building would be desirable: one might, for instance, remove most of the rules from the quip-building rulebook and invite players simply to submit their suggested new questions and the line of dialogue they wanted the player to be able to say, leaving it up to the author to complete this with the character's reply and the more technical features of the quip.

One way to do this would be to add the following bit of code to the source:

The cut off quips rule is listed before the getting a reply rule in the quip-building rules.

This is the cut off quips rule:
     follow the finalize quip rule;
     say "[line break]Suggestion noted.";
     rule succeeds.

Similarly, by default, Conversation Builder will give the player a list of already-defined subjects, as a hint about what a new comment can safely 'mention'. We might want to suppress this in a game released to beta-testers or players, or we might simply find that the subject list is getting long and is more of a hindrance than a help. In that case, we may

Use suppressed subject list.

to omit the feature.

We might also want to skip having the generated source code appear every time the player quits the game; to do this, we would remove the check quitting rule that currently does this:

The show source before stopping rule is not listed in any rulebook.

Finally, when working on our own, we usually do not want the NewConversation file to grow longer and longer with each editing session; but if we are collecting feedback from others, we might want them to be able to accumulate a long file with the results of multiple sessions appended to it. To do this, we simply skip purging the NewConversation file when the game starts up, by declaring that

The clean conversation creation rule is not listed in any rulebook.

Chapter: Changelog

Section: Version 3

Removed;. from two lines, which was preventing compilation. Stricter parsing rules in 6M62?

Section: Version 2

Updated version dependency to require 6L02-compliant version of TC
Adapted to Inform 7 build 6L02