GITBOOK-55: 2.7 updates

Author: sovdeeth

README.md

@@ -7,7 +7,7 @@ This gitbook contains a crash course in Skript programming, so if you're here to
 For those of you who are already familiar with Skript, go ahead and use the navigation table on the left to jump to what you're interested in. Currently, only a few pages are actually complete, so you can use the links below to jump to completed tutorials. If you're interested in helping out, the github repo is linked on the right. Pull requests are welcome!
 
 {% hint style="warning" %}
-**Note:** These tutorials are for the current version of the SkriptLang Skript fork (2.6.4) and are not guaranteed to be correct for other versions or forks. This site does not include any tutorials for addons, either.
+**Note:** These tutorials are for the current version of the SkriptLang Skript fork (2.7.0) and are not guaranteed to be correct for other versions or forks. This site does not include any tutorials for addons, either.
 {% endhint %}
 
 ### Completed Pages

SUMMARY.md

@@ -27,17 +27,17 @@
 
 ## Unfinished
 
-* [Syntax Types](unfinished/syntax-types/README.md)
-  * [Reading Syntax](unfinished/syntax-types/reading-syntax.md)
-  * [Events](unfinished/syntax-types/events.md)
-  * [Conditions](unfinished/syntax-types/conditions.md)
-  * [Effects](unfinished/syntax-types/effects.md)
-  * [Literals and Aliases](unfinished/syntax-types/literals-and-aliases.md)
-  * [Expressions](unfinished/syntax-types/expressions.md)
-  * [Sections](unfinished/syntax-types/sections.md)
-* [Auxiliary Guides](unfinished/auxiliary-guides/README.md)
+* [Syntax Types](syntax-types/README.md)
+  * [Reading Syntax](syntax-types/reading-syntax.md)
+  * [Events](syntax-types/events.md)
+  * [Conditions](syntax-types/conditions.md)
+  * [Effects](syntax-types/effects.md)
+  * [Literals and Aliases](syntax-types/literals-and-aliases.md)
+  * [Expressions](syntax-types/expressions.md)
+  * [Sections](syntax-types/sections.md)
+* [Auxiliary Guides](auxiliary-guides/README.md)
   * [Cooldowns](unfinished/auxiliary-guides/cooldowns.md)
-  * [Using Math](unfinished/auxiliary-guides/using-math.md)
-  * [Useful Config Options](unfinished/auxiliary-guides/useful-config-options.md)
-  * [Naming Conventions](unfinished/auxiliary-guides/naming-conventions.md)
-  * [Writing Good Code](unfinished/auxiliary-guides/writing-good-code.md)
+  * [Using Math](auxiliary-guides/using-math.md)
+  * [Useful Config Options](auxiliary-guides/useful-config-options.md)
+  * [Naming Conventions](auxiliary-guides/naming-conventions.md)
+  * [Writing Good Code](auxiliary-guides/writing-good-code.md)

unfinished/auxiliary-guides/README.md renamed to auxiliary-guides/README.md

@@ -21,6 +21,7 @@ Here's the full list of features that you can use in your commands. They're all
 
 ```applescript
 command /<command name> <arguments>:
+    prefix:              # command prefix, defaults to "skript"
     aliases:             # alternate command names
     executable by:       # players or console
     usage:               # the message that explains how to use the command
@@ -122,17 +123,28 @@ command /give-item <item> [with name <text>] [[and] with lore <text>]:
         give player {_item}
 ```
 
-### Executable by
+### Prefix
 
-Who can execute this command. The options are `players`, `console`, or `players and console`.
+A prefix is something **all** commands have, and it goes before the command when Minecraft registers them. You do not have to type this out when executing commands, but you can. The prefix, by default, is `skript`, which means if you leave this blank your command (with its prefix) will look like `/skript:commandName`.
 
 ```applescript
-command /shutdown:
-    executable by: console
-    trigger:
-        shutdown the server
+# This command can be run by "/test" or "/testing_prefix:test"
+command /test:
+   prefix: testing_prefix
+   trigger:
+       broadcast "test"
+       
+# This command can be run by "/test" or "/skript:test"
+command /test:
+   trigger:
+       broadcast "test"
+       
 ```
 
+{% hint style="danger" %}
+If two commands have the same name but different prefixes, only one will be registered.
+{% endhint %}
+
 ### 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.
