Skript 2.12.0

2.12.0 is here! Please excuse the later release time, Pickle's on vacation! We've got a bounty of new features, changes, and bug fixes for you in Skript 2.12, along with early support for 1.21.6/7.

Below, you can familiarize yourself with the changes. Additionally, by clicking here, you can view the list of new syntax on our documentation site. As always, report any issues to our issues page!

Per our release model, we plan to release 2.12.1 on August 1st. We may release emergency patches before then should the need arise.

We would also like to welcome a new addition to the team, @Absolutionism!

Happy Skripting!

Changes to Supported Versions and Platforms

Back in 2.10, we switched to supporting the last three major versions. While reasonable at the time, Mojang has continued to make significant changes between minor versions and seems to have shyed away from incrementing the major version counter. In order to reduce the development burden of supporting so many versions with different features, as of 2.13 (next release) we have decided to switch to supporting the last 18 months of Minecraft releases. This means as of 2.13, Skript will support 1.20.4 and newer. 2.14 will be 1.21.0 and newer. We hope this change will allow us to modernize Skript more quickly and more fully support new systems like item components going forward. To clarify, 2.12 still supports 1.19.4+. These changes will affect 2.13 and later.

In the same vein, Paper has recently completed its fork away from Spigot. We have aimed to maintain support for both versions so far, but we are running into issues where the API differences between Paper and Spigot are becoming too great. It is not feasible for us to develop two parallel versions of Skript, and as a result, we will be dropping support for Spigot starting with 2.13. We encourage the small portion of our users who are still using Spigot to upgrade to Paper if possible.

Major Changes

Ephemeral Variables

Ephemeral variables (or ram vars, or memory vars) are now fully implemented by default for all users. These are global variables that are not saved between restarts. To make a variable ephemeral, add a hyphen (-) to the start of its name: {-var}. These variables are about 2.5x faster to change compared to normal global variables. You do not need to do anything to enable them.

Function Overloading

[!NOTE] The script reflection experiment, which includes syntax for dynamically referencing and executing functions, does not yet support working with overloaded functions.

Function overloading enables creating functions that have the same name but different parameters types/parameter counts.

:::applescript
function send_welcome(p: player):
    send_welcome({_p}, false)

function send_welcome(p: player, first_time: boolean):
    if {_first_time} is true:
            send "Welcome to our server for the first time, %name of {_p}%!" to {_p}
        else:
            send "Welcome back to our server, %name of {_p}%!" to {_p}

Local Variable Type Hints (Experimental)

[!NOTE] This feature is currently experimental and can be used by enabling the type hints experiment.

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 (Experimental)

[!NOTE] This feature is currently experimental and can be used by enabling the error catching experiment.

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 (Experimental)

[!NOTE] This feature is currently experimental and can be used by enabling the damage sources experiment.

[!CAUTION] Note that type has been removed as an option for the 'damage cause' 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 on our documentation website.

Contributing Updates

We are now allowing contributors to release their code contributions under the more-permissive MIT License. For more information, please review our LICENSING.md file.

⚠ Breaking Changes

• When using index of "a" in "b", values that do not appear in the second string will now return none instead of the previous -1.

