Topics

A topic is way to group triggers and replies together in some arbitrary, or logical way. There are no limit to how many topics you create. SuperScript will continue to try to find matches for your input outside of your current topic.

All dialogue belongs to a topic and even if you do not select any topics, those triggers and replies will be stored in the random topic.

Creating a new topic

You can create new topics using the editor, and the topic has these properties:

• topic name (unique, no spaces)
• keywords (optional) help with the topic flow
• system flag (explained later)
• keep flag (explained later)

Unlike in RiveScript, in SuperScript topics cannot be nested.

Sorting gambits in topics

A topic can include any number of gambits, and the system will try to match them in order. You can sort the gambits in the editor automatically (the greediest trigger will be sorted last), or by drag & drop:

In SuperScript syntax, the default sorting can be overridden by using {weight=XX} in the input (note that this is different from Rivescript, where weight is used in replies):

+ * {weight=100}
- Hello there

+ hello * {weight=90}
- Who are you?

In the above example, Hello John will be matched by the first rule, because of the weighting.

Changing to a new topic

To switch to a new topic, you can use {topic=topic_name} in the reply:

+ I like animals
- Me too! {topic=animals}

If you are in a custom plugin you can also change topics directly by accessing the user object method setTopic(...).

exports.somefunction = function(cb) {
  this.user.setTopic("newTopic")
  cb(null, "")
}

Topic changing only sets the recommended next topic on the next reply but does not guarantee a match. You could also get false positive matches out of context. When the user quits the conversation, the last topic he was in is saved, so next time the user logins, he starts in the same topic.

Topic hooks

Everytime the system tries to match an input, there are two special topics that run, one before your current topic, and one after. We call them pre and post hooks or topics. If you need some trigger to be tested on every pass either before or after the regular triggers, this is where you would put it. Pre and Post topics have a slightly different behavior, but function the same as normal topics.

Topic flags

Topics can have a flag attached to them that modifies its behaviour. keep, system and nostay.

Keep flag

Keep is designed to disable to default behavior of exhausting triggers, if you want the bot to say things over and over again, and apply keep just after the topic definition.

System flag

System topics do not appear in the normal topic flow and you must provide your own way to access them, usually the ^respond(topic_name) function works great for that.

Nostay flag

Nostay can be used to bounce from one topic, but return back to the previous topic right after. It might be a good way to break the flow up and allow the possibility to change the topic, but not do so forcefully.

Topic flow

As noted earlier, the topic logic has improved to allow for easier scripting, and your bot should have access to more gambits. It is important that your topics have well defined keywords, this will help when trying to figure out what topic to check next.

The basic flow for each message cycle is as follows (keep in mind that system topics will never appear in the normal flow):

1. Pre topic
2. Current topic
3. Next best matched topic(s)
4. Any remaining topics
5. Post topic

You can match more than once. Providing your match does not produce any output, the system will keep looking for matches. This is extra helpful when you have plugins or functions that try to do extra parsing on the message or make assumptions that may be false. Note that the goal of SuperScript is to create human-like chatbots, and this is why the topic flow is not as deterministic as RiveScript or Hubot. The lack of keep and arbitrary feeling rules for picking or switching topics makes creating deterministic bots more difficult, but it is better for simulating how real people act (“Hey, I got bored and changed the topic to something else, maybe”).

Functions

^respond() The ^respond(topic_name) function is used in the reply it takes the current input and check it against the selected topic more matches. Once it gets to the end of the topic it will unwind its way back and continue checking in the normal path.

**Topic: random**
+ * i *
- ^respond(i_topic)
+ * you *
- ^respond(you_topic)
**Topic: i_topic**
+ i am not *
- No, you aren’t!
+ i am *1
- Yes, you are!
**Topic: you_topic**
+ you are not *
- No, I am not!
+ you are *1
- Yes, I am!

When the user says I am not a robot! the system will match it with the *** i *** rule and look first for a reply in gambits in i_topic.

^topicRedirect(topic_name,trigger)

^topicRedirect(topic,trigger) is used in the reply and is very similar to reply redirects except they redirect you to a reply in a specific topic.

**Topic: random**
+ say something random
- ^topicRedirect(something_random,__say__)
**Topic: something_random**
+ __say__
- Wind on the face is not good for you.
- I watched Mr. Dressup as a kid.