@@ -146,6 +158,30 @@ command /teleport <number> <number> <number>:
         teleport player to location(arg-1, arg-2, arg-3)
 ```
 
+{% hint style="danger" %}
+Aliases will not overwrite commands registered by other plugins. Say another plugin registers `/spawn`, and you have the following command:
+
+```applescript
+command /tp-to-spawn:
+    aliases: spawn, sp
+    trigger:
+        teleport player to spawn of world
+```
+
+If you run `/spawn`, that other plugin's command will run. You'll need to register a new command with that name and have it run your first command.
+{% endhint %}
+
+### Executable by
+
+Who can execute this command. The options are `players`, `console`, or `players and console`.
+
+```applescript
+command /shutdown:
+    executable by: console
+    trigger:
+        shutdown the server
+```
+
 ### Description
 
 The description of the command. Other plugins can get/show this with `/help`, like `/help teleport`.

unfinished/auxiliary-guides/naming-conventions.md renamed to auxiliary-guides/naming-conventions.md

@@ -156,6 +156,10 @@ Notice how there is no indentation differences, colons, and how the effect comes
 Keep note that there is no `else if` or `else` options with this method.
 {% endhint %}
 
+## If Any and If All
+
+new 2.7 shit
+
 ## Ternary Operators
 
 Ternaries are similar to the `do if` effect, but they're expressions instead. They're designed to return one thing if a condition passes and a different thing if it does not pass. A simple but straight forward example looks something like:

unfinished/auxiliary-guides/useful-config-options.md renamed to auxiliary-guides/useful-config-options.md

@@ -20,6 +20,8 @@ on join:
 
 Now, whenever someone joins, Skript sees `test()` and runs our function, broadcasting "hello world!". The act of telling Skript to run a function is named a **function call**. We just called the function test, or ran it, by using its function call.
 
+Function can be called from anywhere, and at (nearly) any time. You can use them across files! The only restriction is using them in `on load` events. Be careful there. You can also restrict a function to work only in 1 file by using `local`, which we'll get to later.
+
 {% hint style="info" %}
 This might seem a little, well, useless. Why come up with this whole function thing when you can just write the code when you want it? Why couldn't we just write the following?
 
@@ -43,7 +45,7 @@ function functionName():
 
 This is a basic function, like we saw before. The only thing that changes here is the `fuctionName`. The first character must be an alphabetic character, eg a letter, but the following characters can include digits and underscores as well. Common practices are to name functions in `camelCase` or `snake_case`.
 
-However, this is rather limiting. What if we want to do something to an object? Say we have a function called `giveTenApples()`. We don't know who to give to inside the function! This is where **parameters** come into player.
+However, this is rather limiting. What if we want to do something to an object? Say we have a function called `giveTenApples()`. We don't know who to give the apples to! This is where **parameters** come into play.
 
 ### Parameters
 
@@ -134,16 +136,55 @@ Finally, notice the new syntax at the end of the function: `return {_item}`. Thi
 Note that you cannot use `wait` in a function that returns a value. It has to return it instantly, without delay.
 {% endhint %}
 
-### Full Definition
+### Local Functions
+
+The final piece of the puzzle is whether the function is **local or global**. By default, functions are always global. This means you put the function definition in one script file, and you can call the function from any other script! It'll always do the same thing. Sometimes, however, you'll want your function to only be used by 1 script file. Perhaps you want to avoid naming conflicts, where you might accidentally have two functions named `subtract()`. 
+
+This is where **local** functions come into play. By putting `local` in front of your function definition, you can make it so that only _this_ script file can use that function. Any other script file won't even know that it exists.  
+
+```applescript
+[local] function functionName(...)...
+```
+
+{% hint style="warning" %}
+If there's a global function of the same name, your local function will **always** be prioritized over the global version. If that's a bit confusing, here's an example:
+
+```applescript
+# ----------------
+# in script-1.sk
+local function test():
+    broadcast "local!"
+
+on join:
+    test()
+# ----------------
+
+# ----------------
+# in script-2.sk
+function test():
+    broadcast "global!"
+
+on quit:
+    test()
+# ----------------
+```
+
+When a player joins, the `join` event in `script-1.sk` runs. This calls the **local** function `test()`, which broadcasts `"local!"`. 
+
+When a player joins, the `quit` event in `script-2.sk` runs. This can't see the local version of `test()`, so it calls the **global** `test()`, which broadcasts `"global!"`.
+{% endhint %}
+
+## Full Definition
 
 Now that we've explained all the parts, let's show the whole function at once:
 
 ```applescript
