How to:Use Verb Event Hooks

Verb event hooks provide a way for authors to inject custom code into the doTry and doSuccess phases of a verb. Event hooks can be used to augment or override a verb's built-in logic. Event hook calls are made from within built-in blocks of code. Usually, event hook calls 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, event hook calls 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 event hooks may not operate with 100% consistency.

Here's an example of how you might attach a verb event hook to an asset. In this example, onTryThrowThis, onTryThrowThisAtThat, onThrowThis and onThrowThisAtThat are all verb event hooks specific to the verb throw. Each verb has its own event hooks, that are documented on the verb's doc page.

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

MyGame.createAsset({
  class: "Weapon",
  name: "throwing star",
  is: { 
    direct_object_of_verb: { 
      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 an event hook 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" },
  event_hooks:
  {
    onTryThrowThis: 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);
    },
    onTryThrowThisAtThat: 
    { 
      "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);
      }
    },
    onThrowThis: 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);
    },
    onThrowThisAtThat: 
    { 
      "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);
      }
    }
  }
});