Commands

Yunite provides an advanced commands system, supporting various options.

Creating a command

  1. Login to the Dashboard, select your server and click on the tab Commands.

  2. To add a new command, click the green New command on the top.

  3. A modal window will pop up with several options. You can find explanations for each field below.

  4. After you filled out the required fields, click the button Save on the bottom of the modal (you might need to scroll down).

Command options

Please find explanations on every option of command below.

Trigger Pattern

In this field, enter the command invocation or a regular expression pattern which should invoke your command.

Simple Invocation

To have Yunite execute actions upon a simple, classic command, please just enter the full invocation string. For example, if you want Yunite to tell the user Hey Jim, please visit the help channel for help! if an user writes !help, enter

!help

into the field.

Regular Expressions

Yunite allows to look for messages matching a specific regular expression pattern. For example, if you want Yunite to send a message if the message contains the word help, write into the field:

rx:^.*help.*$

To use regular expressions, your trigger must always start with rx:, otherwise Yunite handles your input as simple invocation.

Regular expressions will disable command parameters

Let's split this up:

  • rx: This must always be the prefix of regular expressions in Yunite triggers. This has nothing to do with the expression itself, it just tells Yunite that a regular expression follows and should be used to match messages.

  • ^ Indicates the beginning of a message. Yunite always matches the whole message, so we must enter an expression that matches the whole message (and not only a part of it).

  • .* The dot is an alias for any character, that means that any character is allowed here. The star indicates zero or more occurenes of the character before it (which is a dot, meaning any character).

  • help Is the word we are looking for.

  • .* Again, we allow any amount of character after our word.

  • $ indicates the end of the message.

So, we allow from the beginning of the message any amount of any characters, followed by help , again followed by any amount of any characters, followed by the end of the message.This means that the message must contain the word help.

As you might have noticed, regular expressions are extremely powerful. To learn more, visit https://en.wikipedia.org/wiki/Regular_expression. You can test your expressions on https://regex101.com.

Description

In this field, add a small description of your command. This is just for you to organize your commands and is displayed on commands overview. This field does not affect anything else.

Message Deletion

Enable this switch if you want that Yunite deletes the message that invoked the command. This is useful to hide who invoked a command, or even to filter messages using regular expressions, as you can simply enable Message Deletion, but do not configure any reply.

Parameters

If you're not using a regular expression as invocation, you can use command parameters.

Command parameters are additional information, user mentions, texts etc. that a user writes after the invocation. Look at this command for an example:

!announce #testchannel Hello there!

This command has the invocation !announce and two parameters:

  • A channel parameter - in the example #testchannel .

  • A open text parameter - in the example Hello there!

The command above may post an announcement into the given channel with the given text. However, this is just an example. You can perform a very wide variety of tasks with this feature.

First, let's go through a list of available parameter types:

  • Channel. Only accepts a channel mention or channel ID. You can use this parameter in the Channel Message action as target channel or mention it in any message emitted by the command.

  • User. Only accepts a user mention or user ID. You can use this parameter in the Grant / remove role action as target user or mention it in any message emitted by the command.

  • Role. Only accepts a role mention or role ID. You can mention it in any message emitted by the command, but NOT as target of the Grant / remove role action (if you want that, just use the native Discord features to grant roles).

  • Open text. Accepts anyting that has at least one character. You can reuse it in any message emitted by the command. Note: If the last parameter in your parameter list is a Open Text parameter, it will accept a text of any length including spaces; if it is followed by another parameter ( = it is not the last parameter), it will only accept one word or multiple words if they are wrapped in double quotes ( "").

  • Number. Accepts a number (including floating point numbers). You can reuse it in any message emitted by the command.

  • URL. Accepts an URL, e.g. http://google.com. You can reuse it in any message emitted by the command.

  • Regular Expression. Accepts anything that matches the regular expression you enter. For mulitple words, the same as for the Open Text type is valid.

You can add parameters by clicking on the plus button on the right.

Using Parameters in Actions

All added parameters will now be listed, and have an identifier that consists of a dollar sign and a ascending number, e.g $1, $2, $3 ....

If you are not familiar with Actions, please read the Action section below and come back here afterwards.

You can use all dollar-sign parameter identifiers in your text. For example, if you set up a Reply action, and you have a Open Text Parameter with the identifier $1, you can just type $1anywhere in your text and the value of the parameter will be inserted at that points.

This may sound confusing, but is very easy.

Example 1

Let's do an example:

In this example, we have three different parts:

  1. The command invocation is !test.This means the command will react on messages that start with !test.

  2. In the Parameters section, we add a Open Text parameter. This allows us to type any text we want as parameter after our invocation.

  3. We add a Reply Action to make Yunite answer our command with Hey, your parameter is:, followed by the text we enter.

Now, let's save it and test it! This is how this looks like on Discord:

You can apply this example to more complex usecases.

Example 2

Let's do another, more complicated example.

Our goal is to create a command that we invoke like this:

!announce #announcements Hey there, we have a new video online!

The command should now post this message into the channel #annoucements:

Alright, let's get to work. Look at the following image to get an overview - we will go though each point below.

