-
-
Notifications
You must be signed in to change notification settings - Fork 414
Add tutorial for commands to Docs site. #4653
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
Show all changes
20 commits
Select commit
Hold shift + click to select a range
d607e02
Initial commit of the command tutorial
sovdeeth 1b10ed8
Remove duplicate section
sovdeeth a0a09d3
Moved to commands.html and removed highlight,js
sovdeeth c8223f3
Update commands.html
sovdeeth 6fd1cfe
Update tutorials.html
sovdeeth b8ade25
Removed header/body tags from commands.html
sovdeeth c4a60f2
add one more example from the rewritten command examples
sovdeeth 3ab1bff
applying suggestions from review
sovdeeth 7596a3b
Permission gained
sovdeeth 69a814a
Apply suggestions from code review
sovdeeth 44eae02
Update commands.html
sovdeeth ce921a1
Reorganizing and adding "exec by" stuff
sovdeeth 4a6edb3
accidentally added a test file in here somehow
sovdeeth b33f851
Merge branch 'master' into docs-command-tutorial
sovdeeth e05d0d0
Merge branch 'master' into docs-command-tutorial
sovdeeth a6d242e
Apply simple changes from code review
sovdeeth 81d2141
Cooldown Expressions
sovdeeth d1f223c
Missed a few "permissions"
sovdeeth 74cffdc
Merge branch 'master' into docs-command-tutorial
Moderocky 0f21b05
Useful use case of optional arguments
sovdeeth File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,262 @@ | ||
| <h1 id="nav-title">Custom Commands</h1> | ||
|
|
||
| <div id="content-no-docs" class="no-left-panel" style="padding-top: 32px;"> | ||
| <h2 class="title">Custom Commands in Skript</h2> | ||
| <p class="subtitle"> | ||
| Skript allows you to easily create custom commands in your scripts, like the following: | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| # A simple "broadcast" command for broadcasting the text argument.<br> | ||
| # This is accessible only to users with the "skript.example.broadcast" permission.<br> | ||
| <br> | ||
| command /broadcast <text>: <br> | ||
| permission: skript.example.broadcast <br> | ||
| description: Broadcasts a message to everyone including console. <br> | ||
| trigger: <br> | ||
| broadcast arg-text <br> | ||
| </div> | ||
| <p class="subtitle"> | ||
| 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. | ||
| </p> | ||
|
|
||
| <h2 class="title">Command Pattern</h2> | ||
| <p class="subtitle"> | ||
| 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. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| command /<command name> <arguments>:<br> | ||
| aliases: | ||
| # alternate command names <br> | ||
| executable by: | ||
| # players or console <br> | ||
| usage: | ||
| # the message that explains how to use the command <br> | ||
| description: | ||
| # the command's description <br> | ||
| permission: | ||
| # the permission needed to use the command <br> | ||
| permission message: | ||
| # the message sent to users without the correct permission <br> | ||
| cooldown: | ||
| # a timespan, during which the command can't be used again <br> | ||
| cooldown message: | ||
| # the message sent when the command is used before the cooldown is over <br> | ||
| cooldown bypass: | ||
| # the permission necessary to bypass the cooldown <br> | ||
| cooldown storage: | ||
| # what variable to store the cooldown in <br> | ||
| trigger: <br> | ||
| # The code to run goes here. | ||
| </div><br> | ||
|
|
||
| <h2 class="title">Command Name</h2> | ||
| <p class="subtitle"> | ||
| The command name is what comes immediately after <code>command</code>. It can consist of any characters you want, except for whitespace characters. Additionally, the forward slash (<code>/</code>) in front of the command is optional. This means | ||
| <code>command /broadcast</code> and <code>command broadcast</code> are the same. Here are a few examples: | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| command /test-command:<br> | ||
| trigger: <br> | ||
| broadcast "Command: /test-command"<br> | ||
| <br> | ||
| command nickname:<br> | ||
| trigger: <br> | ||
| broadcast "Command: /nickname"<br> | ||
| <br> | ||
| command //set!:<br> | ||
| trigger: <br> | ||
| broadcast "Command: //set!"<br> | ||
| </div> | ||
|
|
||
| <h2 class="title">Arguments</h2> | ||
| <p class="subtitle"> | ||
| <a href="/expressions.html#ExprArgument">Arguments</a> follow the command name, and are separated by spaces.<br>You can make arguments optional by surrounding them with square brackets <code>[]</code>, like this: <code>command /kill [all entities]</code>. | ||
| <br>However, the real power in arguments comes from type arguments. These allow a command to take in a <a href="/classes.html">type</a>, like <code>command /kill <player></code>. Type arguments must be surrounded by angle brackets <code><></code> and can also be made optional by surrounding them with square brackets: <code>[<player>]</code>. | ||
| <br> The argument can then be referenced in the trigger section by <code>arg-1</code> or <code>argument 1</code> or a <a href="/expressions.html#ExprArgument">number of other ways</a>. You can also name type variables like so: <code><name:type></code>, which can then be refenced as a local variable: <code>{_name}</code>. Here's the full pattern for arguments: | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| <name:type=%default value%> | ||
| </div> | ||
| <p class="subtitle"> | ||
| 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. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| # this command can be run by "/test" or by "/test command".<br> | ||
| command /test [command]:<br> | ||
| trigger: <br> | ||
| broadcast "Command: /test or /test command"<br> | ||
| <br> | ||
| # broadcasts the name of the given player. "of" is optional.<br> | ||
| command /name [of] <player>:<br> | ||
| trigger: <br> | ||
| send "Player's name: %arg-1%, %argument 1%, or %player-argument%" to player # here 'player' refers to the player executing the command<br> | ||
| <br> | ||
| # heals the player in the argument. If no player is given, it will heal the sender.<br> | ||
| command /heal [<player=%player%>]:<br> | ||
| trigger: <br> | ||
| heal argument 1<br> | ||
| <br> | ||
| # this can be used like /kill zombies, /kill creepers and animals in radius 100 or /kill monsters in the radius 6. <br> # the radius will default to 20 if isn't entered.<br> | ||
| command /kill <entity types> [in [the] radius <number = 20>]:<br> | ||
| executable by: players # this will be explained later on<br> | ||
| trigger: <br> | ||
| loop entities in radius arg-2 of player:<br> | ||
| if loop-entity is arg-1:<br> | ||
| kill loop-entity<br> | ||
| <br> | ||
| # sends the text given in the command. If no text is given, it will broadcast the default value of "default text". <br> | ||
| # note that the text is referenced as {_text input}, rather than arg-1 or similar.<br> | ||
| command /broadcast [<text input:text="default text">]:<br> | ||
| trigger: <br> | ||
| broadcast {_text input}<br> | ||
| <br> | ||
| # Using optional commands as flags that don't have to all be used<br> | ||
| # eg: <br> | ||
| # /give-item stone sword with name Sword in the Stone and with lore Haha, get it?<br> | ||
| # or<br> | ||
| # /give-item heart of the sea with lore &bA murky blue orb.<br> | ||
| command /give-item <item> [with name <text>] [[and] with lore <text>]:<br> | ||
| trigger:<br> | ||
| set {_item} to arg-1<br> | ||
| # set name<br> | ||
| if arg-2 is set:<br> | ||
| set name of {_item} to formatted arg-2<br> | ||
| # set lore<br> | ||
| if arg-3 is set:<br> | ||
| set lore of {_item} to formatted arg-3<br> | ||
| # give item<br> | ||
| give player {_item}<br> | ||
| </div> | ||
|
|
||
| <h2 class="title">Executable By</h2> | ||
| <p class="subtitle"> | ||
| Who can execute this command. The options are <code>players</code>, <code>console</code>, or <code>players and console</code>. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| command /shutdown:<br> | ||
| executable by: console<br> | ||
| trigger: <br> | ||
| shutdown the server<br> | ||
| </div> | ||
|
|
||
sovdeeth marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <h2 class="title">Aliases</h2> | ||
| <p class="subtitle"> | ||
| Aliases are alternate names for your command. For example, the command <code>/teleport</code> could have an alias <code>/tp</code>. Like in the command name, the forward slash (<code>/</code>) is optional. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| # this command can be run by "/teleport" or by "/tp".<br> | ||
| command /teleport <number> <number> <number>:<br> | ||
| executable by: players<br> | ||
| aliases: tp<br> | ||
| trigger: <br> | ||
| teleport player to location(arg-1, arg-2, arg-3)<br> | ||
| </div> | ||
|
|
||
| <h2 class="title">Description</h2> | ||
| <p class="subtitle"> | ||
| The description of the command. Other plugins can get/show this like /help or /help teleport. | ||
| </p> | ||
|
|
||
| <h2 class="title">Permission</h2> | ||
| <p class="subtitle"> | ||
| The permission required to execute this command. The message sent to players without the proper permission can be customized with the <code>permission message:</code> field. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| command /shutdown:<br> | ||
| permission: server.admin<br> | ||
| permission message: Only admins can shut down the server!<br> | ||
| trigger: <br> | ||
| shutdown the server<br> | ||
| </div> | ||
|
|
||
| <h2 class="title">Cooldowns</h2> | ||
sovdeeth marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <p class="subtitle"> | ||
| This field takes a timespan that the player must wait out before executing the command again. The cooldown can be canceled with <code>cancel the cooldown</code> (<a href="/effects.html#EffCancelCooldown">documentation here</a>). | ||
| Like with the permission, you can change the default cooldown message with the <code>cooldown message:</code> field. Additionally, you can store the cooldown in a variable with <code>cooldown storage:</code>, 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 <code>bypass cooldown permission:</code>. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| command /vote:<br> | ||
| executable by: players<br> | ||
| cooldown: 1 day<br> | ||
| cooldown message: You can only vote once a day!<br> | ||
| cooldown storage: {vote::cooldown::%uuid of player%}<br> | ||
| cooldown bypass: vote.cooldown.bypass<br> | ||
| trigger: <br> | ||
| add 1 to {vote::players::%uuid of player%}<br> | ||
| </div> | ||
| <p class="subtitle"> | ||
| There are also a number of expressions you can use to interact with the cooldowns of commands. You can get the remaining time with <code>remaining time</code>, the elapsed time with <code>elapsed time</code>, and the total time with <code>cooldown time</code>. You can also get the bypass permission with <code>bypass permission</code>.<br> | ||
| If you've enabled <code>keep command last usage dates</code> in your <code>config.sk</code> file, you can get the last time the player used the command with <code>last usage date</code>.<br> | ||
| You can see the full syntax for these expressions <a href="https://docs.skriptlang.org/expressions.html#ExprCmdCooldownInfo">here</a>. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| # The same vote command but with an improved cooldown message.<br> | ||
| command /vote:<br> | ||
| executable by: players<br> | ||
| cooldown: 1 day<br> | ||
| 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%.<br> | ||
| cooldown storage: {vote::cooldown::%uuid of player%}<br> | ||
| cooldown bypass: vote.cooldown.bypass<br> | ||
| trigger: <br> | ||
| add 1 to {vote::players::%uuid of player%}<br> | ||
| </div> | ||
|
|
||
| <h2 class="title">The Trigger Section</h2> | ||
| <p class="subtitle"> | ||
| 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 <code>/plugins/Skript/scripts/-examples/commands.sk</code> file in your server. | ||
| </p> | ||
| <div class="box skript-code-block left-margin"> | ||
| command /item <items>:<br> | ||
| description: Give yourself some items.<br> | ||
| usage: /item <items...><br> | ||
| aliases: /i<br> | ||
| executable by: players<br> | ||
| permission: skript.example.item<br> | ||
| cooldown: 30 seconds<br> | ||
| cooldown message: You need to wait %remaining time% to use this command again.<br> | ||
| cooldown bypass: skript.example.cooldown.bypass<br> | ||
| trigger:<br> | ||
| if player has permission "skript.example.item.all":<br> | ||
| give arguments to player<br> | ||
| else:<br> | ||
| loop arguments:<br> | ||
| if (TNT, bedrock, obsidian, mob spawner, lava, lava bucket) does not contain loop-item:<br> | ||
| give loop-item to player<br> | ||
| else:<br> | ||
| send "<red>%loop-item%<reset> is blacklisted and cannot be spawned." to player | ||
| </div> | ||
| <br> | ||
| <div class="box skript-code-block left-margin"> | ||
| command /home <text> [<text>]:<br> | ||
| description: Set, delete or teleport to your home.<br> | ||
| usage: /home set/remove <name>, /home <name><br> | ||
| permission: skript.example.home<br> | ||
| executable by: players<br> | ||
| trigger:<br> | ||
| if arg-1 is "set":<br> | ||
| if arg-2 is set:<br> | ||
| set {homes::%uuid of player%::%arg-2%} to player's location<br> | ||
| send "Set your home <green>%arg-2%<reset> to <grey>%location of player%<reset>" to player<br> | ||
| else:<br> | ||
| send "You must specify a name for this home." to player<br> | ||
| else if arg-1 is "remove":<br> | ||
| if arg-2 is set:<br> | ||
| delete {homes::%uuid of player%::%arg-2%}<br> | ||
| send "Deleted your home <green>%arg-2%<reset>" to player<br> | ||
| else:<br> | ||
| send "You must specify the name of this home." to player<br> | ||
| else if arg-2 is set:<br> | ||
| send "Correct usage: /home set/remove <name>" to player<br> | ||
| else if {homes::%uuid of player%::%arg-1%} is set:<br> | ||
| teleport player to {homes::%uuid of player%::%arg-1%}<br> | ||
| else:<br> | ||
| send "You have no home named <green>%arg-1%<reset>." to player | ||
| </div> | ||
|
|
||
| <p style="padding-bottom: 20px"> | ||
| Guide written by <a href="https://github.com/sovdeeth">sovde</a>, with parts used with permission from <a href="https://skripthub.net/tutorials/10">blueyescat's tutorial</a> on <a href="https://skripthub.net/">SkriptHub</a>. | ||
| </p> | ||
| <div style="padding-top: 32px;"></div> <!-- Space --> | ||
| </div> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.