Basic Verb Use:Verb Subscriptions

The first thing to understand about verbs is that there are verbs and there are verb subscriptions. Verbs are defined in the AdventureJS dictionary, and assets must subscribe to verbs in order for the verbs to act on the assets. This document is talking about verb subscriptions.

An asset must be subscribed to a verb in order to be an object of that verb. In other words, the asset's verb subscription defines whether the verb is allowed to be applied to it, and how the verb will behave when it is applied. By default, a verb will act the same way upon all assets. Verb subscriptions allow assets to customize how the verb acts on upon them. Just to make things extra confusing, assets have distinct verb subscriptions depending on whether they are to be used as a direct object or an indirect object of a verb. An asset that can be either the direct object or the indirect object of a verb will have two subscriptions to the same verb.

Scroll down to see a complete list of verb subscription properties that can be used to customize how a verb acts on an asset (or asset class). Verb interactions can also be customized per asset (or class) via three different types of verb hooks: phase hooks, action hooks, and reaction hooks.

Example

This basic example shows a potion asset with customized responses for the verb drink.

MyGame.createAsset({
  class: "Potion",
  name: "sleep potion",
  dov: {
    drink: {

      on_success: "{We} promptly fall asleep. ",
      // Any value set for on_success will be printed when the verb is applied.
      // This will be appended to the default message for drink.

      then_destroy: true,
      // Setting then_destroy to true will destroy this asset after using this verb.

      on_destroy: "{We} crumple the potion bottle and toss it aside. ",
      // Setting any value for then_destroy will print that value 
      // after the verb is applied if then_destroy is true.
      // This will be appended to the default message for drink.

    },
  },
});

Verb subscription properties

automatically {Boolean} Allows for some verbs to be performed automatically if context calls for it; for example, when unlocking a door in order to pass through it. An asset's verb subscription setting takes precedence over game settings.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { automatically: true } },
});
```

automatically_after_use {Boolean} This sets it so that a verb can only be applied automatically after a player has already used it manually. This is to prevent automatic use of tools from breaking puzzles. For example, imagine one door with many keys but only one that works; if choosing the right key is part of the puzzle, this option prevents players from simply saying "unlock door" and having the right key automatically selected for them. When setting automatically_after_use to true you don't also have to set automatically.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { automatically_after_use: true } },
});
```

enabled {Boolean} Verb subscriptions are enabled by default, but can be disabled manually. Temporarily disabling a verb subscription can be a useful method for controlling an asset. For example, you might disable open for a door that needs another action to be completed before it can be opened.

Expand for example

MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { enabled: true } },
});

Individual verb subscriptions can be enabled / disabled via asset.setDOV(verbname) and asset.unsetDOV(verbname).

Expand for example

MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { enabled: true } },
});

// disable the verb subscription
MyGame.$("universal widget").unsetDOV("open");

// reenable the verb subscription
MyGame.$("universal widget").setDOV("open");

// A valid alternative to using game.$(name) 
// is to set your own reference to an asset. 

const horrible = MyGame.createAsset({
  class: "Thing",
  name: "horrible widget",
  dov: { open: { enabled: true } },
});

// disable the verb subscription
horrible.unsetDOV("open");

// reenable the verb subscription
horrible.setDOV("open");

on_success {String|Array|Function} If this property returns a string, the string will be appended to the verb's default success message. Though a string is expected, this property is handled by getStringArrayFunction().
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { on_success: "You open the thing. " } },
});
```

on_first_success {String|Array|Function} If this property returns a string, the string will be appended to the verb's default success message the first time it is applied to this asset. Though a string is expected, this property is handled by getStringArrayFunction().
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { on_first_success: "You opened the universal widget for the first time. " } },
});
```

on_failure {String|Array|Function} If this property returns a string, the string will be appended to the verb's default failure message. Though a string is expected, this property is handled by getStringArrayFunction().
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { on_failure: "You failed to open the universal widget. " } },
});
```

on_first_failure {String|Array|Function} If this property returns a string, the string will be appended to the verb's default failure message the first time it is applied to this asset. Though a string is expected, this property is handled by getStringArrayFunction().
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { on_first_failure: "You failed to open the universal widget this first time. " } },
});
```

