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
//'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