RiveScript-JS

A SessionManager is an interface used to store user variables in RiveScript. These variables include those set via the <set> tag or setUservar() function, as well as recent reply history and private internal state.

By default, RiveScript uses MemorySessionManager, which stores data in memory. This means data is lost when the program restarts. To persist data across restarts, you can replace the default manager with a custom implementation or a community contribution (like rivescript-contrib-redis) that connects to a database like MySQL, MongoDB, or Redis.

To use a custom session manager, pass it as the sessionManager option when instantiating RiveScript.

const RedisSessions = require("rivescript-contrib-redis");

// Provide the sessionManager option to use this instead of
// the default MemorySessionManager.
var bot = new RiveScript({
	sessionManager: new RedisSessions("localhost:6379")
});

The scope parameter in the reply() function allows you to change the execution context of JavaScript macros. Specifically, it redefines the meaning of the built-in this variable within the macro to point to the object provided in the scope argument.

This is useful when your RiveScript bot instance is encapsulated within another JavaScript object (e.g., a class or a controller). By passing the parent object as the scope, your RiveScript JS macros can directly access and manipulate the properties and methods of that parent object using this.

// Conceptual usage:
// If your bot is inside a ScopedBot instance:

class ScopedBot {
  constructor() {
    this.hello = "Hello world";
    this.counter = 1;
    this.bot = new RiveScript();
    // ... setup bot ...
  }

  async testScope(userInput) {
    // Passing 'this' (the ScopedBot instance) as the scope
    // allows JS macros in RiveScript to access ScopedBot's properties.
    return await this.bot.reply(this, userInput);
  }
}

RiveScript v2.0.0+ supports asynchronous object macros that return Promises. Because of the Async/Await architecture, these objects can now be used within *Condition statements in your .rive files. This allows you to perform asynchronous logic (like timers or database lookups) and use the result to branch your bot's responses.

// <call>wait-limited $timeout $maxTimeout</call>
// If the $timeout > $maxTimeout, it resolves "too long" immediately.
// Otherwise it waits $timeout seconds and resolves "done"
> object wait-limited javascript
	var timeout = parseInt(args[0]);
	var max     = parseInt(args[1]);

	return new Promise(function(resolve, reject) {
		if (timeout > max) {
			resolve("too long");
		} else {
			setTimeout(function() {
				resolve("done");
			}, timeout*1000);
		}
	});
< object

+ can you wait # seconds
* <call>wait-limited <star> 6</call> == done => I can!
- No the longest I'll wait is 6 seconds.

The object returned by deparse() follows a specific hierarchical structure representing the bot's logic and variables.

Root Structure

• begin: Contains global definitions:
  • global: Map of ! global variables.
  • var: Map of ! var bot variables.
  • sub: Map of ! sub substitution definitions.
  • person: Map of ! person substitution definitions.
  • array: Map of ! array names to arrays of values.
  • triggers: Array of trigger data for the > begin block.
• topics: Map of topic names to an array of trigger data (the default topic is named "random").
• inherits: Map of topic names to maps of inherited topics.
• includes: Map of topic names to maps of included topics.
• objects: Source code of JavaScript/CoffeeScript object macros (Note: macros defined via rs.setSubroutine() may appear here, but stringifying them is not recommended).

Trigger Data Schema

Each trigger object in begin.triggers or topics.$NAME contains:

• trigger: The plain text trigger string.
• reply: An array of plain text -Reply commands (or []).
• condition: An array of plain text *Condition commands (or []).
• redirect: The text of the @Redirect command, or null.
• previous: The text of the %Previous command, or null.