Discord Bot Guide: Fishsticks

From LCARS Database
Jump to: navigation, search



Introduction

This is the official Fishsticks bot documentation. It contains everything a user would need to know about how Fishsticks is to be used and how he works alongside detailed documentation of each of the commands utilized by Fishsticks. Planned development works are covered in on the Fishsticks page.

Fishsticks is a Discord bot, a script running off of the PlDyn Network that is attached to a Discord server. Discord bots like Fishsticks often make use of various commands to relay information to the issuer. Since Fishsticks is specialized for the CCG community, numerous commands and systems have been built into the bot to accommodate for that. Some commands offer information strictly specific to systems relevant to CCG such as community rules, game server IPs, and more. On top of these commands, Fishsticks also offers numerous other advanced commands that are not commonplace such as temporary channels, delayed announcing, music player, and more.

This guide seeks to answer any and all questions concerning the syntax of commands, types of commands, how to use them, and what future plans are in store for Fishsticks.

Quick Links

Command Systems

Fishsticks is not another human; he is a bot. This means that Fishsticks will only respond to very specific commands put into a text channel available to him. Put metaphorically; Fishsticks speaks a ridiculously primitive but complex language and will only answer to things he understands (to a degree). Commands make up the core foundation for majority of Fishsticks' systems and control most of his behavior - including but not limited to Engineering Mode, MattyB Mode*, and Delayed Announcing. Commands are divided up into various sections dependent on permissions level and accessibility. Some commands are merely menus for more commands. While these divided up commands are useful for in-menu aesthetics, they actually do nothing in terms of operation for Fishsticks. For Fishsticks, commands are split into 2 main categories: Active and Passive. Passive commands are also split into two subsets: Hard Coded and Handler-based.

Active Commands

Active commands are based on a prefix. The prefix for Fishsticks is !, the exclamation point. This prefix is used in each and every active command on LCARS based architectures. Fishsticks core commands and most advanced commands are active based, requiring the prefix. Active commands are defined as the following: [prefix][commandID] [parameter] [parameter] --> !commandID [parameter] [parameter] where command IDs are the base foundation commands. Command IDs define what Fishsticks will do and what parameters may be required to carry out the command. Parameters define extra values that may be required along with the ID to be carried out. Parameters may be required or optional. Optional parameters are shown as angled brackets: <> and required parameters are shown as brackets: []. For example, the volume command for Fishsticks' music player has an optional value parameter: !volume <value>. If no value is assigned to the volume command when executed, the current volume Fishsticks is playing music at will be shown. If it is assigned a value, Fishsticks will attempt to change the volume to that value.

Passive Commands

Passive commands are bit more interesting and can be harder to trigger. Due to the two different types of triggers for Passive commands, executing some of them may be harder. Passive commands are commands not executed with a prefix. They are trigger words and phrases that Fishsticks will respond to in a non-formal way, like a chatbot. Hard Coded commands are passive commands that are directly coded into the base foundation script and are usually phrases and more advanced passive commands. These commands trigger responses that can lead to file uploads, targeted responses, and more. Handler-based commands are simpler passive commands that are one word triggers that are usually one line responses that reply to the command author. Words like Hello and Hi.

Command Syntax

