Phrases

AdventureEngine is inherently designed for making text-based games, which means that everything the player "sees" in the game is communicated through text. The engine uses templates called phrases to generate text, allowing a single line of text to be reused in many different contexts. Phrases have several key features that allow it to do this.

Tags

Tags are the keystone feature of phrases. They allow the text generation system to dynamically replace sections of the phrase with contextual information. This includes nouns (physical things in the game world, such as actors or objects), verbs (which are conjugated to match the subject), and variables (which are simply replaced with a fixed text value). Tags are always specified in the form $key.

Nouns

These tags allow you to insert the name of an actor/object/item/etc. into a phrase by referencing its context key. For example, $actor is replaced with the name of the subject actor in an action phrase. If a particular noun is referenced more than once in a single round (even between multiple phrases), the name will only be used for the first occurrence, after which it will be replaced by a pronoun. The position of the noun tag relative to a verb is used to determine whether it is a subject or an object, which affects which pronouns will be selected (for example, "I" for a subject and "me" for an object). If using the name instead of a pronoun, articles (i.e., "the", "a", "an") will be added unless the noun is marked as a proper noun (this is defined in the referenced object, not in the phrase itself).

There are also several alternative types of noun tags for specific functions (in these examples, key is the context key of the noun, and can be replaced with any noun key):

• $key's: Inserts a possessive form of the noun (e.g., "your" or "the guard's")
• $key_self: Inserts a reflexive form of the noun's pronoun (e.g., "yourself" or "themselves")
• $key_name: Inserts the base name of the noun, with no articles and no pronouns (e.g., "guard" instead of "the guard")

Verbs

Verbs take two forms: regular and irregular. Regular verbs have three tag types that are added at the end of the verb:

• $s: For verbs such as fall$s, which will be conjugated as either "(it) falls" or "(you) fall"
• $es: For verbs such as touch$es, which will be conjugated as either "(it) touches (something)" or "(you) touch (something)"
• $ies: For verbs such as modif$ies, which will be conjugated as either "(it) modifies (something)" or "(you) modify (something)"

Irregular verbs are manually defined in the engine, and thus have their own distinct tags. Currently, the defined irregular verbs are:

• $is
• $isn't
• $doesn't
• $has

Variables

Variables simply replace a tag with a string variable from the context. For example, a phrase for an elevator might look like $actor arrive$s at floor $floorNumber. In this phrase, the tag $floorNumber references a string variable called floorNumber, which can be set in the context to store the string form of the current floor.

Phrase Links

A separate phrase can be inserted into the current phrase by using the form @phraseKey, where phraseKey is the phrase ID.

Random Selectors

Random selectors contain any number of phrase segments, of which one is selected at random and inserted in place of the selector block. Random selectors take the form:

$actor {jump$s|leap$s|spring$s} into the air.

The selector block is enclosed in { }, and each option is separated by a |. The phrase segments within a random selector can contain any phrase features, including tags, other random selectors, or conditional selectors.

Conditional Selectors

Conditional selectors allow you to switch segments of a phrase depending on one or more conditions. It is essentially an in-line if/else chain, in which the conditions are checked in order from left to right, and the first block in which the condition is met is selected. Conditional selectors take the form:

$actor $is ([stat.subject.hp >= 40]in good health|[stat.subject.hp >= 20]lightly injured|seriously injured).

The conditional selector is enclosed in ( ), and each branch is separated by a |. Every branch must contain a condition (an AdventureScript expression enclosed in [ ]) before the phrase segment, except the final branch, which will act as a default "else" branch if no condition is specified. If the final branch does have a condition, and all conditions in the block are unmet, the block will simply be omitted from the generated phrase.

Just like with random selectors, the phrase segments within a conditional selector can contain any phrase features, including tags, random selectors, or other conditional selectors.