Skip to content

Configuring

Jump to bottom
Colin Hall-Coates edited this page Apr 23, 2016 · 8 revisions

Make Stumble yours.

The Config

Stumble instances are configured by way of a simple JavaScript object.

For users of stumble-cli , the configuration object should be contained in a JSON file. It is passed to the command line application with the --config (-c) flag.

For direct users of stumble, the configuration object can be written directly in JS, or included (with require) from a JSON file. It is passed as the first and only argument to the Stumble constructor.

The rest of the document will be an outline followed by explanations of each key & value in the configuration object. Basic understanding of valid JSON types and structure will help out here, but it’s pretty straight forward.

See example.json for additional syntax hints.

Explanations

This section explains individual parts of the configuration object.

Note that:

  • The configuration object is subject to mutatations. Stumble does not clone the object in any way, and in several instances changes certain values on the object. This will cause all references held to the object to change as well. This also means external reference can alter the state of the config. For stumble users, it’s best not to hold on to the configuration object once you pass it off, and proceed as though you’ve given Stumble full ownership of the object. Extensions should provide API for changing certain properties, and, if need be, the configuration object can be found in the .config instance property.

  • All property names (keys) are case sensitive. extensions is not the same as Extensions, and Stumble will make no attempts to spot these mistakes for you.

  • Valid JSON requires double quotes around all property names, but JS does not. This document will generally use JSON syntax in examples, since it is valid in both contexts.

  • Three dots …​ indicate that data has been omitted for brevity. Take this as a fill in the blanks kind of hint.

  • Any time a path is involved, unless it is absolute, it is resolved relative to the current working directory responsible for executing whatever ultimately starts Stumble. Care must be taken to ensure that your paths are correct. When in doubt, use absolute paths.

operator

  • Type: String

  • Required

  • Example: "operator": "!"

The operator is the string value that commands should be prefixed with, differentiating them from regular messages.

echo a regular message, ignored by Stumble.

!echo a command, and it's message body.

mumble

  • Type: Object

  • Required

  • Example: "mumble": { …​ }

The mumble object contains properties pertaining to connecting to the target mumble server, and providing identification for Stumble.

server

  • Type: String

  • Required

  • Example: "server": "127.0.0.1"

The server is a string value representing the address of the Mumble server to connect to. mumble:// is prefixed internally, so you should not include it in the address.

port

  • Type: Number (Integer)

  • Required

  • Example: "port": 64738

The port is an integer value specifying the port of the Mumble server to connect to.

username

  • Type: String

  • Required

  • Example: "username": "A Stumble Bot"

The username is a string value representing the user name Stumble will identify as, in the Mumble server. It must adhere to the user name rules set by the server.

password

  • Type: String

  • Optional-ish

  • Example: "password": "super secret !"

The password is a string value representing the password Stumble will use to access the Mumble server. If the server has no password, this should be set as the empty string ("").

The password is plain text. To avoid having plain text passwords floating around:

  • create a key and cert

  • use the password to connect to the Mumble server once

  • register Stumble in the server

Afterwards this field can be omitted.

key

  • Type: String

  • Optional

  • Example: "key": "id/key.pem"

The key is a string value representing the path to an SSL key file.

cert

  • Type: String

  • Optional

  • Example: "key": "id/cert.pem"

The cert is a string value representing the path to an SSL certificate file.

extensions

  • Type: Object

  • Optional

  • Example: "extensions": { …​ }

The extensions object contains properties representing extension names. It is primarily used to load extensions found in the Standard Extension Library, and to specify options for said extensions.

It may be used by third party extensions, so long as their names do not conflict with any Standard Extensions. Do note that extraneous extensions will not be automatically loaded in any way, shape, or form.

To load a Standard Extension, extensions must simply contain a property name (key) matching the name of the extension, holding a truthy value. The cleanest value to provide is true, but some extensions have required sub properties, and as such will need an object, { …​ }, to house them.

To load zero extensions, provide an empty object {}. If you omit this, Stumble will always load a default extensions object of { "system": true }.

Here is a short example, loading the movement, time, and util Standard Extensions. Note that even though system is present, it will not be loaded because it holds a falsy value. Also note that a third party is not a Standard Extension, so Stumble won’t do anything with it, or to it.

{
  "extensions": {
    "movement": {
      "home": "Bot's home channel."
    },
    "system": false,
    "time": true,
    "util": true,
    "a third party": {
      "some option": 64
    }
  }
}

Again, see example.json for a more complete structure.

Now we will dive into each Standard Extension, and its possible options. Keep in mind, all extensions are optional, though some depend on others.

audio

  • Type: Object

  • Required by: audioplayer, audiostream

  • Requires options

  • Example: "audio": { …​ }

The audio extension loads the corresponding Standard Extension, and houses properties pertaining to its functionality.

Options:

directory

  • Type: 'String'

  • Required

  • Example: "directory": "/path/to/my/audio"

The directory option specifies the directory used to store audio files and subdirectories.

Like all paths in the configuration, if not absolute, it is resolve relative to the working directory responsible for executing Stumble.

Take care to ensure the path is correct.

gain

  • Type: Number (Float)

  • Required

  • Example: "gain": 0.5

The gain options specifies the audio playback gain level. It must be float between 0.01 and 1.0, inclusive. If outside this range, it will be clamped to the nearest minimum/maximum.

Stumble is created with love.

Clone this wiki locally