#002: How Commands are Matched

How Commands are Matched

Welome to the second entry in our “How To” guide about Adventure for Ren'Py.  Today we will explore essential information for the game designer to understand about the command matching system.

Command Sentences

At its heart, Adventure for Ren'Py thinks of commands in much the same way as a classic Text Adventure game.  It is primarily interested in finding a VERB and a NOUN.  Although, there are cases where one or the other is implied.

Gathering Possible Sentences for a Click

When a player has a tool selected and clicks on an interactable Verb Icon or Polygon, Adventure gathers a list of all possible verbs and all possible nouns matching the current mouse position (or touch event position) and the chosen tool.

Verb Icons

The case of Verb Icons is simplest, so lets discuss it first.  Only visible icons are taken under consideration, and each Tool only shows icons belonging to a specific set of layers.

Advanced Tip: 

When a tool shows multiple layers, and more than one layer has an icon enabled for a particular interactable Icon point, those icons will automatically be fanned out side-by-side.  If this arangement isn’t visually pleasing, you can simply add a separate Interactable icon object for each layer in order to position them independently.

There are currently four layers supported by Adventure.  They are named ex (for Examine), say (for Say/Speak), op (for Operate), and go (for Go to another Location.)

It is possible to define custom Verb Icons, but the predefined Verb Icons built into Adventure are as follows:

Ex Layer Verb Icons:

• Hint Dot (*ex)
• Tongue (taste; lick)
• Eyeball (look)
• Book (read)

Say Layer Verb Icons:

• Speech Bubble (*say)

Op Layer Verb Icons:

• Hint Dot (*op)
• Pow Star (hit; kick; fight; punch)
• Place Setting (eat)
• Hourglass (wait)
• Tongue (taste; lick)
• Book (read)

Go Layer Verb Icons:

• Walking Person (*go)

Most of the icons are associated with only a single verb, such as the book which means “read,” however icons can be associated with a semicolon separated list of verbs, such as the tongue which means "taste; lick."  Icons can also be associated with the entire list of default verbs associated with a tool.  This is indicated by an asterisk followed by the tool name, such as “*go”.  We will go over these lists of default verbs later in this article.

In addition to the verb, each icon you place in your scene can have one or more tags associated with it (semicolon separated.)

For our example right now, lets imagine we have a Tongue icon on the op layer that we've tagged with “soup; spoon”.

The resulting list of sentences for a click on this icon would be:

1. taste, soup
2. taste, spoon
3. lick, soup
4. lick, spoon

You'll notice there's a comma between the verb and the noun.  This will be explained in the next section.

Last of all, if an icon is clicked, it takes priority, therefore no Polygons are considered for this particular click.

Matching to Your Source Code

In your loop for a particular room, you will use one or several calls to player_chooses_to(), or to one of its specialized shortcut such as player_examines() — which is really just shorthand for a sequence of player_chooses_to and renpy.say commands.

Adventure will take each potential mach and compare it against the list of possible sentences.  This is done in a very generous way:  Verbs have aliases, allowing the game developer (that’s you) to use some shorthand.  Nouns can also have aliases, which can be defined either globally or per-room, which allows you to “color” your language — for reasons you’ll understand shortly.

For now, imagine that you’ve globally defined a noun alias so that soup and stew are equivalent.  Don’t worry yet about how to do that, just imagine that it has already been done.

If your code contains player_chooses_to('taste the stew'), Adventure goes through all the sentences in the list, looking for a matching noun.  Since the first entry in the list is “taste, soup” and stew is an alias for soup, stew is considered a noun match.  Next, it will see if the verb matches.  The verb you wrote in the player_chooses_to is “taste” and this matches the verb in the sentence, so this is considered a match.

Since a match was found, the sentence will be added to the history log.  If your game is set in first person mode (adventure.first_person = True) this will look like:

>>> I taste the stew.

If your game is in second person mode (adventure.first_person = False), then this will look like:

>>> You taste the stew.

After this is added to the history log, the function returns a True result, allowing your game to proceed with the matched action.

If no match was found, False is returned, which allows you to fall into the else block or the elif clause, moving along to consider the next possible match.

Since the possible list of sentences and your source code have to “meet in the middle” to find a match, only sentences that sound like they make sense end up getting added to the history log.

What about Polygons?

Polygons are handled a bit differently than icons.  A polygon has a set of verbs associated with each layer.  The Location Editor will default these verbs to the standard list for the current tool layer.  You can check or uncheck the box associated with each layer to enable or disable that layer entirely for the selected polygon (but keep in mind, matches can only happen anyway if you have corresponding player_chooses_to() code, so you won’t often need to uncheck these.)

Here are the predefined lists of Tool Verbs:

Tool Verbs for Ex:

• examine
• read
• look
• listen
• taste
• smell

Tool Verbs for Say:

• talk [to]
• speak [to]
• say
• ask

Tool Verbs for Op:

• operate
• use
• touch; press
• push
• pull
• turn [on]; activate
• turn [off]; deactivate

Tool Verbs for Go:

• go [through]
• go in[to]; enter
• go out [of]; exit
• go [across]

Tool Verbs for Auto:

• *go (all the verbs from the Go tool)
• *op (all the verbs from the Op tool)
• *say (all the verbs fom the Say tool)
• .*ex (all the verbs from the Ex tool, but don't show any of the icons)

Unlike icons, Polygons are typically assigned to an entire list of verbs.  Also, when matching a Polygon, the system will match overlapping Polygons underneath the mouse cursor all at the same time.  All possible sentences for each polygon are added to the potential list of sentences, but only verbs for the currently chosen Tool are added to the list.  In the case of “auto”, its possible for any verb from any of the other tool lists to match, since it includes all of them.

Finding the Right Match

If multiple maches are possible, how does the game know which match to accept?  Easy, your source code gets executed in order, so the first match in your if/elif/.../else sequence is the one to be chosen.

This leads us to a basic principle:

You should always list important interactions first in your source code, and descriptive-only or “fluff” interactions at the end of the sequence.

This allows for more specific interactions to happen first, such as clicking a mobile phone sitting on top of a desk, and then more general sequences to consider only after the first matches fail, such as “examine desk”, which should happen if you click anywhere else on the desk, but not on the mobile phone.

In Conclusion

I hope this brings clarity to the way Commands are matched with Clicks, and how the associated History Entries are generated.  There are some additional options available, such as setting up aliases, or overriding the history phrasing, but those will be explored in a future article.

Good luck designing your game!