Printing Text

The printing of text is surprisingly complex as we need to be able to wait, handle fancy text effects and allow for player input (outside the normal command prompt). Details can be found here, though generally you will not have to worry about that!

The msg functions

There are various output functions, falling into two categories. The msg function is the basic one, and will be used most often. Besides that there are various options for displaying different HTML elements. Then there are variations for different types of messages.

All of these work by creating an HTML string (most after the text processor has done its thing), then submitting that string to the output queue.

function msg(s, params, cssClass)

Print out the given text. The params and cssClass are optional (and cssClass is not used if the typewriter effect is active), so just as with Quest 5 you can do:

msg("There is a strange tree here.")

Multi-line

You can print multiple lines as once by using a vertical bar as a separator. This is useful if you want a description to be more than one paragraph, but prefer to use a string than a function. This example will print out the two sentences in separate paragraphs.

msg("There is a strange tree here.|You also see an odd flower.")

If you want a vertical bar in your output text, use the special escape code @@@vert@@@.

Text processor directives cannot straddle line breaks. The msg function will break your string up first, and then apply the text processor to each line, so each line has to stand on its own (more here).

Long dash

If you set settings.convertDoubleDash to true, Quest will convert any pairs of dashes to a single long dash (with the HTML code 'mdash'; looks like this —), as long as they have a space on either side.

CSS Class

The CSS class allows you to set the CSS class for this paragraph, allowing you to change all the styling for this paragraph as required. The class should be defined in your CSS file, which is discussed here.

Headings

If the text starts with a hash and has no CSS class set, it will be printed as a level 4 title, with the hash removed. This is most useful in room templates, as it gives a way to make the room name a heading. Effectively it does this:

msg('#The Lounge')
msg('A wonderful, cosy room.')

Params and the text processor

The "params" is a dictionary that will be passed to the text processor. In this example, the variable "char" is passed to the text processor, with the key "actor". The directive will use that to produce a noun-verb pair, together with the verb "to be", and capitalised.

msg("{nv:actor:be:true} here.", {actor:char})

If "char" is set to an object with the alias "shoes", the player will see "The shoes are here."

For more on how you can use that, see here.

CSS class

To add a certain CSS class to the entire text, add that as a string as a third parameter. If you are not using text processor paramters, just use an empty dictionary as the second parameter.

msg('string to show', {}, 'cssClassUsed')

If you want to use multiple classes they can be included in the string, separated by spaces.

There is more on CSS here. If you want just a section of text to have a CSS class, use the text processor.

Different HTML Options

Everything you see on a web page is contained in HTML elements. Different types of elements display in their own way, and Quest has various functions to use them. These all take an optional "params" parameter, just as msg does. During testing, these are neither printed or saved.

function msgList(arr, ordered, params)

Print out the given text, which should be an array of strings, as an HTML list, either ordered (i.e., each entry is numbered) or unordered (with bullet points).

function msgTable(arr, headings, params)

Print out the given text, which should be an array of arrays of strings, as an HTML list. The second parameter is optional, if supplied it should be an array of strings to use as headings.

function msgHeading(s, level, params)

Print out the given text as a heading. Note that the text must have a number after it, indicating the types of heading, from 1 (highest) to 6 (lowest). This uses the standard H1 to H6 HTML headings. Quest uses H2 for the title of your game, and H4 for the room names.

function msgDiv(arr, params, cssClass)

Print out the given text, which should be an array of strings, inside an HTML div. The params will be passed to the text processor. You can use the cssClass to format a group of paragraphs (which you format in the styles.css file). Perhaps the player has picked up a piece of paper; you could put the text in a fancy font, with a border around it.

Different contexts

These reflect the different types of messages to display. If you prefer to have a single, uniform style, you can modify styles.css. Personally, I think this is a good way to tell the player something has gone wrong, or the message is out of the game world or whatever.

function failedmsg(s, params)

function falsemsg(s, params)

Print out the given text, using the class "failed", allowing you to differentiate between a successful command and a failed command (one the parser understood but that did not work because of the player's situation).

Exactly what counts as a failure is debatable, and most text adventures do not bother to differentiate; if that is your choice, just omit the "failed" class from the styles.css file.

The params is optional and will be passed to the text processor.

The functions return FAILED and false respectively. This allows a one liners like this, where we test the condition for a command, print a message and return a value all in one go.

  if (!container.container) return failedmsg(NOT_CONTAINER(char, container));

function metamsg(s, params)

Print out the given text. This should be used for messages to the player about the game, rather than about the game world, for example in response to HELP. The params will be passed to the text processor.

function errormsg(s)

Print out the given text. This should be used for error messages that indicate a bug. If your game is free of bugs, the player will never see this.

Does not use the text processor (as the bug might be in the text processor itself!).

function parsermsg(s)

Print out the given text. This should be used for messages that indicate the parser has failed to understand what the player is typing.

function debugmsg(s)

Print out the given text. This should be used for debugging messages when trying to work out why something is not working as it should, and will not be printed if settings.debug is false.

Does not use the text processor.

Arguably, you are better off using the built-in console.log command, which prints in the console (press F12 to see), as it will show objects and arrays nicely, and the line number.

The messaging subsystem

Processing

All messages that go via _msg (which includes msg) first go through the text processor, then get split into paragraphs and then escape codes are replaced. The results strings are then passed to the queue.

The Queue

With the exception of errormsg and debugmsg, all the above functions send their resultant HTML string to io.addToOutputQueue via _msg, where it is put in a dictionary and added to the queue. Other items can appear in the queue; for example, the wait function will add an item.

Items are removed from the queue in the order they were added. Text entries are just printed, and other entries can force the game to wait. What this means is that calling wait will stop all subsequent output until the player clicks "Continue".

Let us see that in action. When your games starts, Quest will run the settings.setup function, if it exists. We can use that to add some introductory text.

settings.setup = function() {
  msg("Welcome to the Citadel of Culinary Horrors!")
  wait()
  msg("Do you dare venture within?")
  wait()
}

Quest will run the function, adding four events to the output queue, two texts and two waits, then will do the normal actions for the room, perhaps adding a description and a list of exits to the queue.

However, only the first line of text will get printed, before the queue gets to the first "wait". The player clicks continue, and the output resumes... until the next wait.

You can use wait with a parameter to have it pause for a few seconds. In this example, the player does not have to click anything, the new text will appear after a 5 second pause (you can also add a string as a second parameter telling the player to wait; it will disappear at the end of that time).

settings.setup = function() {
  msg("Welcome to the Citadel of Culinary Horrors!")
  wait(5)
  msg("Do you dare venture within?")
  wait(5)
}

You can use _msg to add your own items to the print queue, and the time you are most likely to want to do that is with special text effects.