Rewrite the Default Examples

src/main/resources/scripts/-examples/chest menus.sk

@@ -0,0 +1,55 @@
+
+#
+# An example of opening a chest inventory with an item.
+# Players will be able to take the item out.
+#
+
+command /simple chest:
+    permission: skript.example.chest
+    trigger:
+        set {_chest} to a new chest inventory named "Simple Chest"
+        set slot 0 of {_chest} to apple # Slots are numbered 0, 1, 2...
+
+#
+# An example of listening for click events in a chest inventory.
+# This can be used to create fancy button-style interfaces for users.
+#
+
+command /chest menu:
+    permission: skript.example.menu
+    trigger:
+        set {_menu} to a new chest inventory with 1 row named "Simple Menu"
+        set slot 4 of {_menu} to stone named "Button" # Slots are numbered 0, 1, 2...
+
+on inventory click: # Listen for players clicking in an inventory.
+    name of event-inventory is "Simple Menu" # Make sure it's our menu.
+    cancel event
+    if index of event-slot is 4: # The button slot.
+        send "You clicked the button."
+    else:
+        send "You didn't click the button."
+
+#
+# An example of making and filling a fancy inventory with a function.
+# This demonstrates another way you can use chest inventories.
+#
+# If you wanted to test this example, you could open the result of `makeMenu` to a player.
+#
+
+aliases:
+    menu items = TNT, lava bucket, string, coal, oak planks
+
+function makeMenu(name: text, rows: number) :: inventory:
+    set {_gui} to a new chest inventory with {_rows} rows with name {_name}
+    add {_name} to {inventory names::*}
+    loop {_rows} * 9 times: # Fill the inventory with random items.
+        set slot loop-number - 1 of {_gui} to random item out of menu items
+    return {_gui}
+
+on inventory click: # Listen for players clicking in an inventory.
+    if {inventory names::*} contains name of event-inventory: # Make sure it's our menu.
+        cancel event
+        send "You clicked!"
+
+on inventory close:
+    remove name of event-inventory from {inventory names::*}

src/main/resources/scripts/-examples/commands.sk

@@ -0,0 +1,69 @@
+
+#
+# A very 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 everybody.
+    trigger:
+        broadcast arg-text
+
+#
+# A simple /home command that allows players to set, remove and travel to homes.
+# This command is executable only by players, and has a `correct usage` message.
+# The first argument is required, whereas the second is optional.
+#
+
+command /home <text> [<text>]:
+    description: Set, delete or travel 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-1%<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-1%<reset>" to player
+            else:
+                send "You must specify the name of this home." 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
+
+#
+# An /item command that accepts Skript item aliases.
+# E.g. `/item birch plank, 5 red wool and 17 iron ore`
+# This command has aliases - alternative versions of the command that can be used.
+#
+
+aliases:
+    # Creates an alias `blacklisted` for this list of items.
+    blacklisted = TNT, bedrock, obsidian, mob spawner, lava, lava bucket
+
+command /item <items>:
+    description: Give yourself some items.
+    usage: /item <items...>
+    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
+    trigger:
+        if player has permission "skript.example.item.all":
+            give arguments to player
+        else:
+            loop arguments:
+                if loop-item is not blacklisted:
+                    give loop-item to player
+                else:
+                    send "<red>%loop-item%<reset> is blacklisted and cannot be spawned." to player

src/main/resources/scripts/-examples/events.sk

@@ -0,0 +1,44 @@
+
+#
+# This example listens for players joining and leaving.
+# Alters the default message when they do.
+#
+
+on join:
+    set the join message to "Oh look, %player% joined! :)"
+
+on quit:
+    set the quit message to "Oh no, %player% left! :("
+
+#
+# This example cancels damage for players if they have a specific permission.
+# If they don't, tell them how much damage they took.
+#
+
+on damage:
+    victim is a player
+    if the victim has permission "skript.example.damage":
+        cancel the event # Stops the default behaviour - the victim taking damage.
+    else:
+        send "Ouch! You took %damage% damage." to the victim
+        add damage to {damage::%uuid of victim%::taken}
+        if the attacker is a player:
+            add damage to {damage::%uuid of attacker%::dealt}
+
+#
+# This example allows players to wear specified blocks as hats.
+# Listens for the clicking in the head slot and, if the player has permission, puts the item on their head.
+#
+
+aliases: # An alias for our allowed hat items.
+    custom helmets = iron block, gold block, diamond block
+
+on inventory click:
+    event-slot is the helmet slot of player # Check that player clicked their head slot.
+    inventory action is place all or nothing
+    player has permission "skript.example.helmet"
+    cursor slot of player is custom helmets # Check if the item is in our custom alias.
+    cancel the event
+    set {_old helmet} to the helmet of player
+    set the helmet of player to the cursor slot of player
+    set the cursor slot of player to {_old helmet}

src/main/resources/scripts/-examples/functions.sk