• The is enchanted with condition now looks for exact levels instead of the specified level or better. Old behavior can be replicated with if {_item} is enchanted with sharpness 2 or better. Some examples:

  :::applescript if {_item} is enchanted with sharpness 2 # only passes for sharpness 2. Previous behavior allowed sharpness of 2 or greater to pass. if {_item} is enchanted with sharpness 2 or better # sharpness 2+ if {_item} is enchanted with sharpness 2 or worse # sharpness 2 or 1 if {_item} is enchanted with sharpness # sharpness of any level - An infinite timespan literal was added, meaning Timespan math operations can now result in an infinite timespan value (just like numbers). - The parsing behavior of the 'amount' expression has changed. Given an expression like amount of {a::*}, "b", it was before parsed as (amount of {a::*}), "b", but it is now parsed as amount of ({a::*}, "b"). Use parentheses as necessary to clarify your intent. - For the old 'beacon values' expression, beacon is now a required keyword for the range and tier expressions. - The remove all changer for the 'custom model data' expression has been removed. It functioned the same as remove. - head has been removed as an option for the 'player skull' expression as head of player conflicts with the 'head location' expression. - type has been removed as an option for the 'damage cause' expression as damage cause and damage type now refer to different things. - The 'load world' effect now requires world. - The API method RegistryParser#getAllNames has been removed in favor of RegistryParser#getCombinedPatterns (from the PatternedParser interface). - API methods for the since documentation field have changed on SkriptEventInfo: - SkriptEventInfo#getSince() (String) -> SkriptEventInfo#getSince() (String[]) - BukkitSyntaxInfos.Event.since() (String) -> BukkitSyntaxInfos.Event.since() (Collection<String>) - BukkitSyntaxInfos.Event.Builder.since(String) -> BukkitSyntaxInfos.Event.Builder.addSince(String) - (API) Syntax ordering is no longer based on registration order when a priority is shared. This may expose syntax conflicts if this behavior was depended on.

Changelog

Additions