once {Boolean} if true, the verb can only be applied once to the asset. The verb subscription will be disabled after use. No special message will be printed, but subsequent attempts to use the verb on this asset will explain why it can't be used again.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { once: true } },
});
```

then_destroy {Boolean} If this property is true, the asset will be destroyed after the verb is applied.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { then_destroy: true } },
});
```

on_destroy {String|Array|Function} If this property returns a string, the asset will be destroyed after the verb is applied, and the string will be appended to the verb's success message. Though a string is expected, this property is handled by getStringArrayFunction().
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { 
    open: { 
      then_destroy: true, 
      on_destroy: "The widget is destroyed!" 
    } 
  },
});
```

with_anything {Boolean} Pertains only to indirect objects. If true, this asset can be used as an indirect object of this verb with any direct object.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  iov: { open: { with_anything: true } },
});
```

with_assets {Boolean} Use to specify particular assets that can interact with this one using the given verb. For example "unlock door with key" where the specified key is the only asset that can unlock door. This works distinctly for direct and indirect verb subscriptions. So, for instance, in "unlock door with key", the door might have a direct object subscription, while the key has an indirect object description.
Expand for example
```
MyGame.createAsset({
  class: "Door",
  name: "gold door",
  dov: { unlock: { with_assets: [ "gold key" ] } },
});
MyGame.createAsset({
  class: "Key",
  name: "gold key",
  iov: { unlock: { with_assets: [ "gold door" ] } },
});
```

with_classes {Array} Use to specify particular classes that can interact with this asset using the given verb. For example "unlock door with skeleton key" where any instance of the class SkeletonKey can unlock door. This works distinctly for direct and indirect verb subscriptions. So, for instance, in "unlock door with skeleton key", the door might have a direct object subscription, while the key has an indirect object description.
Expand for example
```
MyGame.createAsset({
  class: "Door",
  name: "red door",
  dov: { unlock: { with_classes: [ "SkeletonKey" ] } },
});
MyGame.createAsset({
  class: "SkeletonKey",
  name: "skeleton key",
  iov: { unlock: { with_classes: [ "Door", "Chest" ] } },
});
```

with_nothing {Array} Pertains only to direct objects. If true, the specified verb can be applied to the direct object without the use of any indirect object.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { open: { with_nothing: true } },
});
```

with_params {Object} Used to contain a set of parameters that are specific to this particular verb. For example, plugIn includes with_params.max_connections for setting limits on how many other assets this asset can be plugged into. See the with_params section on any verb page to learn more about that verb's parameters.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { 
    plugIn: { 
      with_params: {  
        max_connections: 1,
        on_take_break_connections: true,
        on_take_take_connections: false,
      } 
    } 
  },
});
```

with_prepositions {Array} Use to limit the prepositions that can be used with this asset. For instance: "knock over umbrella stand" might fail with a message of "you can't knock over the umbrella stand"; setting umbrella_stand.dov.knock.with_prepositions = ["over"] will allow the action to succeed.
Expand for example
```
MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { throw: { with_prepositions: [ "through", "over" ] } },
});
```

doBeforeTry {Function} Verb phases provide methods to override default verb behaviors. See Basic Verb Use: Phase Hooks for more information.

Expand for example

MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { 
    open: { 
      doBeforeTry: function (e) {
        console.log("open.doBeforeTry");
      },
    } 
  },
});

doAfterTry {Function} Verb phases provide methods to override default verb behaviors. See Basic Verb Use: Phase Hooks for more information.

Expand for example

MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { 
    open: { 
      doAfterTry: function (e) {
        console.log("open.doAfterTry");
      },
    } 
  },
});

doBeforeSuccess {Function} Verb phases provide methods to override default verb behaviors. See Basic Verb Use: Phase Hooks for more information.

Expand for example

MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { 
    open: { 
      doBeforeSuccess: function (e) {
        console.log("open.doBeforeSuccess");
      },
    } 
  },
});

doAfterSuccess {Function} Verb phases provide methods to override default verb behaviors. See Basic Verb Use: Phase Hooks for more information.

Expand for example

MyGame.createAsset({
  class: "Thing",
  name: "universal widget",
  dov: { 
    open: { 
      doAfterSuccess: function (e) {
        console.log("open.doAfterSuccess");
      },
    } 
  },
});