Restricting a command

This page covers the entries that restrict a declared command: where it runs, who can run it, its cooldown, and how to react when a check turns it away. You're assumed to have a bot named "my-bot" logged in.

How checks work

on discord command used fires first, before any check below; cancelling it stops the command outright. Past that point, checks run in a fixed order and the first one that fails stops the rest:

An entry you don't set is skipped, not enforced as "none allowed": no roles means any role, no executable in means every channel type. permission message, cooldown message and usage message are the only entries that send a reply by themselves; the other three reasons send nothing unless on discord command failed replies too.

discord command admin:
    prefixes: "!"
    permissions: administrator
    permission message: "You need to be an administrator, %event-user%."
    trigger:
        reply with "you are an admin"

Where a command runs

executable in takes a list of words and narrows the channel types the command answers in. Leaving it out is the same as listing every word below.

discord command dmonly:
    prefixes: "!"
    executable in: dm
    trigger:
        reply with "this only works in DMs"

Who can run it

roles, permissions and bots each narrow who may run the command; set as many as you need, they all have to pass. roles takes a comma-separated list of role names or ids:

discord command vip:
    prefixes: "!"
    roles: VIP, 1335575588307734528
    trigger:
        reply with "you have the role"

permissions takes Skript's permission literals, the same administrator used above; list several with a comma: permissions: kick members, ban members. An unrecognised permission name is a load error, not a runtime one (see Errors below).

bots scopes the command to one or more bots by name; on any other bot the command is refused with wrong bot instead of running:

discord command onlyminimal:
    prefixes: "!"
    bots: my-bot
    trigger:
        reply with "handled by %event-bot%"

Cooldowns

cooldown takes a timespan and blocks reuse until it elapses; cooldown scope decides who shares that timer, and defaults to user.

A use is only marked once every check above has passed, argument parsing included: a call refused for invalid arguments never starts the cooldown.

discord command slow:
    prefixes: "!"
    cooldown: 10 seconds
    cooldown message: "Wait %remaining cooldown% before using %name of event-discordcommand% again."
    trigger:
        reply with "slow command used"

discord command guildslow:
    prefixes: "!"
    cooldown: 10 seconds
    cooldown scope: guild
    trigger:
        reply with "guild-wide cooldown started"

Reacting to a refusal

on discord command failed fires for every refused call, whichever check stopped it. failure reason tells which one:

remaining cooldown is only set for a cooldown failure; it's a timespan, ready for %remaining cooldown%. Use this event to reply for the three reasons that have no configured message:

on discord command failed:
    send "[CMD] failed %name of event-discordcommand%: %failure reason% (remaining %remaining cooldown%)" to console
    if failure reason is "wrong channel":
        reply with "wrong channel for %name of event-discordcommand%"
    if failure reason is "missing role":
        reply with "you lack the role for %name of event-discordcommand%"
    if failure reason is "wrong bot":
        reply with "not for %event-bot%"

Errors you may see