• [#4154] Adds support for boolean values to the 'toggle' effect and an 'inverse boolean' expression to obtain the inverse of a boolean (at long last).
• [#6902] Adds a 'buried item' expression and a 'dusted stage' expression for working with brushable blocks.
• [#7495] Adds ephemeral variables (starting with -) which are cleared when the server restarts.
• [#7561] Adds an 'except' expression which provides a simple way to filter values from a list.
• [#7658] Adds an 'On-screen kick message' expression to get and change the on-screen message that appears when a user is kicked, usable in the kick event.
• [#7685] Adds support for the Catalan language (thanks to @TwistedWar3713, @Lukarius11, and @ItzDuck364 for their language insights).
• [#7707] Adds support for the 'item cooldown' syntax to respect cooldown groups (cooldown components) defined on items.
• [#7738] Adds an 'exact item' expression that acts like creative-mode middle-click, copying the block's data exactly.
• [#7745] Adds a 'vault display item' event for when a trial vault displays an item.
• [#7746] Adds a 'villager career change' event for when villagers change professions along with the ability to obtain the reason why.
• [#7748] Adds a condition and effect for working with shivering striders.
• [#7751] Adds support for function overloading, enabling functions to have the same name but different parameters.
• [#7803] Adds the word along as an option in the 'push' effect: push player along vector(1,1,1) at speed 3.
• [#7807] Adds support for using the expanded custom model data system to the 'custom model data' expression. Note that remove all changer support has been removed.
• [#7808] Adds a warning for ambiguous command arguments where expressions like arg-1 could be misinterpreted as (arg) - 1.
• [#7823] Adds experimental syntax for catching and suppressing runtime errors. See the available experiments section below for more information.
• [#7830] Adds support for printing errors to the 'enable/disable/unload/reload script' effect.
• [#7841] Adds support for syntax simplification, which enables parse time pre-computation of some syntax that will always have the same result.
• [#7846] Adds support for the new 1.21.5 pig variants.
• [#7851] Adds a warning for when literals that can be interpeted as multiple types are used and Skript cannot determine the intended type.
• [#7858] Adds error messages for experimental syntax that is used when the experiment is disabled.
• [#7866] Adds support for cow variants.
• [#7868] Adds support for chicken variants.
• [#7892] Adds experimental support for local variable type hints. This allows Skript to determine what kind of values your local variables may hold at parse time. See the available experiments section below for more information.
• [#7897] Expands the 'arrow attached block' expression to support multiple blocks, as arrows may be attached to multiple blocks. The existing single expression has been deprecated on versions where the plural expression is available, as it is unreliable.
• [#7903] Adds a 'harvest block' event for when a block is harvested (berry bushes, glowberries, etc.).
• [#7905] Adds a new event-entity type event value for entity related events.
• [#7906] Adds saddle and dynamic equipment slot support to the 'armor slot' expression.
• [#7909] Adds a 'keyed' expression which allows explicitly passing/including the keys of an expression alongside its values. For example, you can preserve/include keys (indices) when setting a list variable to another list variable or when providing a list variable as the argument of a function.
• [#7914] Adds a 'first empty slot in inventory' expression to obtain the first empty slot in inventories.
• [#7933] Adds scientific notation (e.g. 1.23E4, 10e-10) to numbers.
• [#7942] Function names can now start with an underscore.
• [#7949] Adds support for resetting sent block changes from the 'send block change' effect.
• [#7950] Adds support to the 'push' effect for pushing/pulling entitites towards/away from a location.
• [#7951] Adds support for deleting the 'spawner type' of a spawner.
• [#7956] Adds support for an 'infinite' timespan. Note that now, just like numbers, math operations for Timespans can now result in an infinite timespan value.

• 7957/#7982/#7983 Implement early support for 1.21.6/7.

• [#7961] Adds support for literals in the 'amount' expression. Note that, as a result, the parsing behavior has now changed. Given an expression like amount of {a::*}, "b", it was before parsed as (amount of {a::*}), "b", but it is now parsed as amount of ({a::*}, "b"). Use parentheses as necessary to clarify your intent.

Changes

• [#7325] Improves the 'indices of value' expression to allow accessing the index/position of a specific value in a list. Note that values that are not found in a list or a string now return none instead of -1.
• [#7729] Splits the 'beacon values' expression into multiple new expressions: 'beacon effects', 'beacon range', and 'beacon tier'. Note that the range and tier expressions now require beacon in their syntax.
• [#7742] Cleans up the 'hash' expression and adds SHA-384 and SHA-512. A warning is now printed when using the MD5 algorithm.
• [#7816] The 'is enchanted' condition now looks for exact enchantments, with or better and or worse added as newly available comparison options.
• [#7840] Improves the existing comparisons for offline players and offline players-strings.
• [#7913] The aliases folder will now be created automatically so that users know where to place custom aliases.
• [#7944] Tweaks the 'target entity' expression to make the ray size option more grammatically correct.
• [#7965] Splits the 'special number' expression into multiple literal expressions: 'infinity', 'NaN', and 'negative infinity'

Bug Fixes

• [#7654] Fixes Skript's documentation using incorrect pages and formatting.
• [#7674] Fixes an issue where the event-item in a 'craft' event often returned air due to the recipe being complex.
• [#7879] Fixes an issue where syntax removals using the new Registration API often failed.
• [#7917] Fixes an issue where the raid omen effect was incorrectly given the alias bad omen.
• [#7928] Fixes an issue where sorting lists with duplicate values returned a list with only a single instance of that value.
• [#7935] Fixes incorrect documentation for the 'expand/shrink world border' effect.
• [#7938] Fixes an issue where using the 'name' expression with default variables could cause an exception.
• [#7943] Fixes numerous issues with the 'gamerule value' expression.
• [#7945] Fixes a bug where the 'is within' condition incorrectly handled or lists.
• [#7947] Fixes comparisons between enchantments and enchantment types: if sharpness 1, efficiency 3, and knockback 2 contains sharpness.
• [#7951] Fixes multiple issues with using and comparing against llamas/trader llamas.
• [#7964] Fixes an issue with setting variables during script loading when asynchronous loading is enabled.
• [#7971] Fixes some issues with comparing pig variants and that variants could not be used with baby pigs.
• [#7976] Fixes an issue where arithmetic syntax could fail to resolve valid operations.
• [#7986] Fixes an issue on newer versions where adding items to an inventory could result in other slots being mistakenly deleted.
• [#7989] Fixes an issue where next/previous 'loop-value' could fail to reset in-between loops.
• [#7998] Fixes an issue where the 'inventory holder/viewers/rows/slots' expression could cause an exception when used with other syntax.
• [#7999] Fixes an issue where getting the entities in a chunk failed.
• [#8005] Fixes ephemeral variables still being saved on server shutdown.
• [#8012] Fixes an issue where pig entity data could not be saved in a variable.
• [#8015] Fixes an issue where removing functions mistakenly used the wrong namespace.
• [#8024] Removes the 'cannot be saved' warnings for ephemeral variables.
• [#8026] Fixes test failures with ExprExcept and an issue where it would mistakenly simplify when it shouldn't.
• [#8027] Fixes text arguments and other code being mistakenly parsed as specific literals.
• [#8028] Fixes an issue where custom lang files were not loaded due to Skript looking for them in Skriptlang/ instead of Skript/lang/.
• [#8032] Fixes an issue where overloading functions with no parameters or array parameters could result in errors.

API Changes

• [#7256] Adds API to allow the setting of custom default values for types.
• [#7551] Integrates the Registration API into SkriptParser and syntax class parse methods. Addons using SkriptParser methods directly may need to be recompiled, though there should be no breaking changes.
• [#7709] Updates SkriptEventInfo (and its Registration API equivalent) to support passing an array for the since documentation field. Some methods have had their signatures changed and addons using them will need to be updated.
• [#7710] Cleanup to the ExprTool class and EquipmentSlot conversion methods for BukkitUtils.
• [#7778] Adds a preInit() method intended to help with doing common init work for families of syntaxes, rather than having to hijack init() and create a different signature for the children to implement.
• [#7791] Adds a spawnTestEntity helper method for JUnit tests.
• [#7832] Removes many unnecessary version checks for versions Skript no longer supports.
• [#7841] The syntax simplification API is now used by the parser. For more information, review the pull request's description.
• [#7851] Adds a PatternedParser utility interface and replaces the RegistryParser#getAllNames method with RegistryParser#getCombinedPatterns (from the PatternedParser interface).
• [#7858] Adds ExperimentData utility class and SimpleExperimentalSyntax utility interface to simplify the work needed by syntax to restrict based on the set experiments.
• [#7879] Registered syntax are no longer ordered by when they were registered. Priorities should be used if precise registration order is required.
• [#7891] Improves the return types for many expressions via Expression#possibleReturnTypes() and Expression#canReturn().
• [#7892] Adds experimental support for local variable type hints. If you have syntax that modifies variables (and may result in their type being changed), you you may need to support this feature. For more information, review the pull request's description (see "API Support").
• [#7904] Fixes a conflict between the 'player skull' expression and the 'head location' expression. Note that head has been removed as an option for the player skull expression.
• [#7909] Significantly expands (and reworked to some extent) the Keyed Expression API. For more information about the changes, review the pull request's description.
• [#7918] Adds a Javadoc description for the Type generic parameter in the AnyContains interface.
• [#7927] Adds a getter method for the expression used in PropertyCondition.
• [#7929] Implements preInit() for Effect, Condition, and Section, allowing runtime errors to be used more easily. Adds a #isSectionOnly() method in SectionExpression allowing the ability to check if it requires a Section.
• [#7971] Improves documentation for EntityData.
• [#7972] Switches entitydata age/plurality from parse marks to parse tags.
• [#7993] Adds SyntaxInfo builder methods to the "property" type syntax classes, in favor of the existing register methods.
• [#8001] Adds a default implementation for Expression#simplify().

Click here to view the full list of commits made since 2.11.2 Click here to view the full list of commits made since 2.12.0-pre1

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.

Click to reveal the experiments available in this release

### For-Each Loop **Enable by adding `using for loops` to your script.** A new 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. ### 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.

Help Us Test

We have an official Discord community for beta testing Skript's new features and releases.

Thank You

Special thanks to the contributors whose work was included in this version: - @Absolutionism - @APickledWalrus - @Asleeepp - @Burbulinis - @ChickChicky ⭐ First contribution! ⭐ - @Efnilite - @erenkarakal - @Fusezion - @LalitNarayanYadav ⭐ First contribution! ⭐ - @Moderocky - @Mr-Errors ⭐ First contribution! ⭐ - @nopeless - @OfficialDonut - @Olyno - @sovdeeth - @TheLimeGlass - @TheMug06 - @TwistedWar3713 ⭐ First contribution! ⭐ - @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.