Intro

There's now an optional text parser system in PowerQuest, so you can make really old school games like the early Sierra ones where you have to type in commands. I have a soft spot for these, they're strangely immersive, despite the inherit clunkiness, and I hope this inspires people to make some games with it!

Video Tutorial/Example

The Parser Editor

To use the parser, create a new project, and select the Text Parser option from the list of templates. (You can add text parser support to existing projects, but it's a bit more involved.)

Go to the Parser section under the Tools tab in PowerQuest. It should look something like this:

In that you have:

Global Parser Script, and Room Parser Script buttons:
- These are shortcuts to open the OnParser function in the current room or global script
Ignore List:
- These words are ignored by the parser. If the user types these in they'll be ignored.
- This means you can check for "Look bucket", and it'll work even if the player has typed "Look at the bucket". (Since "at" and "the" are in the ignore list.)
- To add more words, type them at the end, with comma or space between. Or unfold the list to view it vertically.
Synonyms List:
- This list contains the words you want your parser to recognise.
- For each word, you can have any number of synonyms (words that mean the same thing).
- This means that when you check for "Look bucket", it'll work even if the user types "Examine the pail", or "peer at the can".
- To add a new word, click the + at the bottom, and type into the list. Type any number of synonyms for each word, separated by a comma or a space.
Test Condition and Test Parser fields:
- These are useful to test whether something will match text form the player.
- In Test Condition field, type in the condition you want to test (Eg. "look bucket").
- Then type some things the player might type into the Test Parser field. (eg. "examine the pail")
- A window will pop up saying whether the parser text was accepted or not, useful for trying out the special characters mentioned below.

Parser Scripting

The bulk of your parser-game's gameplay will be scripted in OnParser functions in your Rooms and and GlobalScript. They'll end up looking something like this:

There's a lot to unpack here! But it starts nice and simple, I promise!

You can access the IParser class from scripts by typing Parser.. That only contains a few functions, the main ones are Parser.ParseText(string inputText) and Parser.Said(string textToMatch).

Parser.ParseText() tells the parser what the user has typed, and optionally triggers the OnParser functions to be called in your scripts. This is already done in the Parser Gui in the template project, so we won't worry about it for now.

Parser.Said() is the important one, that's what you'll be using the most. Use this to check whether the player's input matches what you want. If it does, it returns true. eg.

if ( Parser.Said("Say Hello" )
{
    Dave: Hello!
}
else if ( Parser.Said("Talk Barney") )
{
    Dave: Hi Barney.
    Barney: Hi!
}

Since you'll have a lot of these, there's a shortcut for the Parser.Said("") bit in the Quest Script editor, using the Tilde charcter ~. eg.

if ( ~Say Hello~ )
{
    Dave: Hello!
}
else if ( ~Talk Barney~ )
{
    Dave: Hi Barney.
    Barney: Hi!
}

And to simplify things even more, you can replace the " if " part with ~~Say Hello~, the "else if", with ~Talk Barney~ and the final closing brace "}" with ~~~. Like so:

~~Say Hello~
    Dave: Hello!

~Talk Barney~
    Dave: Hi Barney.
    Barney: Hi!
~~~

Much more readable!

In some places you'll want to mix and match all three styles, depending how complicated your script is!

Note that if you miss the extra ~~ at the start, or the ~~~ at the end, the script editor will complain about mismatched braces '}', which can be confusing ;)

Special Characters

There's a few special characters you can use in the Said function too~

Optional words

Use brackets ( ) around words that you want to be optional.
Eg: ~look (around)~ will match both "look" and "look around"

Alternate words

Use a comma , to define synonyms when you don't want to add a global synonym to the parser.
eg. look bush,shrubbery will match "look bush" and "look shrubbery", etc.
This is a nice alternative to typing if ( ~look bush~ || ~look shrubbery~ )

Wildcard Words

Use * to match any word.
eg. ~sit on *~ will match "sit on bucket", "sit on well", "sit on barney".
When a wildcard word has been found, Parser.HasWildcard will return true. And Parser.WildcardWord returns it for you to use.
eg. Display: You sit on the {Parser.WildcardWord}.

Rest of line

Use > to match the rest of the line.
eg. ~ tell barney about> ~ matches "tell barney about eels taking over the world", "tell barney about adventure game text parsers", etc.

Quest Objects

Often you want to match hotspots, props, characters, or inventory items that are in the game. Especially if you're mixing mouse and parser support.
This is possible with a second parameter to the IParser.Said() function. Eg. Parser.Said("drink from", H.Well);
And in quest scripts, simply use a dash '-' at the end of the line, followed by the object.
eg. ~drink from- P.Well~
When doing this, the parser will match the text in the description of the object, which also supports the , character.
- So if the Well prop's description is "well, hole", the above example will match "drink from hole" or "drink from well".
Another advantage to this is it flags the object as the last thing "clicked".
- This means you can use functions like WalkToClicked and FaceClicked, and the character will walk to the correct object.
- You also can access this 'clickable object' object with Parser.Target.

Other Scripting Notes

You usually don't want to include ignored words in the said functions, but you can if you want to. For example, to differentiate ~look in well~ from ~look well~ even though "in" is an ignored word.
If no match is found in your room's OnParser function, it'll then check the GlobalScript OnParser function. This is where you can put stuff that'll happen in more than one room, or things for unhandled text.
The GlobalScript OnParser function also contains code to call the OnLookAt functions of Props, Hotspots, Character or Items if their name was typed
- eg: "Look Barney" will automatically call the OnLookAt function in Barney's script.
- You could extend this, to work with OnInteract or maybe OnUseInv functions if it makes sense to do so.
You can call through to other regular interactions using the "Handle" functions. The following, for example, will do what's in the "use" script for the bucket prop, containing the script for the player getting the bucket.

~get- P.Bucket~     
    E.HandleInteract(P.Bucket);

Sometimes when you have alternate ways of saying something it's easiest to re-parse it into the same one using E.HandleParser
- eg. the following works with both "use bucket on well" and "lower bucket into well".

~use well bucket~
    Display: You fill the bucket.
~use,fill,lower bucket well~
    E.HandleParser("use well bucket");

Unhandled input

When a bit of text isn't handled, you should call Parser.OnUnhandledEvent.
This copies the line to the clipboard and opens the room's OnParser function. So you can easily paste the line in.
It also adds it to a file in your project/game folder called UnhandledParser.txt. Testers can give you this file so you can see what they've been typing add responses for those lines!
There's also Parser.UnknownWord, if the user typed a word that wasn't in the Ignored or Synonym list, this will be set, so you can tell the user. eg.

if ( Parser.HasUnknownWord ) 
    Display: You can't use the word {Parser.UnknownWord} here!

Adding Parser Support to Existing Projects (Advanced)

This is a bit involved, since I didn't want to have parser stuff litting projects that don't use it. You'll need to:
Create a prefab with the SystemParser component, and drag that into the list of Systems in Tools->PowerQuest.
Tick the Enable Parser tickbox in Tools->PowerQuest
Create a gui that takes the players input (eg. from a text field) and passes it to Parser.ParseText().
To be able to use Quest script editor shortcuts like ~look well~, you'll need to add stuff to Tools->Editor Settings. It's probably easiest to copy from another project that uses the template.

Contents