Triggers

Triggers are used for making game objects, primarily non-playing characters (NPCs), respond to things that are going on around them.

For example, you may want an NPC to perform a certain action when someone walks into the same room. In that case you would have to implement the oncharacterentered trigger for the NPC. To make the character greet you upon entering the room, the trigger could look like this:

function(activator) {
    this.say('Hi, ' + activator.name + '!');
}

As you can see, writing triggers is pretty straightforward. Any trigger is just a JavaScript function, so if you know JavaScript, you will have little trouble to write triggers. If you don't know JavaScript, a good place to start learning is at CodeAcademy or the Eloquent JavaScript book, which can be read online. Still, some care needs to be taken because there are some differences between writing triggers and writing JavaScript in a webbrowser. Read on to get more information.

Here's another example of a basic trigger:

function() {
    this.go(this.currentRoom.exits.named('north'));
}

The above example is a trigger that works on a character, and will let him walk north, if possible.

Properties and methods

While writing some trigger you will often be interested to know which properties and methods are available on some object. In the examples above, say() and go() are methods that are available on character objects, currentRoom is a property available on character objects, and exits is a property available on room objects. To inspect an object and list its properties or methods, use the list-props or list-methods commands, respectively.

Timers

Ever so often, you will want to write a trigger that performs some action in a delayed fashion. Possibly you will want to have that action be repeated at an interval. For these purposes, there are setTimeout() and setInterval() functions which work just like those in your webbrowser, with one difference only: The functions are attached to any game object rather than to the global window object as you may be used to. So, to make the character from above walk north with a delay of half a second, we could write this trigger:

function() {
    this.setTimeout(function() {
        this.go(this.currentRoom.exits.named('north'));
    }, 500); // note that the timeout is specified in milliseconds
}

The advantage of having setTimeout() and setInterval() defined on specific game objects is that the callback function is evaluated in the scope of the object (thus the special variable this will always point to the current game object), and the timeout/interval will automatically be removed when the object is deleted or, if it is a character, when the character dies.

If you want characters to continuously perform some action, intervals are probably what you will want to use. The onspawn trigger is the preferred place to create interval timers. For example, if you want to have a character walk around randomly by going to a different room every 10 seconds, you can create an onspawn trigger like this:

function() {
    this.setInterval(function() {
        this.go(this.currentRoom.exits.randomElement());
    }, 10000);
}

Note that both setTimeout() and setInterval() return an ID. If ever you want to cancel the timeout/interval, you can do so using clearTimeout() or clearInterval() with the specified ID, respectively:

function() {
    var intervalId = this.setInterval(function() { /* ... */ });

    this.clearInterval(intervalId);
}

Return values

In many cases, triggers have the ability to cancel the action that triggered them. Whenever this is the case, you can have your trigger return the value false, and the action will be canceled. Canceling the action is supported by any trigger that has a bool return type. For example, if the following function is attached to an item's onopen trigger, the item cannot be opened:

function(activator) {
    activator.send('The lid appears to be stuck.');
    return false;
}

Use help triggers to request an overview of all triggers, including their return types.

Testing scripts

If you simply want to test whether some script works as expected, you can use the exec-script command. In addition to testing, this command is also useful to clean up game data and objects when some script had unintended side-effects. If you want to execute some script on a specific object, you can use this function for getting the object: $('<object-type>:<object-id>'). Example:

exec-script $('character:167').say('Miauw')

Underscore.js

As you start to write increasingly complex scripts, you may want to use more advanced utility methods than those included in pure JavaScript. For this purpose, Underscore.js is included in the default set of scripts. It is a well-known library among web developers, and you should not feel shy of taking advantage of its features.

Useful Commands

Get an overview of all defined triggers:

help triggers

Get an overview of all methods defined on a game object:

list-methods #<object-id>

Get an overview of all properties defined on a game object:

list-props #<object-id>

Further Reading

Read how you can implement your own commands, or how you can customize game objects and game events.

You may want to take a look at the Frequently Asked Questions.