-
Notifications
You must be signed in to change notification settings - Fork 5
Configuring
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.
This section of the wiki shows the outline of the configuration object.
This section explains individual parts of the configuration object.
Note that:
-
The configuration object is subject to mutations. 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 an external reference can alter the state of the config. For
stumbleusers, 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.configinstance property. -
All property names (keys) are case sensitive.
extensionsis not the same asExtensions, 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.
-
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 its message body.
-
Type:
Object -
Required
-
Example:
"mumble": { … }
The mumble object contains properties pertaining to connecting to the target mumble server, and providing identification for Stumble.
-
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.
-
Type:
Number(Integer) -
Required
-
Example:
"port": 64738
The port is an integer value specifying the port of the Mumble server to connect to.
-
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.
-
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
keyandcert -
use the password to connect to the Mumble server once
-
register Stumble in the server
Afterwards this field can be omitted.
-
Type:
String -
Optional
-
Example:
"key": "id/key.pem"
The key is a string value representing the path to an SSL key file.
-
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.
-
Type:
Object -
Required by:
audioplayer,audiostream -
Requires additional options
-
Example:
"audio": { … }
The audio extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
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.
-
Type:
Object -
Requires:
audio,database -
Requires additional options
-
Example:
"audioplayer": { … }
The audioplayer extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
Type:
Boolean -
Optional
-
Example:
"autoplay": true
The autoplay option indicates whether or not the audio clips on the queue should be automatically played after the currently playing audio ends.
Omitting this option is akin to setting it to false.
-
Type:
Number(Integer) -
Optional
-
Example:
"delay": 350
The delay option specifies the delay time in milliseconds between each track. It is useful if you find tracks are cutting off too abruptly.
An internal default of 250 is used if this option is omitted.
-
Type:
Number(Integer) -
Required
-
Example:
"maxqueue": 10
The maxqueue option specifies maximum amount of tracks that can be queued up.
-
Type:
Object -
Requires:
audio,database,parser -
Example:
"audiostream": { … }
The audiostream extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
Type:
Object -
Required by:
audiostream,io,permissions -
Requires additional options
-
Example:
"database": { … }
The database extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
Type:
Boolean -
Option-less
-
Example:
"info": true
The info extension property loads the corresponding Standard Extension. It has no options, no dependancies, and no dependents.
-
Type:
Object -
Requires:
database,messenger,parser -
Example:
"io": { … }
The io extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
Type:
Object -
Requires:
parser -
Requires additional options
-
Example:
"log": { … }
The log extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
Type:
String -
Required
-
Example:
"directory": "/path/to/my/logs"
The directory option specifies the directory used to store log files.
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.
-
Type:
Object -
Required by:
audioplayer,io,permissions -
Example:
"messenger": { … }
The messenger extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
Type:
Number(Integer) -
Optional
-
Example:
"textmessagelength": 4000
The textmessagelength option mirrors the murmur.ini server option of the same name, specifying the maximum number of characters that an individual message can contain.
It defaults to the murmur default of 5000.
A non-positive integer ([-Infinity, 0]) will result in an unlimited text message size.
-
Type:
Object -
Example:
"movement": { … }
The movement extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality. It has no options, no dependancies, and no dependents.
Options:
-
Type:
StringorNumber(Integer) -
Optional
-
Example:
"afk": "The AFK Room"
The afk option specifies the name or ID of a given channel in the server for the bot to move to in the event that an afk command is issued.
-
Type:
Boolean -
Required by:
audiostream,io,log,permissions -
Option-less
-
Example:
"parser": true
The parser extension property loads the corresponding Standard Extension. It has no options, and no dependancies.
-
Type:
Object -
Requires:
database,messenger,parser -
Example:
"permissions": { … }
The permissions extension property loads the corresponding Standard Extension, and houses properties pertaining to its functionality.
Options:
-
Type:
Number(Unsigned Integer) -
Optional
-
Example:
"maxlevel": 50
The maxlevel option specifies the maximum level that can be set for a group in the permissions system.
Defaults to 100.
-
Type:
String -
Optional
-
Example:
"superuser": "Jane"
The superuser option specifies the username of a user to temporarily elevate in the permissions system, allowing them to execute any command.
Use with care.
-
Type:
Boolean -
Option-less
-
Example:
"system": true
The system extension property loads the corresponding Standard Extension. It has no options, no dependancies, and no dependents.
-
Type:
Boolean -
Option-less
-
Example:
"time": true
The time extension property loads the corresponding Standard Extension. It has no options, no dependancies, and no dependents.
-
Type:
Boolean -
Option-less
-
Example:
"usersystem": true
The usersystem extension property loads the corresponding Standard Extension. It has no options, no dependancies, and no dependents.
Stumble is created with love.