As reviewed in Active Commands; prefixes, command IDs, and parameters are required to execute majority of Fishsticks' command infrastructure. This section will review how to use them appropriately.

  • Fishsticks' Prefix is the exclamation mark: !
  • A command ID is the foundation command with no parameters or prefix (ie: volume, status.
  • A parameter is an extra value attached to the end of an ID. Parameters are delineated by spaces and can either be required or optional.
    • Required parameters are delineated by brackets: []
    • Optional parameters are delineated by angled brackets: <>

Correct syntax is an absolute must when using Fishsticks. There are a few exceptions to this however. Commands are always checked prior to execution for validity. Active commands check the ID of the command after the prefix before executing the command function handoff. If the ID is not found, then instead of ignoring the command, Fishsticks will reply to the command issuer with a message saying it failed the command and points them to the help command for a reference. Delayed announcing also has a failed command response when an improper type is declared.

Proper syntax is founded on this template: [prefix][commandID] [parameter] [parameter] [parameter]

Examples:

  • !help - Normal active command, no parameters
  • !volume <value> - Active command with an optional parameter
  • !tempch <maxUsers> [channelName] - Active command with one optional parameter and one required parameter
  • Hello - Passive command
  • ey up - Multi-phrase passive command

Some parameters are terminator parameters; this means that that parameter is the last parameter and is usually a multi-word phrase that may not end. These don't have any following parameters because they are variable in size. A good example of this is the [reason] parameter in the !report command. Reason is the terminator parameter in a set of 3 parameters because the other 2 come before it as the reason parameter can be very lengthy.

System Modes

Fishsticks is equipped to utilize a couple of toggle-able modes that numerous commands check for prior to executing. These modes were implemented based on either developer use or by popular demand for specific functions. These modes are toggled on and off by their respective commands.

Engineering Mode (ENGM)

Engineering Mode is a developer instated mode that is only toggle-able by staff members. ENGM disables a couple of commands that require time based or session sensitive information. This way the bot doesn't lose any potentially vital data via a restart caused by a system restart to apply an update or conduct testing. Some session statistics are disabled while ENGM is enabled because of the same reasons. !status will reflect that in the displayed menu.

ENGM is also shown on Fishsticks' status when enabled.

Fishsticks' ENGM normal layout: !help | V<version>

Fishsticks' ENGM enabled layout: ENGM Enabled | !help

Note that the help menu will actually change depending on ENGM to reflect what commands are allowed whilst ENGM is active.

MattyB Mode (MATB)

MattyB mode is a toggle-able system that is checked by the music player commands prior to executing a song. It was requested by popular demand. Similar to ENGM, MATB will disable certain songs from being played in a manor similar to the song copyright and link check. The mode targets songs composed by the artist MattyB, otherwise known as Matthew David Morris. Known for his rap music and high praise from a CCG member, MATB mode was requested to prevent the toxic songs from being queued in a channel where the consensus was that MattyB songs were not to be played on account of how bad they are. The mode is a state-of-the-art system that checks song information twice and counts the number of attempts made before stopping the member from queueing more songs.

Advanced Systems

The following section will address how Fishsticks' more complex systems work. These include the following; Temporary Channels, Delayed Announcing, Reporting, and the Music Player.

Temporary Channels

Temporary Channels was the first complex system added to Fishsticks. This was added as a priority to assist in CCG users being able create their own channels because this feature was default in the TeamSpeak 3 VOIP application. Discord doesn't have this system and CCG users wanted it. To provide some context, temporary channels are channels that users can create by joining a "channel spawner" and executing an action that will create a custom named channel that other users can join. Once the channel is emptied of all people, the server or system deletes the temporary channel...hence temporary. Fishsticks does this in the same way. TS3's version was to right click on the channel spawner name and activate a context menu dialog. Fishsticks' version is simpler in the fact that you still have to join the channel, but now all you have to do is type somewhere to execute the proper command.

How this works is a little difficult to explain and requires some knowledge of programming and how the DiscordAPI works. Assuming you still wish to know; the best way to explain is with some clarity. Fishsticks, while still being a bot - is a client still, and thanks to how the DiscordAPI works, clients can have variables stored on them. These client stored variables are accessible across the entire bot, not limited to just the script it was declared in. Alongside client based variables, the DiscordAPI employs "triggers" called events. Events are called on every time a certain action happens. Whenever Fishsticks picks up a command, it's because a "message" event was triggered which in turn led Fishsticks to read the message and attempt to read a command. On this same note, there are a plethora of different events that can be triggered and built on.

The temporary channels system is built on this. Before creating the channel, the !tempch command performs a number of checks.

  1. Role permissions check - Make sure you have the proper "clearance" to make a temporary channel
  2. ENGM - if enabled, will not allow you to make a temporary channel
    1. If enabled, checks again for staff and if so, conducts an override.
  3. Assuming you have permissions to create one, it then checks what channel you're attached to
    1. It does this by checking your current voice channel ID with the channel spawner, if it doesn't match, then it alerts you to join the channel spawner.
  4. If all is in order, it proceeds to attempt to create the channel:
    1. Log to console: attempt is being made
    2. Clone the channel spawner channel
    3. Take the newly created channel ID and push to temporary channel array (A list of data) (The array is also a client stored variable)
    4. Log to console: attempt successful
    5. Reply to issuer of success
    6. Set the channel parent to the temporary channel category
    7. Check for the maxUsers value, if it's greater than 1 then set the user limit property to that value
    8. Move the issuer into the newly created channel
    9. Log any fails to the console

Now there is a second part to this. Temporary channels wouldn't be temporary if they didn't go away at some point. This isn't to say that you're going to be booted out of your channel as soon as a timer is up, no no. This is where events come into play as I discussed earlier. The event in question is called voiceStateUpdate which means that any time a user interacts with a voice channel in any way: joins, leaves, or moves - then the event is triggered.

  1. Event triggered
  2. ID of old channel is stored
  3. ID of new channel is stored (null if disconnected)
  4. Check if the ID of the old channel was a part of the temporary channels array (that client stored variable)
  5. If it was, check the number of connections the channel has, if more than 0, ignore the event
  6. If there are no connections: delete the channel and remove the ID from the temporary channels array

See? Simple.

Delayed Announcing

This one is even simpler as it doesn't use event states.

Remember that the command for echo (delayed announcing command) is this: !echo [type] [time] [announcement], where:

  • !echo: is the prefix and command ID
  • [type]: is the divisional role class, changes the announcement mention based on this
  • [time]: is the time in minutes that the bot will wait to post the announcement
  • [announcement]: is the announcement, kind of important.

The way this works is simple:

  1. Check for permissions (this is a staff only command) - if you're not staff, Fishsticks won't budge.
  2. Check for ENGM - this will disable staff from sending ENGM, overrides if bot role found
  3. Reads the 1st parameter [type] for one of the following:
    1. rl: Rocket League -> dispatches with mention to Rocket League role
    2. pubg: Playerunknown's Battlegrounds -> dispatches with mention to PUBG role
    3. ark: Ark: Survival Evolved -> dispatches with mention to Ark: SE role
    4. ow: Overwatch -> dispatches with mention to Overwatch
    5. all or none: Dispatches with a generic @here announcement
  4. If no type is noted, it stops the command and doesn't post anything.
  5. Check for the time parameter. Since the DiscordAPI works with a base time type of miliseconds, it conducts some simple multiplication to change this to minutes.
  6. Then it triggers a function that waits the time from the math result to post an announcement with the mention noted by type to the announcements channel.

Ez-Pz lemon squeezy.

Report

Report is similar to the delayed announcing system in terms of parameter complexity. All it does is take data from the issuer and spit it back out in a clean form in the spot where it needs to be. The form for the report command is: !report [type] [target] [reason]. Let's break it down.

  1. Type is one of three things: server, conduct, or discord. This specifies where the report will be shunted to, like TS or a council member.
  2. Target specifies the thing or person in question. ie Ark Rag Server in the event of a server report for a connection failure. Or a member mention for a conduct report.
  3. Reason is obviously the reason for the report. Be descriptive!
  4. In a condensed way of putting it, Fishsticks picks up all this stuff and slaps it in a rich embed and puts the report somewhere for staff to get a hold of.

Music Player

This one is a doozy and I'll get back to it later.

Command Listing

This is a comprehensive and detailed list of the commands that are employed by Fishsticks. Reference this section should you require assistance with parameters and IDs. This section will also be updated with every change to the command structure.

Active Command List

These are the prefixed commands that control the bulk of Fishsticks.

Normal Commands

Commands that utilize no permissions checks.

  • !channels: displays a description of every channel on the server and its purpose.
  • !divisions: displays a list of CCG divisions and their leaders.
  • !gif: finds and displays a random GIF image.
  • !help: displays the help menu
  • !info [commandID]: accesses the Fishsticks internal codex and displays a help page for the commandID specified.
  • !ips: displays a list of CCG game server IPs
  • !links: displays a list of useful CCG website links
  • !meme: finds and displays a random meme. (NI)
  • !roles: displays a list of the roles utilized by the server
  • !rules: displays the rules of the server
  • !version: Fishsticks' "about" report. Contains useful links and version information.
  • !status: Displays a list of current session variables and statistics.

Divisional Role Commands

Adds or removes the specified divisional role from the issuer.

  • !ark: Ark: SE Role
  • !pubg: PUBG role
  • !rl: Rocket League Role
  • !ow: Overwatch Role

CC Member Commands

You must be an (A)CC Member to utilize these commands.

  • !musichelp: displays a help menu for how to use the Fishsticks Music Player
  • !report [type] [target] [reason]: issues a report to staff concerning a subject matter
    • [type]: is the subject selector parameter. This can be one of 3 things.
      • server: Shunts to Tech Support - use when you're having trouble with a CCG game server. Valid targets are any CCG game server name or IP.
      • conduct: Shunts to Council Members/Moderators - use when there's no staff about and trolls amongst you. Valid targets are a user's name.
      • discord: Shunts to SkyeRangerDelta/Tech Support - use when you're having trouble with anything related to the CCG Discord server. Valid targets are any specific role.
    • [target]: Targets are varied and are specified by your type. See above for valid targets.
    • [reason]: This is why you are submitting the report. State your concern and be descriptive but short and to the point!
  • !tempch <maxUsers> [channelName]: This is the temporary channel command.
    • <maxUsers>: Optional parameter that can specify the maximum number of users allowed in the temporary channel.
    • [channelName]: Required parameter that defines the channel name upon creation.
  • !tempname [channelName]: Changes the name of the current temporary channel to the specified name.
    • [channelName]: Required parameter for the bot to change the name of the channel to.

Administrative Commands

You must be a staff member to utilize these commands.

  • !echo [type] [time] [announcement]: The delayed announcing command. Really useful and makes use of divisional roles by default.
    • [type]: specify one of the following depending on your announcement:
      • ark: Tags Ark: SE role.
      • rl: Tags the Rocket League role.
      • pubg: Tags the Playerunknown's Battlegrounds (PUBG) role.
      • ow: Tags the Overwatch role.
      • all or none: Tags generic @here announcement.
    • [time]: the time in minutes that the bot should wait before posting the announcement.
    • [announcement]: should be fairly obvious what this is; your announcement!
  • !engm: Toggles Engineering Mode.

Music Player Commands

Commands that control the Fishsticks Music Player

  • !musichelp: as if it wasn't obvious enough; shows the help menu for all the music player commands
  • !play [youtubeLink]: Adds a song to the playlist queue. If Fishsticks isn't playing anything, begins playing that song.
    • [youtubeLink]: this is a youtube link. It must be a .com and not a .be (youtube shortlink). Fishsticks will catch you if you if there's something wrong with it.
  • !stop: Stops playback and disconnects Fishsticks from the channel.
  • !skip: Skips to the next song in the queue. This is staff only for numerous reasons.
  • !search [value]: Searches YouTube for a video specified by the value. (NI)
  • !playing: Displays the currently playing song in the queue.
  • !queue: Displays the current queue listing.
  • !volume <value>: Displays the current volume or sets the volume to the specified value.
    • <value>: A number. Yes, it can be a super lengthy decimal. Don't turn it up too loud!

Passive Command List

These commands will trigger just be executing them somewhere. They require no prefix and are considered non-formal. These (for the most part) are not case-sensitive.

  • Hello: Hi!
  • Hi: Hello!
  • ey up: 'Ello! I'm right chuffed you're 'ere.
  • ni hao: Hao!
  • fishsticks: Mmmmm, fishsticks...
  • sdu: Special Developers Unit
  • good music / great music: Did someone say, music?
  • [Badmouth Array]: If you trigger an object in the list, Fishsticks will get surly with you.
  • order 66: Execute all the jedi.
  • fire phasers: Firing all phaser banks sir.

Final Details

As always, if there are any questions concerning Fishsticks. Contact SkyeRangerDelta or fill out the contact form on our main site and select Fishsticks DB from the dropdown. This guide will be updated with any changes made to the bot.

NI denotes a system or command that is not implemented on the system yet. See the Fishsticks page for development plans.


Who's viewing this page? Special:WhosOnline