Scene

Scenes conduct participation in dialogue. They use listeners to enter an audience into a new dialogue with the bot.

Once entered into a scene, the audience is engaged and isolated from global listeners. The bot will only respond to branches defined by dialogue in that scene. The scope of audience can be:

• user - engage the user (in any room)
• room - engage the whole room
• direct - engage the user in that room only

Kind: global class

• Scene
  • new Scene(robot, [options], [key])
  • .middleware(context, next, done)
  • .listen(type, regex, callback)
  • .hear()
  • .respond()
  • .whoSpeaks(res) ⇒ string
  • .registerMiddleware(piece)
  • .processEnter(context, [done]) ⇒ Promise
  • .exit(res, [status]) ⇒ boolean
  • .exitAll()
  • .getDialogue(participants) ⇒ Dialogue
  • .inDialogue(participants) ⇒ boolean

---

new Scene(robot, [options], [key])

Param	Type	Description
robot	Robot	Hubot Robot instance
[options]	Object	Key/val options for config
[options.scope]	string	How to address participants: user(default)	room	direct
[options.sendReplies]	boolean	Toggle replying/sending (prefix message with “@user”)
[key]	string	Key name for this instance

Example

let roomScene = new Scene(robot, { scope: 'room' })

---

scene.middleware(context, next, done)

Process incoming messages, re-route to dialogue for engaged participants.

Kind: instance method of Scene

Param	Type	Description
context	Object	Passed through the middleware stack, with res
next	function	Called when all middleware is complete
done	function	Initial (final) completion callback

---

scene.listen(type, regex, callback)

Add listener that enters the audience into the scene with callback to add dialogue branches or process response as required.

Enter callback provides full middleware context, but for consistency with other listener callbacks, response is extracted and given as the first argument, full context is second.

Middleware may prevent callback, e.g. from Director if user denied access.

Kind: instance method of Scene

Param	Type	Description
type	String	The listener type: hear	respond
regex	RegExp	Matcher for listener (accepts string)
callback	function	Called with response and middleware context after listener matched and scene entered

Example

let scene = new Scene(robot, { scope: 'user' })
scene.listen('respond', /hello/, (res) => {
  res.reply('you are now in a scene')
  // add dialogue branches now...
})

---

scene.hear()

Alias of Scene.listen with hear as specified type.

Kind: instance method of Scene

---

scene.respond()

Alias of Scene.listen with respond as specified type.

Kind: instance method of Scene

---

scene.whoSpeaks(res) ⇒ string

Identify the source of a message relative to the scene scope.

Kind: instance method of Scene
Returns: string - ID of room, user or composite

Param	Type	Description
res	Response	Hubot Response object

---

scene.registerMiddleware(piece)

Add a function to the enter middleware stack, to continue or interrupt the pipeline. Called with:

• bound ‘this’ containing the current scene
• context, object containing relevant attributes for the pipeline
• next, function to call to continue the pipeline
• done, final pipeline function, optionally given as argument to next

Kind: instance method of Scene

Param	Type	Description
piece	function	Pipeline function to add to the stack.

---

scene.processEnter(context, [done]) ⇒ Promise

Engage the participants in dialogue. A new Dialogue instance is created and all further messages from the audience in this scene’s scope will be passed to that dialogue, untill they are exited from the scene.

Would usually be invoked as the final piece of enter middleware, after stack execution is triggered by a scene listener but could be called directly to force audience into a scene unprompted.

Kind: instance method of Scene
Returns: Promise - Resolves with callback called in next tick queue

Param	Type	Description
context	Object	The final context after middleware completed
context.response	Object	The hubot response object
context.participants	string	Who is being entered to the scene
[context.options]	Object	Options object given to dialogue
[context.arguments]	Array	Additional arguments given to dialogue
[done]	function	Optional final callback after processed - given context

---

scene.exit(res, [status]) ⇒ boolean

Disengage participants from dialogue e.g. in case of timeout or error.

Kind: instance method of Scene
Returns: boolean - Exit success (may fail if already disengaged)

Param	Type	Default	Description
res	Response		Hubot Response object
[status]	string	"unknown"	Some context, for logs

---

scene.exitAll()

End all engaged dialogues.

Kind: instance method of Scene

---

scene.getDialogue(participants) ⇒ Dialogue

Get the dialogue for engaged participants (relative to scene scope).

Kind: instance method of Scene
Returns: Dialogue - Engaged dialogue instance

Param	Type	Description
participants	string	ID of user, room or composite

---

scene.inDialogue(participants) ⇒ boolean

Get the engaged status for participants.

Kind: instance method of Scene
Returns: boolean - Is engaged status

Param	Type	Description
participants	string	ID of user, room or composite

---