Rewrite the Default Examples (#4605)

* Replace examples.

* Add example for options and aliases.

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

Co-authored-by: Jake Ben-Tovim <jacobbentovim@gmail.com>

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

Co-authored-by: Jake Ben-Tovim <jacobbentovim@gmail.com>

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

Co-authored-by: Jake Ben-Tovim <jacobbentovim@gmail.com>

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

* Apply suggestions from code review

* Implement some suggested changes

* Correct some formatting and add better inventory example.

* Add text formatting example (sorbonbon)

* Fix small issue with destroy ore command

* Fix argument errors

Co-authored-by: Jake Ben-Tovim <jacobbentovim@gmail.com>
Co-authored-by: APickledWalrus <apickledwalrus@gmail.com>

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

@@ -0,0 +1,62 @@
+
+#
+# An example of opening a chest inventory with an item.
+# Players will be able to take the item out.
+#
+
+command /simplechest:
+    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...
+        open {_chest} to player
+
+#
+# An example of listening for click events in a chest inventory.
+# This can be used to create fancy button-style interfaces for users.
+#
+
+command /chestmenu:
+    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...
+        open {_menu} to player
+
+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, and a safe way of listening to specific ones.
+#
+
+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}
+    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}
+
+command /fancymenu:
+    permission: skript.example.menu
+    trigger:
+        set {_menu} to makeMenu("hello", 4)
+        add {_menu} to {my inventories::*} # Prepare to listen to this inventory.
+        open {_menu} to player
+
+on inventory click: # Listen for players clicking in any inventory.
+    if {my inventories::*} contains event-inventory: # Make sure it's our menu.
+        cancel event
+        send "You clicked slot %index of event-slot%!"
+
+on inventory close: # No longer need to listen to this inventory.
+    {my inventories::*} contains event-inventory
+    remove event-inventory from {my inventories::*}

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

@@ -0,0 +1,71 @@
+
+#
+# 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-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
+
+#
+# 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 argument to player
+        else:
+            loop argument:
+                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,55 @@
+
+#
+# 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 /appleexample:
+    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::*}
+    break {_source} naturally using an iron pickaxe
+    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 /oreexample:
+    permission: skript.example.ore
+    trigger:
+        if player's target block is any ore:
+            send "Destroying all connected ore."
+            set {_found::*} to destroyOre(player's target block)
+            send "Destroyed %size of {_found::*}% connected ores!"
+        else:
+            send "<red>You must be looking at an ore block!"

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

@@ -0,0 +1,75 @@
+
+#
+# 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 /loopexample:
+    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 /whileexample:
+    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."
+
+command /dowhileexample:
+    permission: skript.example.dowhile
+    trigger:
+        set {_number} to a random integer between 0 and 6 # The player will get 1 to 3 apples.
+        do while {_number} is greater than 3: # This will always run at least once, even if `{_number} is less than or equal to 3`.
+            give the player an apple
+            remove 1 from {_number}
+        send "Finished giving out apples!"
+
+        do while true is false: # This will run once - the condition is checked AFTER the code is executed.
+            send "I will run only once!"
+
+#
+# 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 /anotherloopexample:
+    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,44 @@
+
+#
+# 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 /variabletest:
+    permission: skript.example.variables
+    trigger:
+        add 1 to {score::%player%}
+        send "Your score is now %{score::%player%}%."
+        send {some variable}

src/main/resources/scripts/-examples/text formatting.sk

@@ -0,0 +1,38 @@
+#
+# This example is for colours and formatting in Skript.
+# Skript allows the old-style Minecraft codes using `&`, like &0 for black and &l for bold.
+# You can also use <> for colours and formats, like `<red>` for red and `<bold>` for bold
+#
+# In Minecraft 1.16, support was added for 6-digit hexadecimal colors to specify custom colors other than the 16 default color codes.
+# The tag for these colors looks like this: <##hex code> e.g. `<##123456>`
+#
+
+command /color:
+    permission: skript.example.color
+    trigger:
+        send "&6This message is golden."
+        send "<light red><bold>This message is light red and bold."
+        send "<##FF0000>This message is red."
+
+#
+# Other formatting options are also available.
+# You can create clickable text, which opens a website or execute a command, or even show a tool tip when hovering over the text.
+#
+
+command /forum:
+    permission: skript.example.link
+    trigger:
+        send "To visit the website, [<link:https://google.com><tooltip:click here>click here<reset>]"
+
+command /copy <text>:
+    permission: skript.example.copy
+    trigger:
+        # Insertion: when the player shift clicks on the message, it will add the text to their text box.
+        # To use variables and other expressions with these tags, you have to send the text as `formatted`.
+        send formatted "<insertion:%arg-1%>%arg-1%"
+
+command /suggest:
+    permission: skript.example.suggest
+    trigger:
+        send "<cmd:/say hi>Click here to run the command /say hi"
+        send "<sgt:/say hi>Click here to suggest the command /say hi"