Basic Verb Use:Verb Hooks - Actions

Verb actions provide a hook for authors to inject custom code into the doTry and doSuccess phases of a verb. Verb actions can be used to augment or override a verb's built-in logic. Action calls are made from within built-in blocks of code. Usually, actions are placed as close as possible to the top of a block, so that an author can override the entire block if they choose. Sometimes, actions may fall a little lower in the block; for example, if the verb needs to resolve some issue involving the order of words in the input before moving on to processing the nouns. This is just a mild warning to note that verb actions may not be perfectly consistent from verb to verb.

Here's an example of how you might hook an asset into a verb action. In this example, tryThrowThis, tryThrowThisAtThat, doThrowThis and doThrowThisAtThat are all actions of throw. You can find each verb's actions listed on its doc page.

MyGame.createAsset({
  class: "NPC",
  name: "cave troll",
  place: {in: "cave"},
});

MyGame.createAsset({
  class: "Weapon",
  name: "throwing star",
  dov: { 
    throw: { 
      // this lets a player throw the star at anything
      with_anything: true, 
    }, 
  }, 
  descriptions: {
    look: "It's a little star of black metal with sharpened points. ",

    // descriptions.throw is one way to print a string when the asset is thrown
    // If you also use verb actions as shown below, 
    // you may find the output competes with itself.
    // You can choose which option works the best for you.
    throw: "It bounces across the floor with a series of metallic clangs. ",
  },
  article: "the",
  place: { in: "weapons rack" },
  tryThrowThis: function(params)
  {
    // this results if the player tries to throw the star
    // it will print independently of any other output the verb prints
    let msg = "You limber up your arm for a good overhand throw. ";
    MyGame.print(msg);
  },
  tryThrowThisAtThat: 
  { 
    "cave troll": function(params)
    {
      // this results only if the player tries to throw the star at the troll
      let msg = "You size up the troll and ready your arm for a strong throw. ";
      MyGame.print(msg);
    }
  },
  doThrowThis: function(params)
  {
    // this results if the player succeeds in throwing the star
    let msg = "You feel a painful twinge in your arm after releasing the star. ";
    MyGame.print(msg);
  },
  doThrowThisAtThat: 
  { 
    "cave troll": function(params)
    {
      // this results only if the player succeeds in throwing the star at the troll
      let msg = "The star thuds to a stop in the troll's chest. The troll looks annoyed. ";
      MyGame.print(msg);
    }
  }
});

WHY SO MANY???

Verb action hooks provide hooks that allow authors to inject custom code in response to specific combinations of verb/preposition/noun. There are a lot of them and clearly some are redundant; in its defense, it's a deliberate effort to offer a menu of precise injection points for authors' custom code. To use a verb action, just use the verb action name as a method on any asset. Below is a generic example of how to code a verb action.

MyGame.createAsset({
  class: "Player",
  name: "Elvis",  
});
MyGame.createAsset({
  class: "Weapon",
  name: "pistol",
  doShootThis: {
    let msg = `You fire the pistol! BANG! `;
      MyGame.print(msg);
  },
  doShootThatWithThis:{
    "television": function {
      let msg = `You fire the pistol at the television! BANG! 
        The television explodes with sparks and a screech of static. `;
      MyGame.print(msg);
    },
  },
});
MyGame.createAsset({
  class: "Electronics",
  name: "television",
});

Verb actions are called by the verb.handleActions() method, which looks for those nested functions and calls whatever function it finds. Each verb has a unique set of actions, which mirror the sentence structures the verb can handle. For instance, the verb lock handles "verb noun" and "verb noun preposition noun", and so it handles tryLockThis and doLockThis and tryLockThisWithThat and doLockThisWithThat.

The difference between try actions and do actions is one of timing. try actions fire immediately before a verb's doTry phase, which provides an opportunity to supersede a verb's default conditional logic before it tests whether the verb can be applied to the assets. do actions fire immediately before a verb's doSuccess phase, which provides an opportunity to supersede or append the verb's state changes and output to the player.

It's common for sentence structures to be mutated during a verb's doTry phase, as doTry may reorder a player's input to make it conform with the verb's logic. This means that the try and do actions may differ within the same turn. You can check the browser's Javascript console to see which actions are being called.