Back to Main Page

Walnutbot supports a wide range of commands used to manage almost all aspects of the bot. Accordingly, the UI mirrors the behaviors of these commands to provide a unified functionality regardless if you are running the bot through the UI, or through sending commands to the bot.

When running commands through Discord, commands take the following format:

?<command> [subcommands..] [args..]

Otherwise, in all other cases, commands take the following format:

<command> [subcommands..] [args..]

Where ? is replaced with command_char, and each subcommand and argument is separated with a space.

For command arguments containing spaces, you can wrap the input string in quotation marks to keep them from being separated. Accordingly, to include quotation marks in an argument, you can use backslashes to escape quotation marks and other backslashes. For example, the command below adds a sound (on a Windows filesystem) called "air quotes" to the Soundboard:

sb add "\"air quotes\"" "~~\\sounds\\air quotes.mp3"

Walnutbot does not inherently parse relative file paths, and instead includes the macros ~~/ and ~~\, which will automatically expand themselves into the folder in which the .jar is running from. The demonstration above used the relative file paths to access the sounds directory, which occupied the same directory as the .jar executable.

Discord users may be of three types of users when running commands accepted by Walnutbot:

• User : The default state for all Discord users.
• Admin : Administrators of the bot, who are typically granted the ability to run more commands.

Commands perms admin add USER#1234 and perms admin remove USER#1234 manage who has Admin permissions.

• Blocked : Users who have blocked access from the bot, and cannot run any commands.

Commands perms blocked add USER#1234 and perms blocked remove USER#1234 manage who is blocked from using the bot.

Each command is associated with a byte that encodes which user permissions are satisfactory for running the command. Accordingly, the value of perm_COMMAND in settings.ini is the byte associated with a particular command (Where COMMAND is replaced with the command in question).

The byte is arranged as follows:

Setting a bit to a 1 means users of that type may run the command. For example, setting the byte to a 2 means only Admins may run the command, while a 3 allows anyone to run the command. Bit 2, called INTERNAL, is always treated as a one, and is exclusively used to describe commands the bot sends to itself.

The following are the commands supported by Walnutbot:

For any of the commands listed here (with the exception of exit), you can run help [command] to learn more about the usage of the command.

Walnutbot is able to parse simple scripts, which are text files where each line is a command the bot recognizes above (with the exception of exit). For example, a script to connect the bot to a particular server and start playing from the lobby.playlist playlist might look like this:

connect "My Server" General
jb dfl load ~~/playlists/lobby.playlist
jb play

The # symbol, if placed at the start of a line, causes the script parser to ignore it as a comment. Comments must occupy their line of the text file.

The @ symbol can be used to introduce timing and delays into your scripts when placed at the start of a line. It supports the following formats:

• @<Time..> Waits for a fixed amount of time. <Time..> is a series of integers suffixed by a unit, which can be one of the following values:

For example, @12m55s250ms waits 12 minutes and 55.25 seconds, while @550ms only waits 0.550 seconds. When using multiple units, you must always list them in order of descending length (starting with hours going down to milliseconds).

• @sb Waits until the Soundboard is no longer playing. This mode is useful for playing multiple sounds in a row, since playing a sound from the Soundboard interrupts the currently-playing one.

• @jb Waits until the Jukebox is no longer handling or loading song requests to place onto the queue. When you make a request to the Jukebox, it takes time to fetch the song from its URL and start playback / store onto the queue. This delay statement is useful for avoiding such concurrency issues.

These delay statements occupy their own line in the script.

When running scripts, output messages are only sent to the bot's internal log rather than printing out messages to the Discord channel, in order to prevent potential issues of flooding the server with a large number of messages.

Cutting a Soundboard sound short (in this case, only 3 seconds long):

sb long_sound
@3s
sb stop

Playing a series of Soundboard sounds in a row:

sb sound_one
@sb
sb sound_two
@sb
sb sound_three

Playing a soundboard sound at a lower volume:

vol sb 10
sb loud_sound
@sb
vol sb 50

Swapping to a new Default List, but play a specific song before pulling random songs from the list:

# Swap to new playlist
jb dfl load ~~/playlists/newlist.playlist

# Empty Jukebox Queue
jb clearqueue

# Ends the currently-running song while keeping the audio player running.
# This will queue up another song, but it is soon to be replaced.
jb skip

# Place starting song into the queue
jb ~~/starting_song.mp3

# Wait for song to load, then skip to it.
@jb
jb skip