Reference Manual:How A Verb Works

do

All verbs have a do method. For most verbs, do acts as a sequencer, calling each of these sub-methods or phases in turn: doBeforeTry, doTry, doAfterTry, doBeforeSuccess, and doAfterSuccess. These six phases are split into distinct methods in order to let authors inject custom code at specific points of a verb's process. This way authors can choose whether they would like their custom logic to precede or follow or override entirely. Some special verbs, such as again, have only a do method without submethods.

doBeforeTry phase

doBeforeTry is one of four phases that support verb phases. These allow authors to inject custom code, per asset, before and after the doTry and doSuccess phases.

Per asset in input

For example if player inputs attach flange to pipe with wrench, these steps will be applied in turn to each of flange and pipe and wrench.

• Increment try verb count
  Keeps a count of every time a verb is attempted on an asset, a number that is available for use by authors through asset._didTry(verb).
• Check verb subscription for doBeforeTry verb phase
  Authors may inject custom code by setting a doBeforeTry verb phase in any asset's verb subscription. This allows an author to inject custom logic that runs before the verb's default doTry logic.

doTry phase

doTry contains all of a verb's conditional logic to test whether it can be applied to a specified asset under current circumstances. It offers additional opportunities for authors to inject custom code by means of verb actions.

• Apply specific verb logic
  Many verbs share common blocks and patterns, though each verb may also have distinct logic at any point.

Sentence structure: verb noun

Verb noun is a common sentence structure, though it's only shown here as an example. Each verb typically supports anywhere from one to five sentence structures, including: verb for intransitive verbs like "jump"; verb noun for phrases like "go north"; verb preposition noun for phrases like "look at tree"; verb noun preposition noun for "break glass with hammer"; etc. Each verb's logic may vary according to the sentence structure received.

• doVerbAction tryVerbThis
  Verb actions are another way for authors to inject custom code. Verb actions can be assigned to specific assets, to call custom code whenever a certain verb-related event is applied to them. Verb actions differ from verb phases in that verb actions may be called from within the doTry or doSuccess phases. Additionally, some verb actions, such as doMoveThatToThis, are not verb-specific and may be called by multiple verbs. Though these are technically identical to verb actions, we refer to these non verb-related events as verb reactions.
• Apply verb's specific sentence structure logic
  It's common that each sentence structure a verb handles will have some amount of distinct logic. For example, consider the differences in handling input like "look" vs "look at reflection in mirror". One is an intransitive verb with no object that might only need to print the current room description, while the other may need to test for the existence of two assets and the relationship between them.

Sentence structure: verb noun preposition noun

Verb noun preposition noun is a common sentence structure, though it's only shown here as an example. Each verb typically supports anywhere from one to five sentence structures, including: verb for intransitive verbs like "jump"; verb noun for phrases like "go north"; verb preposition noun for phrases like "look at tree"; verb noun preposition noun for "break glass with hammer"; etc. Each verb's logic may vary according to the sentence structure received.

• doVerbAction tryVerbThisWithThat
  Verb actions are another way for authors to inject custom code. Verb actions can be assigned to specific assets, to call custom code whenever a certain verb-related event is applied to them. Verb actions differ from verb phases in that verb actions may be called from within the doTry or doSuccess phases. Additionally, some verb actions, such as doMoveThatToThis, are not verb-specific and may be called by multiple verbs. Though these are technically identical to verb actions, we refer to these non verb-related events as verb reactions.
• doVerbAction tryVerbThatWithThis
  See how this hook is onTryThatWithThis vs the previous hook onTryThisWithThat. That is because, given a direct object and an indirect object, either one may have a verb action hooked into it. AdventureJS does this to give authors more flexibility in where they may place custom code.
• Apply verb's specific sentence structure logic
  It's common that each sentence structure a verb handles will have some amount of distinct logic. For example, consider the differences in handling input like "look" vs "look at reflection in mirror". One is an intransitive verb with no object that might only need to print the current room description, while the other may need to test for the existence of two assets and the relationship between them.

Handle failure (if needed)

While each verb has its own failure logic, additional steps are universally applied to most verbs, and handled by a common handleFailure method.

• Check verb for override_failure_msg
  This is a simple way to override a verb's failure messages. If set, it will override any message generated by a verb's doTry phase. This is a broad override that applies to all assets. Useful if you don't want to use a verb's built-in failure messages but also don't want to rewrite every one of them. However, note that it doesn't override messages generated by the parser before reaching the verb, which includes failures caused by unacceptable sentence structures, not enough or too many nouns, assets that don't meet minimum requirements, etc.

Per asset in input

For example if player inputs attach flange to pipe with wrench, these steps will be applied in turn to each of flange and pipe and wrench.

• Check verb subscription for on_first_failure
  Any asset can be set to print a custom string the first time a specific verb fails to be applied to it. For example, set it so that climb stairs when applied the first time results in printing "You feel dizzy and fall back down the stairs."
• Check verb subscription for on_failure
  Any asset can be set to print a custom string any time a specific verb fails to be applied to it. For example, set it so that close door when applied to a certain door results in printing "The door just won't quite shut."

doAfterTry phase

doBeforeSuccess is one of four phases that support verb phases. These allow authors to inject custom code, per asset, before and after the doTry and doSuccess phases. doAfterTry and doBeforeSuccess are arguably the same, as they both occur between doTry and doSuccess. Which one to use is up to author preference.

Per asset in input

For example if player inputs attach flange to pipe with wrench, these steps will be applied in turn to each of flange and pipe and wrench.

• Check verb subscription for doAfterTry verb phase
  Authors may inject custom code by setting a doAfterTry verb phase in any asset's verb subscription. This allows an author to inject custom logic that runs immediately after the verb's default doTry logic.

