# Skript 2.14.0 Today, we are excited to be starting the year off strong with the formal release of Skript 2.14.0! This release includes dozens of major contributions to enhance Skript's existing features, along with a handful of exciting new features. With all of this early spring cleaning, there are some important breaking changes to be aware of, specifically around visual effects and potions. Be sure to look through the **Breaking Changes** section below to see whether your scripts are impacted. In accordance with supporting the last 18 months of Minecraft updates, Skript 2.14.0 supports **Minecraft 1.21.0 to 1.21.11**. Newer versions may also work but were not tested at time of release. **[Paper](https://papermc.io) is required**. Below, you can familiarize yourself with the changes. Additionally, [by clicking here](https://docs.skriptlang.org/docs.html?isNew), you can view the list of new syntax on our documentation site. As always, report any issues to our [issues page](https://github.com/SkriptLang/Skript/issues)! Per our [release model](https://github.com/SkriptLang/Skript/blob/master/CLOCKWORK_RELEASE_MODEL.md), we plan to release 2.14.1 on February 1st. We may release additional pre-releases before then should the need arise. Happy Skripting! ## Major Changes ### Potions Rework Potion syntax has seen a major rework in order to modernize the syntax and make working with potions a breeze. #### Obtaining Potion Effects Just as before, potion effects can be obtained through syntax like: ```applescript set {_potions::*} to the potion effects of the player ``` However, it is now also possible to obtain specific potion effects: ```applescript set {_speed} to the player's speed effect ``` #### Potion Creation Potion creation has been united into a single expression that may optionally be used as a section: ```applescript apply an ambient potion effect of speed of tier 5 to the player for 15 seconds: hide the particles hide the icon ``` The current effect has been replaced with one for applying potion effects. #### Potion Modification The six primary properties of potion effects are supported: `type`, `duration`, `amplifier`, `ambient`, `particles`, and `icon`. All of these properties may be modified in the builder (see above). It is also now possible to modify existing potion effects: ```applescript set the amplifier of {_potion} to 5 apply {_potion} to {_entity} ``` Even better, it is now possible to modify potion effects that are **actively** applied to entities and items: ```applescript set the duration of the player's active speed effect to 5 minutes set the amplifier of the player's slowness effect to 10 make the potion effects of the player's tool infinite ``` #### Hidden Effects Full support for hidden effects has been implemented too. Hidden effects allow a player to have multiple effects of the same type. For example, if a player has speed 1 for 30 seconds, and is then affected by speed 2 for 15 seconds, after those 15 seconds, the player will have 15 seconds of speed 1 remaining. Support for obtaining these effects has been implemented: ```applescript set {_effects::*} to the player's potion effects # only active effects set {_effects::*} to the player's active effects # only active effects set {_effects::*} to the player's hidden effects # only hidden effects set {_effects::*} to the player's active and hidden effects # all effects ``` Just as with active effects, hidden effects support being changed too! Note that modifying a hidden effect may result in it taking precedence over the active effect. #### Comparisons Support for more lenient comparisons has been implemented too: ```applescript player has speed 10 # checks type, amplifier player has a potion effect of speed for 30 seconds # checks type, duration ``` The '[comparison](https://docs.skriptlang.org/docs.html?search=#CondCompare)' condition (as in, `x is y`), can be used for exact comparisons. These comparisons are also used for removals: ``` remove speed 10 from the player's potion effects # removed effects must match type, amplifier remove potion effect of speed for 30 seconds from the player's potion effects # removed effects must match type, duration ``` ### Complete Visual Effect Rework Skript's visual effect system has been in dire need of repair, with limited to no documentation and multiple errors and outdated syntaxes. We've tackled this with a full rework of visual effects, meaning likely all code using visual effects will suffer breaking changes, but it was sadly necessary to get to a better state. Visual effects are now split into 3 different types: particle effects, game effects, and entity effects. **Entity effects** are generally animations that can be played on specific entities, like the `ravager attack animation` effect. **Game effects** compose a variety of built-in game sounds and/or particle effects, like the combined sound+particles of the composter, or the footstep sound for a specific block. **Particle effects** are the standard particles you all know and love from `/particle`. We've overhauled the system to provide easier access to data-driven particles like `dust`; you can now `draw red dust particle at player`! We've also added some syntax to help users better understand and use the admittedly labyrinthine particle api in the form of scale, distribution, and velocity support, rather than simply offset (though you can still set offset manually!). ```applescript # sets the random distribution of the particle set particle distribution of {_flame particle} to vector(1,2,1) # set the velocity of the flame particle. # Note this only works for 'directional particles' and it will override the random distribution # (distribution and special effects like scale/velocity are mutually exclusive) set the velocity of {_flame particle} to vector(1,2,1) # set the scale of the explostion particle. # Note this only works for 'scalable particles' (explosion, sweeping edge) and it will override the random distribution # (distribution and special effects like scale/velocity are mutually exclusive) set the scale of {_explosion particle} to 2.5 ``` Drawing a particle should look more like this, now: ```applescript draw 8 red dust particles at player draw 3 blue trail particles moving to player's target over 3 seconds at player draw an electric spark particle with velocity vector(1,1,1) at player draw 10 flame particles with offset vector(1,0,1) with an extra value of 0 set {_particle} to a flame particle set velocity of {_particle} to vector(0,1,0) draw 10 of {_particle} at player ``` Please note that users of **SkBee and skript-particles** and any other addon dealing with particles will likely need to wait for these addons to be updated to use Skript's particle system instead. ### Named Function Arguments Arguments for functions can now be specified by the name of the argument. This improves clarity with regard to the passed arguments for functions with many parameters. ```applescript function multiply(a: number, b: number) returns number: return {_a} * {_b} on load: assert multiply(1, 2) is 2 assert multiply(a: 1, b: 2) is 2 assert multiply(1, b: 2) is 2 assert multiply(a: 1, 2) is 2 assert multiply(b: 2, a: 1) is 2 ``` Mixing named and unnamed function arguments is allowed, as long as the order of the function parameters is followed, as specified in the function definition. ```applescript function add(a: number, b: number) returns number: return {_a} + {_b} on load: assert multiply(a: 1, 2) is 2 # allowed! assert multiply(1, b: 2) is 2 # allowed! assert multiply(b: 2, 2) is 2 # not allowed! assert multiply(2, a: 2) is 2 # not allowed! ``` ### For-Each Loop For loops are now available by default for all users and no longer require opting into the `for loops` experiment. As a reminder, for loops are a kind of loop syntax that stores the loop index and value in variables for convenience. This can be used to avoid confusion when nesting multiple loops inside each other. ```applescript for {_index}, {_value} in {my list::*}: broadcast "%{_index}%: %{_value}%" ``` ```applescript for each {_player} in all players: send "Hello %{_player}%!" to {_player} ``` All existing loop features are also available in this section. ### Interaction Entities Syntax has been added for working with [interaction entities](https://minecraft.wiki/w/Interaction). There is support for responsiveness and dimensions, along with obtaining the last date an interaction was clicked and the last player to interact. The syntax is available on our [documentation site](https://docs.skriptlang.org/docs.html?search=interaction). ### Recursive Expression Expressions may now return values recursively using `recursive %objects%`, or combined with the `keyed %objects%` expression to return its keys recursively as well. This allows Skript to pass entire structures (i.e. lists) around different contexts, like passing a list to a function while retaining indices and sublists, freely. Note: To avoid cumbersome wording, passing a keyed expression to a function will implicitly pass it recursively as well. For example: ```applescript set {_list::a} to "Hello" set {_list::b} to "World!" set {_list::sublist::c} to "I'm nested!" # This behaves the same as the same as 'print_list(recursive keyed {_list::*})'. # This is only true for function parameter. print_list(keyed {_list::*}) # Prints: # a -> Hello # b -> World! # sublist::c -> I'm nested! function print_list(list: objects): loop {_list::*}: broadcast "%loop-index% -> %loop-value%" ``` For more information, you can review the [pull request](https://github.com/SkriptLang/Skript/pull/8243). ### (API) Registration API Stabilization The modern addon and syntax registration APIs introduced in 2.10 have moved out of their experimental status. As a result, the APIs being replaced have been deprecated and marked for removal. Due to the significant nature of some of these APIs, they will continue to function. They will not be removed without explicit warnings long in advance. Detailed API documentation is being finalized and will be available for the full 2.14 release. For now, the pull request overview can be reviewed for further information about the new APIs: https://github.com/SkriptLang/Skript/pull/6246 ### (API) Type Properties Beta Release In 2.13 we added a new opt-in system for dealing with common properties that are often sources of conflict with addons, like `name of x`, or `length of y`. > These are a way for addons to be able to use the same generic `name of x` or `x contains y` syntaxes that Skript does without causing syntax conflicts. You can register your type (`ClassInfo`) as having a property, such as `Property#NAME` for `name of x`, and Skript will automatically allow it to be used in the `name of` expression. > > For more details on how to do this and what else you can do with type properties, see [the pull request](https://github.com/SkriptLang/Skript/pull/8165). We plan on making a more comprehensive API spec/tutorial once the implementation is solidified, but for now the pull request description should be more than sufficient to try it out. We are now enabling this by default in 2.14 to test it more thoroughly. You will notice a new `use type properties` option in your `config.sk`, which can be set to false if you encounter issues with type properties. We do not anticipate issues, but if you encounter them, there's an easy way out! Please make an issue report on GitHub if you do encounter problems, though. For addon developers, it should be relatively safe to develop with the type properties API now, and we are in the process of preparing detailed documentation for our site. ## ⚠ Breaking Changes - #4183 With the potion system being rewritten, there have been some breaking changes, specifically around potion creation and application. While we have tried to preserve compatibility, it is possible some syntax combinations may no longer work. Please read the dedicated section above and review our documentation site for full syntax details. - #8302 With the visual effects system being rewritten, there have been changes to nearly all patterns. Please read the dedicated section above and review our documentation site for full syntax details. - #8330 The `text opacity` expression for text displays has been modified to make it much more intuitive and easier to use. Previously, opacity was as follows: ```= 0 to 3, fully opaque; 4 to 26, fully transparent; 27 to 127, gradually more opaque until half-opaque at 127; -127 to -1, gradually more opaque from half to fully opaque at -1. defaults to -1. ``` This has been changed to ```= 0 to 3, fully opaque; (this is mojang's fault, don't ask us why!) 4 to 26, fully transparent; 27 to 255, gradually more opaque from transparent to fully opaque at 255. defaults to 255 ``` The expression can still be set to values between -1 and -128, which correspond to 255 to 128 respectively, but the returned value will be positive and add/subtract will not allow opacity to leave the 0-255 range. - [API] #8316/#8355 As part of Registration API stabilization, there have been a few breaking changes: - The `BukkitRegistryKeys` class has been removed. The existing field, `BukkitRegistryKeys.EVENT` is now available at `BukkitSyntaxInfos.Event.KEY`. - `SyntaxOrigin` has been replaced in favor of a more generic `Origin` system. Origins are still constructed in a similar way using the static methods available on the `Origin` interface. - Some methods, such as `patterns` on `SyntaxInfo` now return [SequencedCollection](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/SequencedCollection.html)s rather than regular [Collection](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Collection.html)s. If. you were implementing this interface before, you may need to update your code. - `AddonModule` now has a required `name` method. This also means that it is no longer a [FunctionalInterface](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/FunctionalInterface.html). ## Changelog ### Since pre-2 - #8367 Fixes misformatting in the '[sorted list](https://docs.skriptlang.org/docs.html?search=#ExprSortedList)' expression example. - #8373 Improves the error message when an unknown function is used. ### Additions - #7925 Adds the ability to use local axes when offsetting vectors: `player's location offset by vector(0, 1, 5) using local axes`, where x becomes left/right, y is up/down, and z is forward/back. - #8112 Adds support for specifying named function arguments when calling functions. - #8252 Adds support for obtaining the indices of multiple values at once with the '[indices of value](https://docs.skriptlang.org/docs.html?search=#ExprIndicesOfValue)' expression. - #8261 Adds support for obtaining and changing the BlockData of falling blocks. - #8291 Adds support for working with interaction entities. - #8280 Moves '[for-each loops](https://docs.skriptlang.org/docs.html?search=#SecFor)' out of experimental status. - #8314 Adds two expressions for converting colors to and from hex codes: `hex code of %colors%` and `color from hex code %strings%`. - #8314 Adds two functions for converting numbers/strings to and from various bases like hexadecimal, octal, or binary: `toBase(value: number, base: number)` and `fromBase(value: string, base: number)`. - #8323 Adds support for obtaining the '[respawn reason](https://docs.skriptlang.org/docs.html?search=#ExprRespawnReason)' in a '[respawn](https://docs.skriptlang.org/docs.html?search=#respawn)' event. - #8328 Adds support for Minecraft 1.21.11. ### Changes - #4183 Reworks potion syntax from the ground up. Read more in its dedicated section above. - #8243 Looping using the '[alphabetical sort](https://docs.skriptlang.org/docs.html?search=#ExprAlphabetList)', '[reversed list](https://docs.skriptlang.org/docs.html?search=#ExprReversedList)', '[shuffled list](https://docs.skriptlang.org/docs.html?search=#ExprShuffledList)', '[sorted list](https://docs.skriptlang.org/docs.html?search=#ExprSortedList)', and '[elements](https://docs.skriptlang.org/docs.html?search=#ExprElement)' expressions now allow you to reference the looped index using `loop-index`. - #8280 Marks the Script Reflection experiment as stable (that is, not subject to breaking changes). - #8302 Completely replaces Visual Effects with a new system of particle effects, game effects, and entity effects. Read more in its dedicated section above. - #8320 Adds a negation option to the '[chance](https://docs.skriptlang.org/docs.html?search=#CondChance)' condition: `if chance of 50% fails`. - #8330 Reworks the '[text display opacity](https://docs.skriptlang.org/docs.html?search=#ExprTextDisplayOpacity)' expression to go from 0 to 255, rather than from -128 to 127. - #8335 Improves loop performance for the '[elements](https://docs.skriptlang.org/docs.html?search=#ExprElement)' and '[reversed list](https://docs.skriptlang.org/docs.html?search=#ExprReversedList)' expressions. - #8348 Changes the lang entry for particles effects from `particle effect` to simply `particle` to match its code name and docs name. ### Bug Fixes - #8243 Fixes an error that occurs when attempting to get the sorted indices of a list with empty values (sublists). - #8243 Fixes an error that occurs when calling a function with two lists with values corresponding to the same keys. - #8313 Fixes an issue where resetting an entity's attributes would use the global default instead of the default for that entity type. e.g. resetting player's walk speed to 0.7 instead of 0.1. - #8315 Fixes an issue where the '[look](https://docs.skriptlang.org/docs.html?search=#EffLook)' effect mistakenly required an entity in some cases (even though it was unused). - #8332 Fixes arithmetic operations used for testing showing up on the documentation site. - #8334 Fixes an error that could occur when attempting to change the '[yaw/pitch](https://docs.skriptlang.org/docs.html?search=#ExprYawPitch)' to a non-finite value. - #8343 Fixes an issue where indices of nested lists would contain duplicates. - #8344 Fixes issue with the docs not showing function parameters properly. ### API Changes - #8061 Adds tests for entity AI syntaxes. - #8105 Adds experiments and their descriptions to the `JSONGenerator`. - #8112 Reworks most code related to parsing and calling functions. Some long-deprecated methods and fields have been removed. Please review the pull request overview for further information. - #8224 Migrates the vast majority of syntax examples from the old `@Examples` annotation to the new `@Example` annotations. - #8272 Adds the `appendIf()` utility method to `SyntaxStringBuilder`. - #8274 Supports `w/x/y/z of %object%` via the type property WXYZ, if type properties are enabled. Reorganizes the type property handlers to avoid one massive class. - #8300 Adds new utility methods for working with Fields objects. - #8302 Adds a new `ParticleEffect` class that extends Paper's `ParticleBuilder` class. Addons should use this class when dealing with particles. - #8303 Removes Java 17 tests (1.20.4). - #8314 Adds a new function paramater `Modifier` for default functions, `Modifier.RANGED`. This can be used to limit parameters to a fixed range of values, complete with parse errors if the user uses values out of the range and automatic documentation. - #8314 Ensures that runtime errors emitted during simplification result in parse errors instead. Also fixed an issue where the `RuntimeErrorCatcher` would not properly remove consumers from the manager. - #8316 Marks the new addon and syntax registration APIs as stable. The existing APIs have been deprecated. See the full announcement above for the complete information. - #8317 Adds a customTest gradle task to allow testing of any combination of environments. Parallelizes tests on GitHub. - #8334 Removes the long-deprecated VectorMath utility class. - #8336 Enables type properties by default. Read more in the dedicated section above. - #8355 Updates some properties of SyntaxInfo (and implementations) to use `SequencedCollection` rather than `Collection`. Also adds automatic Priority detection (if not specified) for `SyntaxInfo`. Also adds a required `name` method to `AddonModule` (which is no longer a `FunctionalInterface`). [Click here to view the full list of commits made since 2.13.2](<https://github.com/SkriptLang/Skript/compare/2.13.2...2.14.0>) ## Notices ### Experimental Features Experimental features can be used to enable syntax and other behavior on a per-script basis. Some of these features are new proposals that we are testing while others may have unsafe or complex elements that regular users may not need. While we have tested the available experiments to the best of our ability, they are they are still in development. As a result, they are subject to change and may contain bugs. Experiments should be used at your own discretion. Additionally, example scripts demonstrating usage of the available experiments can be found [here](https://github.com/SkriptLang/Skript/tree/master/src/main/resources/scripts/-examples/experimental%20features). <details> <summary>Click to reveal the experiments available in this release</summary> ### Queue **Enable by adding `using queues` to your script.** A collection that removes elements whenever they are requested. This is useful for processing tasks or keeping track of things that need to happen only once. ```applescript set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} # "hello" is now removed broadcast the first element of {queue} # "world" is now removed # queue is empty ``` ```applescript set {queue} to a new queue of all players set {player 1} to a random element out of {queue} set {player 2} to a random element out of {queue} # players 1 and 2 are guaranteed to be distinct ``` Queues can be looped over like a regular list. ### Script Reflection **Enable by adding `using script reflection` to your script.** This feature includes: - The ability to reference a script in code. - Finding and running functions by name. - Reading configuration files and values. ### Local Variable Type Hints **Enable by adding `using type hints` to your script.** Local variable type hints enable Skript to understand what kind of values your local variables will hold at parse time. Consider the following example: ```applescript set {_a} to 5 set {_b} to "some string" ... do stuff ... set {_c} to {_a} in lowercase # oops i used the wrong variable ``` Previously, the code above would parse without issue. However, Skript now understands that when it is used, `{_a}` could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types. Please note that this feature is currently only supported by **simple local variables**. A simple local variable is one whose name does not contain any expressions: ```applescript {_var} # can use type hints {_var::%player's name%} # can't use type hints ``` ### Runtime Error Catching **Enable by adding `using error catching` to your script.** A new `catch [run[ ]time] error[s]` section allows you to catch and suppress runtime errors within it and access them later with `[the] last caught [run[ ]time] errors`. ```applescript catch runtime errors: ... set worldborder center of {_border} to {_my unsafe location} ... if last caught runtime errors contains "Your location can't have a NaN value as one of its components": set worldborder center of {_border} to location(0, 0, 0) ``` ### Damage Sources **Enable by adding `using damage sources` to your script.** > Note that `type` has been removed as an option for the '[damage cause](https://docs.skriptlang.org/docs.html?search=#ExprDamageCause)' expression as `damage cause` and `damage type` now refer to different things. Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more. Below is an example of what damaging using custom damage sources looks like: ```applescript damage all players by 5 using a custom damage source: set the damage type to magic set the causing entity to {_player} set the direct entity to {_arrow} set the damage location to location(0, 0, 10) ``` For more details about the syntax, visit [damage source](https://docs.skriptlang.org/docs.html?search=damage%20source) on our documentation website. ### Equippable Components **Enable by adding `using equippable components` to your script.** Equippable components allows retrieving and changing the data of an item in the usage as equipment/armor. Below is an example of creating a blank equippable component, modifying it, and applying it to an item: ```applescript set {_component} to a blank equippable component: set the camera overlay to "custom_overlay" set the allowed entities to a zombie and a skeleton set the equip sound to "block.note_block.pling" set the equipped model id to "custom_model" set the shear sound to "ui.toast.in" set the equipment slot to chest slot allow event-equippable component to be damage when hurt allow event-equippable component to be dispensed allow event-equippable component to be equipped onto entities allow event-equippable component to be sheared off allow event-equippable component to swap equipment set the equippable component of {_item} to {_component} ``` Changes can be made directly on to the existing equippable component of an item whether using the item itself or the retrieved equippable component ```applescript set the equipment slot of {_item} to helmet slot set {_component} to the equippable component of {_item} allow {_component} to swap equipment ``` For more details about the syntax, visit [equippable component](https://docs.skriptlang.org/docs.html?search=equippable%20component) on our documentation website. </details> ### New Documentation Site Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons. While this site is still under heavy development, the beta is available for viewing at https://beta-docs.skriptlang.org. ### Help Us Test We have an [official Discord community](https://discord.gg/ZPsZAg6ygu) for beta testing Skript's new features and releases. ### Thank You Special thanks to the contributors whose work was included in this version: - @APickledWalrus - @bluelhf - @Efnilite - @erenkarakal - @F1r3w477 ⭐ First contribution! ⭐ - @Fusezion - @isuniverseok-ua ⭐ First contribution! ⭐ - @sovdeeth - @TheLimeGlass - @TheMug06 - @UnderscoreTud As always, if you encounter any issues or have some minor suggestions, please report them at https://github.com/SkriptLang/Skript/issues. If you have any bigger ideas or input for the future of Skript, you can share those too at https://github.com/SkriptLang/Skript/discussions.