Commands

Yunite provides an advanced custom commands system, supporting various options like parameters, actions, cooldowns, and more.

Creating a simple new command#

  1. On the dashboard, open the commands page.
  2. Click on "New ungrouped command".
  3. A modal window will pop up with several options. You can find explanations for each field below.
  4. After you filled the required fields, click the button Save on the modal's bottom.

Command options#

Below you will find explanations on every command option.

Invocation Pattern#

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

Simple Invocation#

To have Yunite execute actions upon a simple, classic command, please 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 a user writes !help, enter the following into the field and do not tick the RegEx box:

!help

Regular Expressions#

Yunite can look for messages matching a specific regular expression pattern. To use regular expressions, tick the RegEx box on the left.

caution

If you use regular expressions, the command parameters and DM replies will be disabled.

For example, if you want Yunite to send a message if the message contains the word help, write into the field:

^.*help.*$

In this example, we are using the following regular expression syntax:

  • ^ Indicates the beginning of a message. Yunite always matches the whole message, so we must enter an expression that matches the entire message (and not only a part of it).
  • .* The dot is an alias for any character, which means that any character is allowed here. The star indicates zero or more occurrences 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 number of any characters, followed by help, again followed by any number of any characters, followed by the end of the message. This means that the message must contain the word help.

tip

As you might have noticed, regular expressions are extremely powerful. To learn more, visit, for example this article. You can test your expressions here.

Description#

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

Delete message#

Tick this box if you want Yunite to delete the message that invoked the command. This is particularly useful if you are using the commands module as a chat filter.

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.

tip

If you want to drop an action, use the small trash icon in the upper right corner of an 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 continue our example from above, if you want Yunite to tell the user Hey Jim, please visit the help channel for help! if a user writes !help, enter:

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

The small Send as DM box will send the message as a direct message to the user instead of sending it in the channel where 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. DMs are disabled if using regular expressions.

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 clicking "Add reaction" at the bottom. It supports all default emojis and the custom emojis of your server.

info

You can use variables in your texts. Here's a list:

  • {user} mentions the invoking user.
  • {user.id} finds the ID of the invoking user.
  • {user.name} shows the username of the invoking user.
  • {user.nick} shows the invoking user's nickname on the server or - if none is set.
  • {user.fullname} shows the full username including discriminator (stuff like #1234).
  • {user.createdAt} shows the timestamp at which the user signed up on Discord for the first time.
  • {user.joinedAt} shows the timestamp at which the user joined the server.
  • {server} shows the name of the server.
  • {server.id} shows the ID of the server.
  • {server.memberCount} shows the current member count of the server.
  • {channel} mentions the channel in which the command got invoked.
  • {channel.name} shows the name of the channel in which the command got invoked.
  • {channel.id} shows the ID of the channel in which the command got invoked.
  • {#1234567890} mentions the channel with the ID 1234567890.
  • {#my-channel} mentions the channel with the name my-channel.
  • {&1234567890} mentions the role with the ID 1234567890.
  • {&my-role} mentions the role with the name my-role.
  • {@1234567890} mentions the user with the ID 1234567890.
  • {#joe} mentions the user with the name joe.

All variables that should mention someone or something fall back to printing the entity's name if mentions are unavailable, for example, in footers.

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 messages support variables. Just look into the list above.

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 clicking "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, click on the "Remove" type on the right.

You also need to select the target of the operation in the Grant to menu. If you choose Invoking user, Yunite will assign/remove the selected role to/from the user that invokes the command. If you have set up a User parameter (we learn about parameters below), you can also choose this parameter as a target; Yunite will assign (or remove) the selected role to/from the user that gets passed into that parameter.

caution

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

Apply permission overrides#

Yunite can apply permission overrides to a channel as a command action.

This is an extremely powerful feature that allows opening or closing channels using a simple command without having any opinions on how to close/lock a channel as other bots do. It also adds the possibility to allow your moderators to lock channels without giving them more native Discord permissions.

First, to use them, select the target channel type, either a text channel or a voice channel.

Second, choose the channel you want to affect - this can either be a fixed one or a text channel parameter (we learn about parameters later on).

Third, please select the permission overrides Yunite should apply to the channel. If you are using a fixed channel, you can sync the current state from Discord using the bottom button. The interface to do that has been cloned from Discord, so it should be easy to use.

Parameters#

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

Command parameters are a numerical or other measurable factor forming one of a set that defines a system or sets its operation conditions.

Look at this command for an example:

!announce #testchannel Hello there!

This command consists of the invocation !announce and two parameters:

  • A channel parameter - in the example #testchannel.
  • An open text parameter - in the example Hello there!.

The command above may, for example, post a formatted announcement into the given channel with the given text. However, this is just an example. You can perform a 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 the 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 a target user or mention the user 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 the target of the Grant / remove role action (if you want that, use the native Discord features to grant roles).
  • Open text. Accepts anything 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 an Open Text parameter, it will accept a text of any length, including spaces; if another parameter follows it (= 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 multiple words, the same rules as for the Open Text type apply.

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 an ascending number, e.g. $1, $2, $3 ...

danger

If you are not familiar with Actions, please read the Action section above and return here afterward.

Similarly to variables, you can use all dollar-sign parameter identifiers in your texts in the Reply action and the Channel Message action. For example, if you set up a Reply action and have an Open Text Parameter with the identifier $1, you can type $1 anywhere in your text, and the value of the parameter will be inserted at these points. In other actions like the Grant / Remove role action, or the Apply permission overrides action, you can use parameters as a target. That way, you can build fully customized, super-powerful utility commands.

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:

LevelDescription
UserIf you set a 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 cooldown once they invoke the command.
ChannelIf 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 affects all users.
ServerIf 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 affects all users and all channels.
info

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

Permissions#

You can set allowed and blocked roles and allowed and blocked channels for your commands to limit who can use them. The same rules and hints as for system commands apply: See here