@@ -0,0 +1,51 @@
+
+#
+# A simple broadcasting function example.
+# This demonstrates how to declare and run a simple function.
+#
+
+function sayMessage(message: text):
+    broadcast {_message} # our message argument is available in `{_message}`.
+
+on first join:
+    wait 1 second
+    sayMessage("Welcome, %player%!") # Runs the `sayMessage` function.
+
+#
+# An example of a function with multiple parameters and a return type.
+# This demonstrates how to return a value and use it.
+#
+
+function giveApple(name: text, amount: number) :: item:
+    set {_item} to an apple
+    set the name of {_item} to {_name}
+    set the item amount of {_item} to {_amount}
+    return {_item} # Gives this value to the code that called the function.
+
+command /apple example:
+    permission: skript.example.apple
+    trigger:
+        send "Giving you an apple!"
+        set {_item} to giveApple("Banana", 4)
+        give player {_item}
+
+#
+# An example of a recursive (self-calling) function that is used to repeat a complex task.
+# Please note that self-calling functions can loop infinitely, so use with caution.
+#
+
+function destroyOre(source: block) :: blocks:
+    add {_source} to {_found::*}
+    loop blocks in radius 1 of {_source}:
+        loop-block is any ore
+        break loop-block naturally using an iron pickaxe
+        if {_found::*} does not contain loop-block:
+            add destroyOre(loop-block) to {_found::*}
+    return {_found::*}
+
+command /ore example:
+    permission: skript.example.ore
+    trigger:
+        send "Destroying all connected ore."
+        set {_found::*} to destroyOre(player's target block)
+        send "Destroyed %size of {_found::*}% connected ores!"

src/main/resources/scripts/-examples/loops.sk

@@ -0,0 +1,63 @@
+
+#
+# Examples for two basic loops: one will run a set number of times, the other will run for all elements in a list.
+# Multi-value expressions like `all players` can also be looped.
+#
+
+command /loop example:
+    permission: skript.example.loop
+    trigger:
+        set {_number} to 5
+        loop {_number} times: # Runs `{_number}` times.
+            send "The number is %loop-number%."
+
+        set {_list::*} to "apple", "banana" and "orange"
+        loop {_list::*}: # Runs for each value in the list.
+            send "The word is: %loop-value%"
+
+#
+# Examples for while-loops, which run as long as the condition is true.
+# A while-loop can run indefinitely and freeze the server, so make sure to add a delay or an exit condition.
+#
+
+command /while example:
+    permission: skript.example.while
+    trigger:
+        set {_number} to 5
+        while {_number} is greater than 0:
+            send "The number is %{_number}%"
+            remove a random number between 0 and 2 from {_number}
+        send "Finished counting down."
+
+        while true is true: # this will run forever
+            add "banana" to {_list::*}
+            if size of {_list::*} is 10:
+                exit loop
+        send "The list has %size of {_list::*}% bananas."
+
+#
+# Examples for looping collections of specific types, such as players, blocks and items.
+# This shows how loops can be used to simplify more complex actions.
+#
+
+command /another loop example:
+    permission: skript.example.loop
+    trigger:
+        send "Listing all players:"
+        loop all players: # Remember - player is the command sender, loop-player is the loop value.
+            send " - %loop-player%"
+            if loop-player has permission "skript.example.apple":
+                give loop-player an apple named "Potato"
+
+        set {_items::*} to stone, oak planks and an apple
+        loop {_items::*}:
+            send "%loop-index%. %loop-value%"
+            give loop-value to player
+
+        loop blocks in radius 2 of player:
+            loop-block is a chest
+            loop items of types ore and log: # Loop-block comes from the first loop, loop-item from the second.
+                inventory of loop-block contains loop-item
+                remove loop-item from the inventory of loop-block
+                send "Destroyed a %loop-item%!"
+                exit loop # Exits the item loop.

src/main/resources/scripts/-examples/options and meta.sk

@@ -0,0 +1,43 @@
+
+#
+# A simple example of using an option to make a common value accessible through the file.
+#
+
+options:
+    my server name: Server Name
+    condition: player is alive
+    nice message: "You're alive!"
+
+on join:
+    send "Welcome to {@my server name}"
+    # Options don't need `%...%` since they are raw inputs.
+    if {@condition}: # The raw `player is alive` is copied here during parsing.
+        send {@nice message}
+
+#
+# An example of custom aliases for groups of items.
+# This can be used as a shorthand in code.
+#
+
+aliases:
+    pretty items = iron ingot, gold ingot, diamond
+
+on join:
+    player has permission "skript.example.aliases"
+    give player random item out of pretty items # A random item from our alias.
+
+#
+# An example showing how default variables can be used.
+# These are seen the first time they are loaded, but not overwritten if you change the file copy.
+# They act like default variable values.
+#
+
+variables:
+    score::%player% = 100
+    some variable = "Hello"
+
+command /variable test:
+    permission: skript.example.variables
+    trigger:
+        add 1 to {score::%player%}
+        send {some variable}

src/main/resources/scripts/-examples/timings.sk

@@ -0,0 +1,36 @@
+#
+# This example schedules a repeating action to be run at a time in the *minecraft* world.
+# Every minecraft day at 6 PM, the time is reset to 7 AM, making it always day.
+#
+
+at 18:00:
+    set the time to 7:00
+
+#
+# This example schedules a repeating action. Each time the delay elapses, the trigger will be run.
+# The delay is in real-world time.
+#
+
+every 5 minutes:
+    broadcast "Did you know that five minutes have passed?"
+    loop all players:
+        if loop-player has permission "skript.example.apple":
+            give loop-player an apple
+
+#
+# This example shows how the `wait` effect can be used to delay code being run.
+#
+
+command /wait example:
+    permission: skript.example.wait
+    trigger:
+        send "Waiting for two seconds..."
+        wait 2 seconds
+        send "Finished waiting!"
+
+        send "Counting to five."
+        set {_count} to 0
+        while {_count} is less than 5:
+            wait 3 ticks # Minecraft game ticks: 20 ticks = 1 second.
+            add 0.5 to {_count}
+        send "Finished counting!"