-function functionName(parameterName: parameterType = defaultValue) :: returnType:
+[local] function functionName(parameterName: parameterType = defaultValue) :: returnType:
 ```
 
 Hopefully by now you know all these parts, but let's recap:
 
+* **\[local]**: Whether this function is local or global. (global is default)
 * **functionName:** the name of the function, starts with a letter and can use letters, numbers, and underscores
 * **parameterName:** Optional. The name of the parameter, follows the same rules as variable names. Will be accessible as a local variable of the same name in the function.
   * **parameterType:** Required if you have a parameter. Tells Skript what type the parameter will be. Use `object` if you're unsure.

unfinished/auxiliary-guides/using-math.md renamed to auxiliary-guides/using-math.md

@@ -62,7 +62,7 @@ Perfect, right? We save the player's location to a variable, and then when they
 
 Well, this is only partially correct. You see, since global variables are, in fact, global, there's only one of them at any time. So if someone else comes along and does `/sethome`, the `{home}` variable now has their home location, and if you use `/home`, you're getting teleported to their home instead!
 
-To solve this, we need to make the variable unique for each player. The best method to do this is to use the player's uuid as part of the variable name. If you use just `player` or `player's name`, you run the risk of the data no longer being useful when the player changes their name. This is why it's always recommended to use uuids, or enable the config option `use player UUIDs in variable names`, which is explained [here](../../unfinished/auxiliary-guides/useful-config-options.md).
+To solve this, we need to make the variable unique for each player. The best method to do this is to use the player's uuid as part of the variable name. If you use just `player` or `player's name`, you run the risk of the data no longer being useful when the player changes their name. This is why it's always recommended to use uuids, or enable the config option `use player UUIDs in variable names`, which is explained [here](../../auxiliary-guides/useful-config-options.md).
 
 ```applescript
 command /sethome:

unfinished/auxiliary-guides/writing-good-code.md renamed to auxiliary-guides/writing-good-code.md

@@ -6,8 +6,9 @@ Installing Skript is no different from any other plugin. You download the latest
 You should ensure your server meets the requirements for running Skript:
 
 * A Spigot, Paper, or Paper fork server jar. Spigot is the absolute minimum and Skript includes some features that are only accessible when using Paper or a fork of Paper.
