Events

Listening to moments during Choicelab playback.

When Choicelab does something, it often fires an event that you can listen and respond to in JavaScript.

Listen to an event

To listen to an event, invoke the .on() method:

Choicelab.on('ready', function() {
  // your event here
});

To stop listening to an event, include a name as the second argument for the .on() method, and the function as the third:

//
// Enable event listener
//
Choicelab.on('ready', 'myCustomListener', function() {
  // your event here
});

Then, disable it using the .off() method:

//
// Disable event listener
//
Choicelab.off('ready', 'myCustomListener');

Built-in events

Event	Fires when...
`end`	The story reaches the end of a path, with no scenes left
`endScene`	The current scene ends
`inputSubmitted`	The player provides input to a question
`pause`	Playback is paused
`play`	Playback starts or resumes
`ready`	Path files are parsed, asset preloading is complete, and Choicelab is ready to play
`scenesParsed`	Path files are parsed, but asset preloading isn't complete
`start`	Playback starts for the first time during a session
`startScene`	The current scene begins

Custom events

If you want to listen to specific scenes, you can create custom events using the event action, and respond to them in your own external script. This is useful if you want to add additional behavior to your story asynchronously, without the work of creating a custom action.

To create an event, add an event action to your scene:


~~


[event name="myCustomEvent"]

Then, simply listen for it in your JavaScript:

Choicelab.on('myCustomEvent', function() {
  // your event here
});