Parsing Blocks

Parsing blocks interact with the tag invocation and affect the tag’s output in Discord.

Restriction Blocks

The following blocks allow for restriction of tags behind roles or channels, or setting tag cooldowns.

Require Block

class TagScriptEngine.RequireBlock(*args, **kwargs)[source]

The require block will attempt to convert the given parameter into a channel or role, using name or ID. If the user running the tag is not in the targeted channel or doesn’t have the targeted role, the tag will stop processing and it will send the response if one is given. Multiple role or channel requirements can be given, and should be split by a “,”.

Usage: {require(<role,channel>):[response]}

Aliases: whitelist

Payload: response, None

Parameter: role, channel

Examples:

{require(Moderator)}
{require(#general, #bot-cmds):This tag can only be run in #general and #bot-cmds.}
{require(757425366209134764, 668713062186090506, 737961895356792882):You aren't allowed to use this tag.}

Blacklist Block

class TagScriptEngine.BlacklistBlock(*args, **kwargs)[source]

The blacklist block will attempt to convert the given parameter into a channel or role, using name or ID. If the user running the tag is in the targeted channel or has the targeted role, the tag will stop processing and it will send the response if one is given. Multiple role or channel requirements can be given, and should be split by a “,”.

Usage: {blacklist(<role,channel>):[response]}

Payload: response, None

Parameter: role, channel

Examples:

{blacklist(Muted)}
{blacklist(#support):This tag is not allowed in #support.}
{blacklist(Tag Blacklist, 668713062186090506):You are blacklisted from using tags.}

Cooldown Block

class TagScriptEngine.CooldownBlock(*args, **kwargs)[source]

The cooldown block implements cooldowns when running a tag. The parameter requires 2 values to be passed: rate and per integers. The rate is the number of times the tag can be used every per seconds.

The payload requires a key value, which is the key used to store the cooldown. A key should be any string that is unique. If a channel’s ID is passed as a key, the tag’s cooldown will be enforced on that channel. Running the tag in a separate channel would have a different cooldown with the same rate and per values.

The payload also has an optional message value, which is the message to be sent when the cooldown is exceeded. If no message is passed, the default message will be sent instead. The cooldown message supports 2 blocks: key and retry_after.

Note

Delimiter for the parameter (<rate> and <per>): | or ~. Where | takes priority over ~.

Usage: {cooldown(<rate>|<per>):<key>|[message]}

Payload: key, message

Parameter: rate, per

Examples:

{cooldown(1|10):{author(id)}}
# the tag author used the tag more than once in 10 seconds
# The bucket for 741074175875088424 has reached its cooldown. Retry in 3.25 seconds."

{cooldown(3|3):{channel(id)}|Slow down! This tag can only be used 3 times per 3 seconds per channel. Try again in **{retry_after}** seconds."}
# the tag was used more than 3 times in 3 seconds in a channel
# Slow down! This tag can only be used 3 times per 3 seconds per channel. Try again in **0.74** seconds.

Message Blocks

Message blocks modify the tag’s output.

Embed Block

class TagScriptEngine.EmbedBlock(*args, **kwargs)[source]

An embed block will send an embed in the tag response. There are two ways to use the embed block, either by using properly formatted embed JSON from an embed generator or manually inputting the accepted embed attributes.

JSON

Using JSON to create an embed offers complete embed customization. Multiple embed generators are available online to visualize and generate embed JSON.

Important

Embed Limits are:
- Title: 256 characters
- Description: 4096 characters
- Footer: 2048 characters
- Author: 256 characters
- Field name: 256 characters
- Field value: 1024 characters
The total length of the embed must not exceed 6000 characters.

Usage: {embed(<json>)}

Payload: None

Parameter: json

Examples:

Example 1:
{embed({"title":"Hello!", "description":"This is a test embed."})}

Example 2:
{embed({
    "title":"Here's a random duck!",
    "image":{"url":"https://random-d.uk/api/randomimg"},
    "color":15194415,
    "fields": [
        {
            "name": "Fun Fact",
            "value": "Ducks are birds that are well-adapted to life in and around water.",
            "inline": false
        }
    ]
})}

Manual

The following embed attributes can be set manually:

title
description
color
url
thumbnail
image
author
footer
field - (See below)

Adding a field to an embed requires the payload to be split by ;;, | or ~ into either 2 or 3 parts. The first part is the name of the field, the second is the text of the field, and the third optionally specifies whether the field should be inline.

Usage: {embed(<attribute>):<value>}

Payload: value

Parameter: attribute

Examples:

{embed(color):#37b2cb}
{embed(title):Rules}
{embed(description):Follow these rules to ensure a good experience in our server!}
{embed(field):Rule 1|Respect everyone you speak to.|false}
{embed(author):Mod Team|{author(avatar)}}
{embed(footer):Thanks for reading!|{guild(icon)}}

Both methods can be combined to create an embed in a tag. The following tagscript uses JSON to create an embed with fields and later set the embed title.

Caution

The JSON block acts as a base for the embed.
Since blocks are processed in order, the JSON block must come before any manual attribute blocks.
The manual attributes are used to modify or add to the embed created by the JSON block.

{embed({
    "description": "This is a test description.",
    "fields": [
        {
            "name": "Field 1",
            "value": "field description",
            "inline": false
        }
    ]
})}
{embed(title):My embed title}

Redirect Block

class TagScriptEngine.RedirectBlock(*args, **kwargs)[source]

Redirects the tag response to either the given channel, the author’s DMs, or uses a reply based on what is passed to the parameter.

Usage: {redirect(<"dm"|"reply"|channel>)}

Payload: None

Parameter: “dm”, “reply”, channel

Examples:

{redirect(dm)}
{redirect(reply)}
{redirect(#general)}
{redirect(626861902521434160)}

Delete Block

class tags.blocks.DeleteBlock(*args, **kwargs)[source]

Delete blocks will delete the invocation message if the given parameter is true. If there is no parameter i.e. {delete} it will default to true.

Usage: {delete([bool])

Aliases: delete, del

Payload: None

Parameter: bool, None

Examples:

{delete}
{delete({args(1)}==delete)}
{del}

React Block

class tags.blocks.ReactBlock(*args, **kwargs)[source]

The react block will react with up to 5 emoji to the tag response message. If the name used is reactu, it will react to the tag invocation instead. The given emoji can be custom or unicode emoji. Emojis can be split with “,”.

The block accepts emojis being passed to the parameter or the payload, but not both.

Usage: {react(<emoji,emoji>):[emoji,emoji]}

Aliases: reactu

Payload: emoji

Parameter: emoji

Examples:

{react(🅱️)}
{react(🍎,🍏)}
{react(<:kappa:754146174843355146>)}
{reactu:🅱️}

Utility Blocks

The following utility blocks extend the power of tags that interface with bot commands.

Command Block

class TagScriptEngine.CommandBlock(limit: int = 3)[source]

Run a command as if the tag invoker had ran it. Only 3 command blocks can be used in a tag.

Usage: {command:<command>}

Aliases: c, com, command

Payload: command

Parameter: None

Examples:

{c:ping}
# invokes ping command

{c:ban {target(id)} Chatflood/spam}
# invokes ban command on the pinged user with the reason as "Chatflood/spam"

Override Block

class TagScriptEngine.OverrideBlock(*args, **kwargs)[source]

Override a command’s permission requirements. This can override mod, admin, or general user permission requirements when running commands with the Command Block. Passing no parameter will default to overriding all permissions.

In order to add a tag with the override block, the tag author must have Manage Server permissions.

This will not override bot owner commands or command checks.

Usage: {override(["admin"|"mod"|"permissions"]):[command]}

Payload: command

Parameter: “admin”, “mod”, “permissions”

Examples:

{override}
# overrides all commands and permissions

{override(admin)}
# overrides commands that require the admin role

{override(permissions)}
{override(mod)}
# overrides commands that require the mod role or have user permission requirements

Silent Block

class tags.blocks.SilentBlock(*args, **kwargs)[source]

The silent block silences the usual output of any command being used in a command block. This is useful when you want a tag to execute commands without their output appearing in the channel.

Usage: {silent([bool])}

Aliases: silent, silence

Payload: None

Parameter: bool (optional, defaults to true)

Example:

{silent}
{c:ping}
# The ping command runs but its output is suppressed.

{silent(true)}
{c:ping}
# Same as above, explicitly enabled.

{silent(false)}
{c:ping}
# The ping command runs and its output is shown normally.

Reply Block

class tags.blocks.ReplyBlock(*args, **kwargs)[source]

Reply blocks are conditional components that trigger bot responses to be replied when the specified parameter is set to True. If no parameter is provided {reply}, it’ll default to True.

Usage: {reply([bool])}

Payload: None

Parameter: bool, None

Examples:

{reply}
{reply(False)}

Allowed Mentions Block

class tags.blocks.AllowedMentionsBlock(*args, **kwargs)[source]

The “allowed mentions” block attempts to enable mentioning of roles. Passing no parameter enables mentioning of all roles within the message content. However passing a role name or ID to the block parameter allows mentioning of that specific role only. Multiple role name or IDs can be included, separated by a comma “,”. By default, mentioning is only triggered if the execution author has “manage server” permissions. However, using the “override” keyword as a payload allows mentioning to be triggered by anyone.

Usage: {allowedmentions(<role, None>):["override", None]}

Aliases: mentions

Payload: “override”, None

Parameter: role, None

Examples:

{allowedmentions}
{allowedmentions:override}
{allowedmentions(@Admin, Moderator):override}
{allowedmentions(763522431151112265, 812949167190048769)}
{mentions(763522431151112265, 812949167190048769):override}