-* Minecraft Version. Currently, 2.6.4 works for 1.9 - 1.19.3, but 2.7 will only work for 1.13+. 
+* Minecraft Version. Skript 2.7 works for versions 1.13+. 
   * 1.8 support can be found [here](https://github.com/Matocolotoe/Skript-1.8/releases), but is not official, nor recommended, nor guaranteed to work.
+  * 1.9-1.12 support is limited to old versions of Skript that do not receive updates (2.6.4) 
 {% endhint %}
 
 After you've downloaded the jar file, put it in your `plugins` folder in your server directory. Restart the server and Skript should generate the folder `plugins/Skript`. 

core-concepts/commands.md

@@ -39,7 +39,7 @@ We want a code that fills the player's hunger bar, but we don't know what to wri
 This may seem annoying, or frivolous, but please actually visit the docs. They're your best tool for finding what you need when you have questions.
 {% endhint %}
 
-You should see one result, called Food Level. If you look at the patterns, you can see that `player`, `food`, and `level` all show up in there. It might be a bit hard to read, which is why we have a [syntax reading tutorial](../unfinished/syntax-types/reading-syntax.md), but it's pretty simple once you know how. For now, we'll just look at the example.
+You should see one result, called Food Level. If you look at the patterns, you can see that `player`, `food`, and `level` all show up in there. It might be a bit hard to read, which is why we have a [syntax reading tutorial](../syntax-types/reading-syntax.md), but it's pretty simple once you know how. For now, we'll just look at the example.
 
 ```applescript
 set the player's food level to 10
@@ -202,7 +202,7 @@ set {_tool-text} to "%player's tool%"
 
 ### Using Events
 
-We've been using a command all this time, but events are another extremely useful way to trigger code in Skript. Events are things that happen when certain, well, events happen in the game. Say the player jumps. There's an event for that. Say a furnace burns a piece of coal. There's an event for that. Say a sheep regrows its wool. There's an event for that. You can see all the events at [https://docs.skriptlang.org/events.html](https://docs.skriptlang.org/events.html). You can also learn more about them in the[ Events page](../unfinished/syntax-types/events.md).
+We've been using a command all this time, but events are another extremely useful way to trigger code in Skript. Events are things that happen when certain, well, events happen in the game. Say the player jumps. There's an event for that. Say a furnace burns a piece of coal. There's an event for that. Say a sheep regrows its wool. There's an event for that. You can see all the events at [https://docs.skriptlang.org/events.html](https://docs.skriptlang.org/events.html). You can also learn more about them in the[ Events page](../syntax-types/events.md).
 
 Events are kind of like commands in that they're never indented. Commands and events always start all the way to the left. Since we've been giving players food, let's use an `on consume` event:
 

core-concepts/indentation/conditionals.md

@@ -5,7 +5,7 @@ Syntax is a word that means the set or rules or conventions that define a langua
 {% hint style="info" %}
 Skript has a few main types of syntaxes:
 
-* Top-level syntaxes like events, commands, function definitions, and the option and variables sections.
+* Structures like events, commands, function definitions, and the option and variables sections.
 * Sections and conditions, syntaxes that require some indentation.
 * Effects, expressions, literals and similar syntaxes that make up the fundamental bits of a line of Skript code.
 {% endhint %}
@@ -14,7 +14,7 @@ I will warn you, this is a very long page. Feel free to use the right-side bar t
 
 ## Crash Course in Reading Syntax
 
-You may have looked at the Skript docs and been very confused on how to turn that long string of words and symbols into actual code. The docs can be a bit daunting if you don't know the rules for how to read them. Here's a little crash course, but if you want more detail, head over to [Reading Syntax](../unfinished/syntax-types/reading-syntax.md).
+You may have looked at the Skript docs and been very confused on how to turn that long string of words and symbols into actual code. The docs can be a bit daunting if you don't know the rules for how to read them. Here's a little crash course, but if you want more detail, head over to [Reading Syntax](../syntax-types/reading-syntax.md).
 
 ```applescript
 (message|send [message[s]]) %objects% [to %players/console%] [from %player%]
@@ -35,9 +35,9 @@ message {_something} to player from {_another player}
 
 Hopefully this helps you see how the syntax in the docs can be turned into actual Skript code.
 
-## Top-Level Syntaxes
+## Structures
 
-Top level syntaxes are things you would write to start out a script:
+Structures, or top-level syntaxes, are things you would write to start out a script:
 
 ```applescript
 # an event
@@ -53,11 +53,11 @@ function name(p: player) :: text:
     # run code
 ```
 
-You don't need to know exactly how to use all of these, they'll be explained in greater detail later. **The important part is that none of them are indented.** All top-level syntaxes are just that, top-level. They're never indented. They contain every other bit of code inside of them. If you ever get the error `"All code must be put inside an event"`, you've encountered this principle.
+You don't need to know exactly how to use all of these, they'll be explained in greater detail later. **The important part is that none of them are indented.** All structures are top-level, they stay to the left. They're never indented. They contain every other bit of code inside of them. If you ever get the error `"All code must be put inside an event"`, you've encountered this principle.
 
 ## Fundamental Syntaxes
 
-Top-level syntaxes are pretty straightforward, just write an event, or a command, or whatever. Everything else is a little more complicated, but we'll break it down to the simple bits. The basic structure of a line of Skript code consists of two main elements: Effects and Expressions.
+Structures are pretty straightforward, just write an event, or a command, or whatever. Everything else is a little more complicated, but we'll break it down to the simple bits. The basic structure of a line of Skript code consists of two main elements: Effects and Expressions.
 
 ### Effects
 
@@ -105,7 +105,7 @@ command /give-food <player>:
         give 5 steak to arg-1
 ```
 
-This is a pretty short line, so there isn't too much to dissect. Firstly, we have our top-level syntax, which is a command. We won't be going in to the details of those here. Inside that command, we have this line of code: `give 5 steak to arg-1`. This consists of 1 effect, an alias, and a simple expression.
+This is a pretty short line, so there isn't too much to dissect. Firstly, we have our structure, which is a command. We won't be going in to the details of those here. Inside that command, we have this line of code: `give 5 steak to arg-1`. This consists of 1 effect, an alias, and a simple expression.
 
 The effect, as always, begins our line. Here we're using the Change effect, a very common effect. Specifically, we're using the `give` syntax of the effect:
 
@@ -127,7 +127,7 @@ on right click:
     send "%player's name% and %type of player's tool%" to all players
 ```
 
-Again, we have a top-level element, this time a right-click event. Inside this event, we have a `send` effect.
+Again, we have a structure, this time a right-click event. Inside this event, we have a `send` effect.
 
 ```applescript
 (message|send [message[s]]) %objects% [to %players/console%] [from %player%]