The Output Queue

Deciding when something should get written to the screen is not trivial. The author might want a pause of so many seconds or have the player click to continue. There are text effects that take time to complete. Sounds may need to be coordinated with that too. To handle all this, Quest 6 uses a queue. When the game determines something is to be written it gets added to the end of the queue. Meanwhile, Quest is pulling items from the start of the queue as required to show on the screen.

The io.addToOutputQueue(data) function is used to add an item to the queue (usually via _msg), while io.outputFromQueue takes the next item, and handles it; if it is text, it is passed to io.print. The queue itself is io.outputQueue, and the system uses io.outputSuspended to flag that output should be temporarily stopped.

The errormsg and debugmsg functions bypass the queue, and directly use io.print, as the issue may be in the queue.

The items are dictionaries with various attributes:

action:     What to do, should be one of those listed later
cssClass:   The CSS class, defaults to "default-" plus the tag (eg "default-h2")
delay:      How long to wait for, in seconds (only used for delay)
destination:An image can be sent to the named HTML element rather than the normal output
id:         A unique sequential number assigned by Quest - do not set this yourself
height:     Used by images
name:       Name of the audio element to play (only for sound and ambient)
onclick:    Text to give to the element's "onclick" attribute.
printBlank: Print even if there is no content (only for output)
src:        As usual for HTML images
tag:        HTML tag name to use for this element, defaults to "p"
text:       The actual text
volume:     How loud to play the sound (only for ambient)
width:      Used by images

    Effects use further attributes

The actions allowed are:

action	input disabled	output suspended	next	comment
wait	y	y	n	Print a message, then wait for player click, calling io.waitContinue()
delay	y	y	n	Optionally print a message, then wait for delay seconds, before calling io.unpause()
output	n	n	y	Print the text to screen using io.print, with itself as parameter
clear	n	n	y	Empty the #output element
ambient	n	n	n	Stop all current sounds, start name, looping
sound	n	n	n	Start name
effect	n	n	n	Calls its own effect function attribute, with itself as parameter
func	n	n	?	Call the "func" attribute as a function; will go to next if the function returns true

Usually after one item is printed, it calls io.outputFromQueue (noted under the "next" column in the table). However, if an action sets io.outputSuspended this will cause io.outputFromQueue to terminate before doing anything. Thus, if the author has some text printed, then a pause, then more text, as each line of text is printed, it calls io.outputFromQueue. When it gets to the pause, however, it does not, instead setting up a time out. The timeout then calls io.forceOutputFromQueue, which unsets io.outputSuspended before calling io.outputFromQueue and the rest of the text is printed.