General Hooks

As described in the plugin Hooks documentation, a plugin can define events and hooks that other plugins can observe, trigger, and respond to. In addition, components can define properties and actions that other plugins and components can access. Together, these capabilities allow plugins and components to control and communicate with each other.

The following hooks are exposed from the core app and available to use in any plugins or components.

User Input Control Hooks

Key Down

Hook identifier: 'controls.key.down'

Triggered when a key is pressed. Returns a KeyboardEvent.

function onKeyDown(evt) {
  console.log('key pressed', evt.code)
}
//
this.hooks.addHandler('controls.key.down', onKeyDown)

Key Up

Hook identifier: 'controls.key.up'

Triggered when a key is released. Returns a KeyboardEvent.

function onKeyUp(evt) {
  console.log('key released', evt.code)
}
//
this.hooks.addHandler('controls.key.up', onKeyUp)

Jump

Hook identifier: 'controls.jump'

Triggered when the user has started the jump animation.

function onJump() {
  console.log('jumping')
}
//
this.hooks.addHandler('controls.jump', onJump)

Space Transition Hooks

Transition Started

Hook identifier: 'core.space.change.start'

Triggered when a user has started the transition to another space. Returns the spaceID and alias of the space that the user is going to.

function onSpaceChangeStart(info) {
  console.log('going to space', ('@' + info.alias), 'with id', info.spaceID)
}
//
this.hooks.addHandler('core.space.change.start', onSpaceChangeStart)

Transition Completed

Hook identifier: 'core.space.change.complete'

Triggered when a user has arrived in a new space. Returns the spaceID and alias of the space that the user has arrived at.

function onSpaceChangeComplete(info) {
  console.log('in space', ('@' + info.alias), 'with id', info.spaceID)
}
//
this.hooks.addHandler('core.space.change.complete', onSpaceChangeComplete)

Entering Space

Hook identifier: 'core.space.enter'

Triggered immediately before a user enters a space, so it can be used by plugins to execute code prior to a user entering a space.

To allow access to the space, nothing special needs to be done. To block access to the space, an error should be thrown, which will display an error screen and prevent the user from entering the space.

// Allows the user to enter the space
function allowEntry() {
  console.log('entering the space')
}
// Prevents the user from entering the space
function blockEntry() {
  throw new Error('You are not allowed to enter this space')
}
//
this.hooks.addHandler('core.space.enter', blockEntry)

Microphone Mute State Change

Hook identifier: 'core.user.audio.mute-change'

Detects when the user's microphone has been toggled between muted and unmuted. The parameter carries a boolean muted property to announce the new state.

function onMuteStateChange(data) {
	console.log( data.muted ? 'User is muted' : 'User mic is on air' )
}
//
this.hooks.addHandler('core.user.audio.mute-change', onMuteStateChange)

Also see user.isMuted() to query the current microphone mute state.

Debug Info

Hook identifier: 'debug.text'

Used to add information to the debug text, which can be viewed by pressing Shift + ~ whilst inside a space. Handler method must return the name of the section and text to display.

function addDebugInfo() {
  return {
    name: 'Section Name',
    text: 'This is some debug info'
  }
}
//
this.hooks.addHandler('debug.text', addDebugInfo)

Gesture Hooks

Quick-Move Started

Hook identifier: 'gestures.quick-move.start'

Triggered when a user has started a quick-move action to a location within the space, initiated by either double-clicking (on desktop) or double-tapping (on mobile) somewhere in the space. Returns the x, y and z position that the user will move to.

function onQuickMoveStart(pos) {
  console.log('moving to position', `(${pos.x}, ${pos.y}, ${pos.z})`)
}
//
this.hooks.addHandler('gestures.quick-move.start', onQuickMoveStart)

Quick-Move Completed

Hook identifier: 'gestures.quick-move.complete'

Triggered when a user has completed a quick-move action. Returns the x, y and z position of the user.

function onQuickMoveComplete(pos) {
  console.log('at position', `(${pos.x}, ${pos.y}, ${pos.z})`)
}
//
this.hooks.addHandler('gestures.quick-move.complete', onQuickMoveComplete)

Places Menu Hook

Hook identifier: 'user.place.arrive'

Triggered when a user has arrived at a place (when using the Places menu). Returns the id, name and pos (which contains x, y and z values) of the place that the user has arrived at.

function onUserArrive(place) {
  console.log('arrived at place', place.name, 'with id', place.id, 'at position', `(${place.pos.x}, ${place.pos.y}, ${place.pos.z})`)
}
//
this.hooks.addHandler('user.place.arrive', onUserArrive)

Video Camera Control hooks

Video Started

Hook identifier: 'user.video.start'

Triggered when a user has turned on their webcam.

function onWebcamOn() {
  console.log('turned on webcam')
}
//
this.hooks.addHandler('user.video.start', onWebcamOn)

Video Ended

Hook identifier: 'user.video.stop'

Triggered when a user has turned off their webcam.

function onWebcamOff() {
  console.log('turned off webcam')
}
//
this.hooks.addHandler('user.video.stop', onWebcamOff)