doBeforeSuccess phase

doBeforeSuccess is one of four phases that support verb phases. These allow authors to inject custom code, per asset, before and after the doTry and doSuccess phases. doAfterTry and doBeforeSuccess are arguably the same, as they both occur between doTry and doSuccess. Which one to use is up to author preference.

Per asset in input

For example if player inputs attach flange to pipe with wrench, these steps will be applied in turn to each of flange and pipe and wrench.

• Check verb subscription for doBeforeSuccess verb phase
  Authors may inject custom code by setting a doBeforeSuccess verb phase in any asset's verb subscription. This allows an author to inject custom logic that runs before the verb's default doSuccess logic. In practical terms, doBeforeSuccess is effectively the same as doAfterTry; which one to use is up to personal preference.

doSuccess phase

doSuccess contains logic to apply the verb to a specified asset, by setting state and composing output to return to the player. It offers additional opportunities for authors to inject custom code by means of verb actions.

Sentence structure: verb noun

Verb noun is a common sentence structure, though it's only shown here as an example. Each verb typically supports anywhere from one to five sentence structures, including: verb for intransitive verbs like "jump"; verb noun for phrases like "go north"; verb preposition noun for phrases like "look at tree"; verb noun preposition noun for "break glass with hammer"; etc. Each verb's logic may vary according to the sentence structure received.

• doVerbAction doVerbThis
  Verb actions are another way for authors to inject custom code. Verb actions can be assigned to specific assets, to call custom code whenever a certain verb-related event is applied to them. Verb actions differ from verb phases in that verb actions may be called from within the doTry or doSuccess phases. Additionally, some verb actions, such as doMoveThatToThis, are not verb-specific and may be called by multiple verbs. Though these are technically identical to verb actions, we refer to these non verb-related events as verb reactions.
• Apply verb's specific sentence structure logic
  It's common that each sentence structure a verb handles will have some amount of distinct logic. For example, consider the differences in handling input like "look" vs "look at reflection in mirror". One is an intransitive verb with no object that might only need to print the current room description, while the other may need to test for the existence of two assets and the relationship between them.

Sentence structure: verb noun preposition noun

Verb noun preposition noun is a common sentence structure, though it's only shown here as an example. Each verb typically supports anywhere from one to five sentence structures, including: verb for intransitive verbs like "jump"; verb noun for phrases like "go north"; verb preposition noun for phrases like "look at tree"; verb noun preposition noun for "break glass with hammer"; etc. Each verb's logic may vary according to the sentence structure received.

• doVerbAction doVerbThisWithThat
  Verb actions are another way for authors to inject custom code. Verb actions can be assigned to specific assets, to call custom code whenever a certain verb-related event is applied to them. Verb actions differ from verb phases in that verb actions may be called from within the doTry or doSuccess phases. Additionally, some verb actions, such as doMoveThatToThis, are not verb-specific and may be called by multiple verbs. Though these are technically identical to verb actions, we refer to these non verb-related events as verb reactions.
• doVerbAction doVerbThatWithThis
  See how this hook is onDoThatWithThis vs the previous hook onDoThisWithThat. That is because, given a direct object and an indirect object, either one may have a verb action hooked into it. AdventureJS does this to give authors more flexibility in where they may place custom code.
• Apply verb's specific sentence structure logic
  It's common that each sentence structure a verb handles will have some amount of distinct logic. For example, consider the differences in handling input like "look" vs "look at reflection in mirror". One is an intransitive verb with no object that might only need to print the current room description, while the other may need to test for the existence of two assets and the relationship between them.
• Apply state changes
  For example, using verb lock on an asset may set asset.is.locked to true.
• Compose output
  Many verbs will tailor their output depending on conditions such as whether an indirect object was used, the state of the assets effected, or the player's posture or position.

Handle success

While doSuccess handles state and output, there are additional steps beyond it which are universal to most verbs, and handled by a common handleSuccess method.

• Check verb for override_success_msg
  This is a simple way to override a verb's success messages. It can be set in an author's game file. If set, it will override the message generated by the compose output block in a verb's doSuccess phase. This is a broad override that applies to all assets. Useful if you don't want the built-in messages but don't want to rewrite every one of them.

Per asset in input

For example if player inputs attach flange to pipe with wrench, these steps will be applied in turn to each of flange and pipe and wrench.

• Increment do verb count
  Keeps a count of every time a verb is applied to an asset, a number that is available for use by authors through asset._didDo(verb).
• Check verb subscription for on_first_success
  Any asset can be set to print a custom string the first time a specific verb is applied to it, by setting its verb subscription's on_first_success property. For example, set it so that "climb stairs" when applied the first time results in printing "You feel dizzy when you reach the top."
• Check verb subscription for on_success
  Any asset can be set to print a custom string any time a specific verb is applied to it, by setting its verb subscription's on_success property. For example, set it so that "close door" when applied to a certain door results in printing "The door creaks shut eerily."
• Check verb subscription for then_destroy
  Any asset can be set to be destroyed after a specific verb is applied to it, by setting its verb subscription's then_destroy property to true. For example, consider a lockpick that breaks after a single use.

doAfterSuccess phase

doAfterSuccess is one of four phases that support verb phases. These allow authors to inject custom code, per asset, before and after the doTry and doSuccess phases.

Per asset in input

For example if player inputs attach flange to pipe with wrench, these steps will be applied in turn to each of flange and pipe and wrench.

• Check verb subscription for doAfterSuccess verb phase
  Authors may inject custom code by setting a doAfterSuccess verb phase in any asset's verb subscription. This allows an author to inject custom logic that runs after the verb's default doSuccess logic.