+
Custom Commands in Skript
+
+ Skript allows you to easily create custom commands in your scripts, like the following:
+
+
+ # A simple "broadcast" command for broadcasting the text argument.
+ # This is accessible only to users with the "skript.example.broadcast" permission.
+
+ command /broadcast <text>:
+ permission: skript.example.broadcast
+ description: Broadcasts a message to everyone including console.
+ trigger:
+ broadcast arg-text
+
+
+ That's a simple example, but you can do much more complex things with custom commands!
+ That "/broadcast" command only shows a few of the options you have available when creating a custom command.
+
+
+
Command Pattern
+
+ Here's the full list of features that you can use in your commands. They're all optional, except for the trigger section. We'll explain each one individually below.
+
+
+ command /<command name> <arguments>:
+ aliases:
+ # alternate command names
+ executable by:
+ # players or console
+ usage:
+ # the message that explains how to use the command
+ description:
+ # the command's description
+ permission:
+ # the permission needed to use the command
+ permission message:
+ # the message sent to users without the correct permission
+ cooldown:
+ # a timespan, during which the command can't be used again
+ cooldown message:
+ # the message sent when the command is used before the cooldown is over
+ cooldown bypass:
+ # the permission necessary to bypass the cooldown
+ cooldown storage:
+ # what variable to store the cooldown in
+ trigger:
+ # The code to run goes here.
+
+
+
Command Name
+
+ The command name is what comes immediately after command. It can consist of any characters you want, except for whitespace characters. Additionally, the forward slash (/) in front of the command is optional. This means
+ command /broadcast and command broadcast are the same. Here are a few examples:
+
+
+ command /test-command:
+ trigger:
+ broadcast "Command: /test-command"
+
+ command nickname:
+ trigger:
+ broadcast "Command: /nickname"
+
+ command //set!:
+ trigger:
+ broadcast "Command: //set!"
+
+
+
Arguments
+
+ Arguments follow the command name, and are separated by spaces.
You can make arguments optional by surrounding them with square brackets [], like this: command /kill [all entities].
+
However, the real power in arguments comes from type arguments. These allow a command to take in a type, like command /kill <player>. Type arguments must be surrounded by angle brackets <> and can also be made optional by surrounding them with square brackets: [<player>].
+
The argument can then be referenced in the trigger section by arg-1 or argument 1 or a number of other ways. You can also name type variables like so: <name:type>, which can then be refenced as a local variable: {_name}. Here's the full pattern for arguments:
+
+
+ <name:type=%default value%>
+
+
+ Arguments can be used in a lot of different ways, so I'll provide some examples ranging from the simplest possible to more complex uses.
+
+
+ # this command can be run by "/test" or by "/test command".
+ command /test [command]:
+ trigger:
+ broadcast "Command: /test or /test command"
+
+ # broadcasts the name of the given player. "of" is optional.
+ command /name [of] <player>:
+ trigger:
+ send "Player's name: %arg-1%, %argument 1%, or %player-argument%" to player # here 'player' refers to the player executing the command
+
+ # heals the player in the argument. If no player is given, it will heal the sender.
+ command /heal [<player=%player%>]:
+ trigger:
+ heal argument 1
+
+ # this can be used like /kill zombies, /kill creepers and animals in radius 100 or /kill monsters in the radius 6.
# the radius will default to 20 if isn't entered.
+ command /kill <entity types> [in [the] radius <number = 20>]:
+ executable by: players # this will be explained later on
+ trigger:
+ loop entities in radius arg-2 of player:
+ if loop-entity is arg-1:
+ kill loop-entity
+
+ # sends the text given in the command. If no text is given, it will broadcast the default value of "default text".
+ # note that the text is referenced as {_text input}, rather than arg-1 or similar.
+ command /broadcast [<text input:text="default text">]:
+ trigger:
+ broadcast {_text input}
+
+ # Using optional commands as flags that don't have to all be used
+ # eg:
+ # /give-item stone sword with name Sword in the Stone and with lore Haha, get it?
+ # or
+ # /give-item heart of the sea with lore &bA murky blue orb.
+ command /give-item
- [with name ] [[and] with lore ]:
+ trigger:
+ set {_item} to arg-1
+ # set name
+ if arg-2 is set:
+ set name of {_item} to formatted arg-2
+ # set lore
+ if arg-3 is set:
+ set lore of {_item} to formatted arg-3
+ # give item
+ give player {_item}
+
+
+
Executable By
+
+ Who can execute this command. The options are players, console, or players and console.
+
+
+ command /shutdown:
+ executable by: console
+ trigger:
+ shutdown the server
+
+
+
Aliases
+
+ Aliases are alternate names for your command. For example, the command /teleport could have an alias /tp. Like in the command name, the forward slash (/) is optional.
+
+
+ # this command can be run by "/teleport" or by "/tp".
+ command /teleport <number> <number> <number>:
+ executable by: players
+ aliases: tp
+ trigger:
+ teleport player to location(arg-1, arg-2, arg-3)
+
+
+
Description
+
+ The description of the command. Other plugins can get/show this like /help or /help teleport.
+
+
+
Permission
+
+ The permission required to execute this command. The message sent to players without the proper permission can be customized with the permission message: field.
+
+
+ command /shutdown:
+ permission: server.admin
+ permission message: Only admins can shut down the server!
+ trigger:
+ shutdown the server
+
+
+
Cooldowns
+
+ This field takes a timespan that the player must wait out before executing the command again. The cooldown can be canceled with cancel the cooldown (documentation here).
+ Like with the permission, you can change the default cooldown message with the cooldown message: field. Additionally, you can store the cooldown in a variable with cooldown storage:, in order to store the cooldown even when the server restarts.
+ You can also set up a permission that allows players to bypass the cooldown with bypass cooldown permission:.
+
+
+ command /vote:
+ executable by: players
+ cooldown: 1 day
+ cooldown message: You can only vote once a day!
+ cooldown storage: {vote::cooldown::%uuid of player%}
+ cooldown bypass: vote.cooldown.bypass
+ trigger:
+ add 1 to {vote::players::%uuid of player%}
+
+
+ There are also a number of expressions you can use to interact with the cooldowns of commands. You can get the remaining time with remaining time, the elapsed time with elapsed time, and the total time with cooldown time. You can also get the bypass permission with bypass permission.
+ If you've enabled keep command last usage dates in your config.sk file, you can get the last time the player used the command with last usage date.
+ You can see the full syntax for these expressions here.
+
+
+ # The same vote command but with an improved cooldown message.
+ command /vote:
+ executable by: players
+ cooldown: 1 day
+ cooldown message: You can only vote once a day! You last voted at %last usage%, and it's only been %elapsed time%. Please wait another %remaining time%.
+ cooldown storage: {vote::cooldown::%uuid of player%}
+ cooldown bypass: vote.cooldown.bypass
+ trigger:
+ add 1 to {vote::players::%uuid of player%}
+
+
+
The Trigger Section
+
+ This section is where all the code the command should run is located. I'm sure you're familiar with how it works from the previous examples, but in case you're still unsure, some more examples of commands will be displayed here. You can see these example commands and more in the /plugins/Skript/scripts/-examples/commands.sk file in your server.
+
+
+ command /item <items>:
+ description: Give yourself some items.
+ usage: /item
+ aliases: /i
+ executable by: players
+ permission: skript.example.item
+ cooldown: 30 seconds
+ cooldown message: You need to wait %remaining time% to use this command again.
+ cooldown bypass: skript.example.cooldown.bypass
+ trigger:
+ if player has permission "skript.example.item.all":
+ give arguments to player
+ else:
+ loop arguments:
+ if (TNT, bedrock, obsidian, mob spawner, lava, lava bucket) does not contain loop-item:
+ give loop-item to player
+ else:
+ send "%loop-item% is blacklisted and cannot be spawned." to player
+
+
+
+ command /home <text> [<text>]:
+ description: Set, delete or teleport to your home.
+ usage: /home set/remove <name>, /home <name>
+ permission: skript.example.home
+ executable by: players
+ trigger:
+ if arg-1 is "set":
+ if arg-2 is set:
+ set {homes::%uuid of player%::%arg-2%} to player's location
+ send "Set your home <green>%arg-2%<reset> to <grey>%location of player%<reset>" to player
+ else:
+ send "You must specify a name for this home." to player
+ else if arg-1 is "remove":
+ if arg-2 is set:
+ delete {homes::%uuid of player%::%arg-2%}
+ send "Deleted your home <green>%arg-2%<reset>" to player
+ else:
+ send "You must specify the name of this home." to player
+ else if arg-2 is set:
+ send "Correct usage: /home set/remove <name>" to player
+ else if {homes::%uuid of player%::%arg-1%} is set:
+ teleport player to {homes::%uuid of player%::%arg-1%}
+ else:
+ send "You have no home named <green>%arg-1%<reset>." to player
+
+
+
+ Guide written by sovde, with parts used with permission from blueyescat's tutorial on SkriptHub.
+
+
+