In this configuration, we have six relevant parts:

  1. The command invocation is !announce.This means the command will react on messages that start with !announce.

  2. Now, we need two parameters: One to tell Yunite where it should post the message to, and another that contains the text of our annoucement. In the box at 2, we choose Channel, so our first parameter is a channel.

  3. In the next box, we choose Open text, so our second and last parameter accepts any kind of text.

  4. Now we need to tell Yunite that it should send a message when we invoke the command. To do that, we add a Channel Message action. As target channel, Yunite offers us the parameter we just created at the bottom of the list of our dropdown. You can also search for it by typing in the field. We choose $1 (Parameter) so Yunite sends the message into the channel that the user passes in as first parameter.

  5. Now, click on "Add embed", so Yunite sends an embed with the message. We put Announcement in the title to show users that the message is an annoucement, and write $2 into the description field so Yunite fills in our second parameter as primary content of the embed. Remember: Our second parameter is the Open Text parameter that accepts any kind of text.

  6. As last step, we add a field to the embed, with title Anounced by and {user} as value. Yunite will replace {user}with the mention (e.g. @Joe) of the users that invokes the command.

Done! We now get the result we set as goal above once we invoked the command with a channel and some text.

As you might have noticed, you can do a super wide variety of things with this. If you need help, get in touch with our community on our support server.

Actions

This section is very important for your command. You can configure what Yunite should do after a matching message that invokes the command has been received. You can add any amount of actions you want by clicking on the small plus button on the right.

If you want to drop an action, use the small trash icon in the upper right corner of a actions box.

Available actions are:

Reply

Use the reply action to send a message back to the invoking user. Just enter the message into the big text area. To mention the invoking user, enter {user} somewhere in the message.

To continue our example from above, if you want Yunite to tell the user Hey Jim, please visit the help channel for help! if an user writes !help, enter

Hey {user}, please visit the help channel for help!

Please note that there is API limit of 2000 characters per message.

The small Answer as private message switch on the bottom will send the message as direct message to the user instead of sending it in the channel were the message was invoked. If you want both to send a message in the channel AND send a message via DM, add a second reply action.

Press "Add embed" to make Yunite send an embed in the message. You can configure Yunite to add reactions to the message it sends by click "Add reaction" at the bottom. It supports all default emojis and the custom emojis of your server.

Channel message

Use the channel message action to send a message to any other channel that is not the channel where the message gets invoked.This is useful for logging purposes. Just select a channel in the dropdown menu and enter the message in the big text area. Just like reply actions, channel message actions support mentioning the invoking user with {user}.

Press "Add embed" to make Yunite send an embed in the message. You can configure Yunite to add reactions to the message it sends by click "Add reaction" at the bottom. It supports all default emojis and the custom emojis of your server.

Grant / remove role

Use this action for role management.

To do that, select the role from the dropdown menu. If you want Yunite to remove the role instead of assigning it, switch the Remove the role instead of adding it switch on. You also need to select the target of the operation. If you choose Invoking user, Yunite will assign (or remove) the selected role to/from the user that invokes the command. If you have set up a User parameter, you can also choose this parameter as target; Yunite will assign (or remove) the selected role to/from the user that gets passed into that parameter.

Make sure that Yunite has permissions to assign roles and that Yunites role is above the role you want to assign in the role list.

Cooldowns

Yunite supports cooldowns for commands, preventing spam and abuse of your commands. If the command is invoked, users have to wait the given amount of seconds until they can again invoke the command. You can create one cooldown for each level:

Level

Description

User

If you set an user level cooldown, this means that a particular user must wait the given amount of time. Other users are not affected, but they will receive their own countdown once they invoked the command.

Channel

If you set a channel level cooldown, the command can not be invoked again in the same channel for the given amount of seconds after it has been invoked. This affect all users.

Server

If you set a server level cooldown, the command can not be invoked anywhere on your server for the given amount of seconds after it has been invoked. This affect all users and all channels.

If you want to drop a cooldown, use the small trash icon in the upper right corner of a actions box.

Channels

Set up in which channels your command can be invoked. You have three options.

  1. Leave both Allowed Channels and Blocked Channels empty: This will allow the command in every channel.

  2. Add one or more channels to Allowed Channels: This will allow the command to be invoked in each of those channels, but no other channels.

  3. Add one or more channels to Blocked Channels: This will allow the command in every channel except those channels.

While possible, there is no sense in filling out both fields.

Roles

Set up roles whose users should be allowed to invoked the command or are blocked from executing the command. You have four options:

  1. Leave both Allowed Roles and Blocked Roles empty: This will allow the command for everyone.

  2. Add one or more roles to Allowed Roles: This will allow the command to be invoked for users having one or more of those roles, but not for users that have none of these roles.

  3. Add one or more roles to Blocked Roles: This will allow the command for everyone, but not for users that have at least on of these roles.

  4. Add one or more roles to both Allowed Roles and Blocked Roles: This will allow the command to be invoked for users having one or more of the roles in Allowed Roles as long as don't have any role listed in Blocked Roles.

Do not add @everyone to Blocked Roles as this will result in no one being able to invoke the command, regardless of Allowed Roles.

Patreon

If you enjoy using Yunite, please consider becoming a Patron! Each and every pledge helps to keep this project up and running in the future. Go to: https://patreon.com/yunite‚Äč