Feature Release 2.12.0

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.

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:

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:

{_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.

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:

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:

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](https://docs.skriptlang.org/docs.html?search=#Ex...

Pre-Release 2.12.0-pre2

Skript 2.12.0-pre2

Today, we are releasing Skript 2.12.0-pre2. This pre-release includes additional bug fixes, including some for issues that were reported with the first pre-release. Skript 2.12 includes dozens of new features and bug fixes, 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.0 on July 15th. We may release additional pre-releases 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.

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:

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:

{_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.

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:

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:

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

Pre-Release 2 Changes

• #7943 Fixes numerous issues with the 'gamerule value' expression.
• #7992 Fixes an issue where some examples diplayed incorrectly on the documentation site.
• #7993 Adds SyntaxInfo builder methods to the "property" type syntax classes, in favor of the existing register methods.
• #7996 Fixes an error that would occur when using experimental syntax in effect commands.
• #7997 Fixes an issue where the 'indices of value' expression failed to respect the c...

Pre-Release 2.12.0-pre1

Skript 2.12.0-pre1

Today, we are excited to celebrate the beginning of the second half of the year with a new Skript pre-release! Skript 2.12.0-pre1 is now available! This release includes dozens of new features and bug fixes, 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.0 on July 15th. We may release additional pre-releases before then should the need arise.

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

Happy Skripting!

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.

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:

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:

{_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.

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:

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:

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 Add...

Patch Release 2.11.2

Skript 2.11.2

As we prepare for Skript 2.12 in July, Skript 2.11.2 is here to resolve some additional bugs.

As always, you can report any issues on our issue tracker.
Skript 2.11.2 supports Spigot or Paper servers on versions 1.19.4 to 1.21.4, with tentative support for 1.21.5.

Happy Skripting!

Changelog

Bug Fixes

• #7845 Fixes types marked as a instead of an in the default language file.
• #7850 Fixes an issue where LiteralUtils#hasUnparsedLiteral() would not check recursively and therefore could miss some UnparsedLiterals.
• #7886 Fixes an exception/crash that could occur when using blockdata in a click event.
• #7889 Fixes an issue where the 'stop trigger' effect used the incorrect ExecutionIntent.
• #7890 Fixes an issue where the 'no damage ticks' expression printed an improper (non-suppressable) deprecation warning.
• #7895 Fixes the player event value not working in a 'flight toggle' event.
• #7907 Fixes an issue with the 'arithmetic' expression that could result in valid operations failing or exceptions.

API Changes

• #7826 Cleans up tests and removes outdated checks for unsupported versions.
• #7883 Adds safe arithmetic methods for Timespans.

Click here to view the full list of commits made since 2.11.1

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.

for {_index}, {_value} in {my list::*}:
    broadcast "%{_index}%: %{_value}%"

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.

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

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.

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
• @erenkarakal
• @sovdeeth

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.

Patch Release 2.11.1

Skript 2.11.1

What better than a new Skript release to celebrate the beginning of May? Today, we are releasing Skript 2.11.1 which brings with it a handful of bug fixes.

As always, you can report any issues on our issue tracker.
Skript 2.11.1 supports Spigot or Paper servers on versions 1.19.4 to 1.21.4, with tentative support for 1.21.5.

Happy Skripting!

Changelog

Changes

• #7806 Tweaked the documentation of the 'using experimental feature' structure.
• #7827 Corrects the documentation examples to reflect the usage of minimized aliases.
• #7838 Improves the documentation of the 'create worldborder' expression section.

Bug Fixes

• #7698 Fixes an issue with plural type representation when generating a JSON documentation file.
• #7775 Fixes an issue where the 'broadcast' effect could evaluate its expressions multiple times.
• #7795 Fixes a crash that could occur when loading invalid BlockData.
• #7796 Fixes some issues that could occur when running Skript on 1.21.5.
• #7809 Fixes an error that could occur in variable loading from slow name parsing
• #7814 Fixes an issue where the 'any of' expression would mistakenly allow itself to be changed using add, set, remove, and other changers.
• #7827 Fixes an issue where per-player usages of the 'create worldborder' expression section shared state.
• #7829 Fixes an issue where using the 'shoot' effect section as a section would reset the velocity (from the head statement).

API Changes

• #7817 Formalized deprecation processes and updated removal dates of deprecated content. If you are using any deprecated methods or classes, check to see if they will be removed in 2.12.
• #7821 Moves the inventory event-value to InventoryEvent.class, rather than having to implement it on each child event individually.

Click here to view the full list of commits made since 2.11.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.

Click to reveal the experiments avaiable 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.

for {_index}, {_value} in {my list::*}:
    broadcast "%{_index}%: %{_value}%"

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.

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

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.

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
• @ahmadmsaleem
• @cRxPtiCz (first time)
• @Efnilite
• @erenkarakal
• @sovdeeth

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.

Feature Release 2.11.0

Skript 2.11.0

Skript 2.11.0 is now available! This release is of a much more manageable size compared to 2.10, but includes a significant amount of new syntaxes to play around with, as well as a major fix for some item variables. Please read the Major Changes section closely.

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!
Skript 2.11.0 supports Spigot or Paper servers on versions 1.19.4 to 1.21.4.

Per our release model, we plan to release 2.11.1 on May 1st to address any immediate issues that are spotted with this release. Should it be necessary, an emergency patch release may come before then.

Happy Skripting!

Major Changes

• Adds the ability to clarify the type of a literal, allowing e.g. black (wolf color) or black (color).
• A large number of additional syntaxes for various entities, like wardens, allays, and endermen.
• Allows the use of minecraft ids to refer to items: minecraft:oak_log.
• Adds a spanish language option.
• Fixes bug where stored items in variables could change types between Minecraft versions.

Caution

Updating your Minecraft version before switching to 2.11 can cause some item variables to change materials!
To avoid issues, please ensure you start your server normally with 2.11 active, shut it down normally, and only then proceed to updating your Minecraft version.

If you are still on 2.10, have updated your Minecraft version, and are experiencing item variable issues, you may find success by downgrading Minecraft to before the issues began and updating to 2.11 on that version (Or by copying your variables.csv file to a server running on an older version). Be warned that downgrading generally is not supported by Paper or Spigot, and you may encounter other unrelated issues attempting this.

Be warned that downgrading from 2.11 may cause Skript to be unable to load some item variables. Keep this in mind when testing 2.11.

⚠ Breaking Changes

• The last colour of %string% expression has been reworked, adding additional support. This necessitated a pattern change, so existing code using this expression should now use last string colour code of %string%.
• The potion type type has been renamed to potion effect type. Usages of the previous name will need to be updated in scripts.
• The chiseled bookshelf and decorated pot inventory types have been renamed to [chiseled] bookshelf inventory and decorated pot inventory respectively. Usages of the previous names will need to be updated in scripts.
• event-item in the 'armor change event' has been removed in favor of 'old armor item' and 'new armor item'
• UUIDs are no longer represented by strings in Skript and are instead proper UUID objects. This should cause no changes for normal Skript users, but may cause issues if you are relying on them being strings in contexts like using Skript-Reflect methods.

Changelog

Additions

• #7006 Adds full support for modifying players' world borders.
• #7270 Adds additional syntax for interacting with dropped items.
• #7314 Adds Warden related syntaxes:
  • Make a Warden investigate an area.
  • Get the entity a Warden is most angry at.
  • Get the anger level of a Warden.
• #7316 Adds support for dealing with the entities in 'entity storage' blocks like beehives, as well as other beehive related syntax.
• #7332 Adds an event that is triggered at certain real-life times of day.
• #7351 Adds an effect to zombify/dezombify villagers.
• #7358 Adds Allay related syntaxes:
  • Get or change whether allays can duplicate and their duplication cooldown.
  • Get the target jukebox of an Allay.
  • Force an Allay to duplicate or dance.
• #7361 Adds an effect and condition for whether axolotls are playing dead.
• #7362 Updates sleeping related syntaxes to support bats, foxes and villagers.
• #7365 Adds effect to make a player sprint, adds a condition to check if a camel is using its dash ability.
• #7386 Adds ability to check if an entity is riding a specific other entity. Prevents error when trying to make an entity ride itself.
• #7415 Adds ability to get and change the simulation and view distances on Paper servers.
• #7453 Adds support for specifying slots in the armor change event like on helmet change.
• #7479 Adds syntax related to goats.
• #7480 Adds Enderman related syntaxes:
  • Check or change the block an Enderman is carrying.
  • Make Enderman randomly teleport or towards an entity.
  • Check if an Enderman is being stared at.
• #7532 Adds a config option for the number of variable changes required to trigger a save.
• #7550 Adds various math functions:
  • mean(numbers)
  • median(numbers)
  • factorial(number)
  • root(number, number)
  • permutation(number, number)
  • combination(number, number)
• #7554 Moves the "invulnerability time" expression to support timespans and deprecates the tick-based version.
• #7564 Allows modifying the persistence of entities and blocks, and allows modifying whether entities should despawn when the player is far away.
• #7586 Adds spanish language option.
• #7597 Adds checking for whether a ghast is charging its fireball and adds getting and changing the explosive power of a ghast's fireball.
• #7683 Added support for fishing states and generic fishing state change event.
• #7701 Adds an expression to treat a list as if it is of the form a, b, or c rather than a, b, and c: if {_X} is any of {_possibilities::*}.
• #7702 Adds an expression to change phantom and slime entity sizes.
• #7709 Adds past event-item, future event-item, and event-slot to the armor change event.
• #7714 Adds the entity shoot bow event, as well as some expressions for it.
• #7722 Adds the ability to clarify the type of a literal, allowing e.g. black (wolf color) or black (color).
• #7747 Adds support for interacting with pandas.
• #7750 Adds support for obtaining items with/without their tooltip.

Changes

• #7276 Changes the pattern of last colour of %string%, adds support for returning colour objects, the first colour, and all colours.
• #7287 Improves the check for what types Skript attempts to compare by comparing super classinfos.
• #7317 Adds examples to the location type.
• #7440 Enforces the use of effect when using the type potion effect type.
• #7442 Merges ExprWeather and ExprPlayerWeather to resolve syntax conflicts.
• #7492 Allows the use of minecraft ids to refer to items: minecraft:oak_log.
• #7547 Allows checking whether something is within multiple objects, e.g. if player is in world "world" or world "world_nether".
• #7549 Allows using skript tag as an alternative for custom tag.
• #7552 Allows using multiple numbers in the rounding expression.
• #7602 Adds support for using experience as a regular number, allowing for arithmetic like 5 xp + 10.
• #7622 Adds syntax that allows the user to improve the clarity of using experiment.
• #7694 Allows itemstack as another way to reference the item type.
• #7704 Adds support for with all item flags.
• #7708 Adds support for using armour instead of armor.
• #7716 Improves the errors for when a single value is passed, where multiple are expected.
• #7762 Improves the registration and internal organization of the '[bell events](https://docs.skriptlang.org/...

Pre-Release 2.11.0-pre2

Skript 2.11.0-pre2

Skript 2.11.0-pre2 is now available! This release includes a handful of extra bug fixes not present in pre1, including one major bug fix relating to some item variables. Please read the Major Changes section closely.

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.11.0 on April 15th. We may release additional pre-releases before then should the need arise.

Happy Skripting!

Major Changes

• Adds the ability to clarify the type of a literal, allowing e.g. black (wolf color) or black (color).
• A large number of additional syntaxes for various entities, like wardens, allays, and endermen.
• Allows the use of minecraft ids to refer to items: minecraft:oak_log.
• Adds a spanish language option.
• Fixes bug where stored items in variables could change types between Minecraft versions.

Caution

Updating your Minecraft version before switching to 2.11 can cause some item variables to change materials!
To avoid issues, please ensure you start your server normally with 2.11 active, shut it down normally, and only then proceed to updating your Minecraft version.

If you are still on 2.10, have updated your Minecraft version, and are experiencing item variable issues, you may find success by downgrading Minecraft to before the issues began and updating to 2.11 on that version (Or by copying your variables.csv file to a server running on an older version). Be warned that downgrading generally is not supported by Paper or Spigot, and you may encounter other unrelated issues attempting this.

Be warned that downgrading from 2.11 may cause Skript to be unable to load some item variables. Keep this in mind when testing 2.11.

⚠ Breaking Changes

• The last colour of %string% expression has been reworked, adding additional support. This necessitated a pattern change, so existing code using this expression should now use last string colour code of %string%.
• The potion type type has been renamed to potion effect type. Usages of the previous name will need to be updated in scripts.
• The chiseled bookshelf and decorated pot inventory types have been renamed to [chiseled] bookshelf inventory and decorated pot inventory respectively. Usages of the previous names will need to be updated in scripts.
• event-item in the 'armor change event' has been removed in favor of 'old armor item' and 'new armor item'
• UUIDs are no longer represented by strings in Skript and are instead proper UUID objects. This should cause no changes for normal Skript users, but may cause issues if you are relying on them being strings in contexts like using Skript-Reflect methods.

Changelog

Pre-Release 2 Changes

• aliases#126 Fixes confusion between resin brick and resin bricks.
• #7483 Fix conflicts with any in the player input event.
• #7656 Fix event values not being null in docs created by the JSON generator.
• #7697 Improve error messages for event restricted syntaxes.
• #7736 Maintains the inventory of items when setting blocks.
• #7754 Fix name and example of ExprDisplayTeleportDuration on the docs.
• #7769 Fix issues with looping blocks in a straight line when starting near the edge of a block.
• #7773 Fixes unintended claiming errors when using section expressions without sections.
• #7774 Fixes crashes on Spigot due to the armor change event attempting to load a Paper class.
• #7776 Adds lang entries for bundle inventory actions and for the bucket spawn reason.
• #7790 Fixes bug where stored items in variables could change types between Minecraft versions.

Additions

• #7006 Adds full support for modifying players' world borders.
• #7270 Adds additional syntax for interacting with dropped items.
• #7314 Adds Warden related syntaxes:
  • Make a Warden investigate an area.
  • Get the entity a Warden is most angry at.
  • Get the anger level of a Warden.
• #7316 Adds support for dealing with the entities in 'entity storage' blocks like beehives, as well as other beehive related syntax.
• #7332 Adds an event that is triggered at certain real-life times of day.
• #7351 Adds an effect to zombify/dezombify villagers.
• #7358 Adds Allay related syntaxes:
  • Get or change whether allays can duplicate and their duplication cooldown.
  • Get the target jukebox of an Allay.
  • Force an Allay to duplicate or dance.
• #7361 Adds an effect and condition for whether axolotls are playing dead.
• #7362 Updates sleeping related syntaxes to support bats, foxes and villagers.
• #7365 Adds effect to make a player sprint, adds a condition to check if a camel is using its dash ability.
• #7386 Adds ability to check if an entity is riding a specific other entity. Prevents error when trying to make an entity ride itself.
• #7415 Adds ability to get and change the simulation and view distances on Paper servers.
• #7453 Adds support for specifying slots in the armor change event like on helmet change.
• #7479 Adds syntax related to goats.
• #7480 Adds Enderman related syntaxes:
  • Check or change the block an Enderman is carrying.
  • Make Enderman randomly teleport or towards an entity.
  • Check if an Enderman is being stared at.
• #7532 Adds a config option for the number of variable changes required to trigger a save.
• #7550 Adds various math functions:
  • mean(numbers)
  • median(numbers)
  • factorial(number)
  • root(number, number)
  • permutation(number, number)
  • combination(number, number)
• #7554 Moves the "invulnerability time" expression to support timespans and deprecates the tick-based version.
• #7564 Allows modifying the persistence of entities and blocks, and allows modifying whether entities should despawn when the player is far away.
• #7586 Adds spanish language option.
• #7597 Adds checking for whether a ghast is charging its fireball and adds getting and changing the explosive power of a ghast's fireball.
• #7683 Added support for fishing states and generic fishing state change event.
• #7701 Adds an expression to treat a list as if it is of the form a, b, or c rather than a, b, and c: if {_X} is any of {_possibilities::*}.
• #7702 Adds an expression to change phantom and slime entity sizes.
• #7709 Adds past event-item, future event-item, and event-slot to the armor change event.
• #7714 Adds the entity shoot bow event, as well as some expressions for it.
• #7722 Adds the ability to clarify the type of a literal, allowing e.g. black (wolf color) or black (color).
• #7747 Adds support for interacting with pandas.
• #7750 Adds support for obtaining items with/without their tooltip.

Changes

• #7276 Changes the pattern of last colour of %string%, adds support for returning colour objects, the first colour, and all colours.
• #7287 Improves the check for what types Skript attempts to compare by comparing super classinfos.
• #7317 Adds examples to the location type.
• #7440 Enforces the use of effect when using the type potion effect type.
• #7442 Merges ExprWeather and ExprPlayerWeather to resolve syntax conflicts.
• #7492 Allows the use of minecraft ids to refer to items: minecraft:oak_log.
• #7547 Al...

Pre-Release 2.11.0-pre1

Skript 2.11.0-pre1

It's no joke: Skript 2.11.0-pre1 is now available! This release includes dozens of new features, bug fixes, and other enhancements.

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.11.0 on April 15th. We may release additional pre-releases before then should the need arise.

Happy Skripting!

Major Changes

⚠ Breaking Changes

• The last colour of %string% expression has been reworked, adding additional support. This necessitated a pattern change, so existing code using this expression should now use last string colour code of %string%.
• The potion type type has been renamed to potion effect type. Usages of the previous name will need to be updated in scripts.
• The chiseled bookshelf and decorated pot inventory types have been renamed to [chiseled] bookshelf inventory and decorated pot inventory respectively. Usages of the previous names will need to be updated in scripts.
• event-item in the 'armor change event' has been removed in favor of 'old armor item' and 'new armor item'

Changelog

Additions

• #7006 Adds full support for modifying players' world borders.
• #7270 Adds additional syntax for interacting with dropped items.
• #7314 Adds Warden related syntaxes:
  • Make a Warden investigate an area.
  • Get the entity a Warden is most angry at.
  • Get the anger level of a Warden.
• #7316 Adds support for dealing with the entities in 'entity storage' blocks like beehives, as well as other beehive related syntax.
• #7332 Adds an event that is triggered at certain real-life times of day.
• #7351 Adds an effect to zombify/dezombify villagers.
• #7358 Adds Allay related syntaxes:
  • Get or change whether allays can duplicate and their duplication cooldown.
  • Get the target jukebox of an Allay.
  • Force an Allay to duplicate or dance.
• #7361 Adds an effect and condition for whether axolotls are playing dead.
• #7362 Updates sleeping related syntaxes to support bats, foxes and villagers.
• #7365 Adds effect to make a player sprint, adds a condition to check if a camel is using its dash ability.
• #7386 Adds ability to check if an entity is riding a specific other entity. Prevents error when trying to make an entity ride itself.
• #7415 Adds ability to get and change the simulation and view distances on Paper servers.
• #7453 Adds support for specifying slots in the armor change event like on helmet change.
• #7479 Adds syntax related to goats.
• #7480 Adds Enderman related syntaxes:
  • Check or change the block an Enderman is carrying.
  • Make Enderman randomly teleport or towards an entity.
  • Check if an Enderman is being stared at.
• #7532 Adds a config option for the number of variable changes required to trigger a save.
• #7550 Adds various math functions:
  • mean(numbers)
  • median(numbers)
  • factorial(number)
  • root(number, number)
  • permutation(number, number)
  • combination(number, number)
• #7554 Moves the "invulnerability time" expression to support timespans and deprecates the tick-based version.
• #7564 Allows modifying the persistence of entities and blocks, and allows modifying whether entities should despawn when the player is far away.
• #7586 Adds spanish language option.
• #7597 Adds checking for whether a ghast is charging its fireball and adds getting and changing the explosive power of a ghast's fireball.
• #7683 Added support for fishing states and generic fishing state change event.
• #7701 Adds an expression to treat a list as if it is of the form a, b, or c rather than a, b, and c: if {_X} is any of {_possibilities::*}.
• #7702 Adds an expression to change phantom and slime entity sizes.
• #7709 Adds past event-item, future event-item, and event-slot to the armor change event.
• #7714 Adds the entity shoot bow event, as well as some expressions for it.
• #7722 Adds the ability to clarify the type of a literal, allowing e.g. black (wolf color) or black (color).
• #7747 Adds support for interacting with pandas.
• #7750 Adds support for obtaining items with/without their tooltip.

Changes

• #7276 Changes the pattern of last colour of %string%, adds support for returning colour objects, the first colour, and all colours.
• #7287 Improves the check for what types Skript attempts to compare by comparing super classinfos.
• #7317 Adds examples to the location type.
• #7440 Enforces the use of effect when using the type potion effect type.
• #7442 Merges ExprWeather and ExprPlayerWeather to resolve syntax conflicts.
• #7492 Allows the use of minecraft ids to refer to items: minecraft:oak_log.
• #7547 Allows checking whether something is within multiple objects, e.g. if player is in world "world" or world "world_nether".
• #7549 Allows using skript tag as an alternative for custom tag.
• #7552 Allows using multiple numbers in the rounding expression.
• #7602 Adds support for using experience as a regular number, allowing for arithmetic like 5 xp + 10.
• #7622 Adds syntax that allows the user to improve the clarity of using experiment.
• #7694 Allows itemstack as another way to reference the item type.
• #7704 Adds support for with all item flags.
• #7708 Adds support for using armour instead of armor.
• #7716 Improves the errors for when a single value is passed, where multiple are expected.
• #7762 Improves the registration and internal organization of the 'bell events'.

Bug Fixes

• #7431 Fixes the order of in which sections are printed in debug mode.
• #7566 Improved condition classes and added missing method overrides.
• #7599 Changes how event-values are determined to avoid possible conflicts when 2 or more values could apply.
• #7665 Ensures EffSort's input expression always returns a single value.
• #7669 Fixes issue when using player in entity move event.
• #7679 Fixes some incorrectly configured documentation annotations for events.
• #7696 Fixes decorated pot and bookshelf item comparisons.
• #7688 Fixes an issue where damage component were added to undamaged items.
• #7713 Fixes an issue with comparing inventory slots.
• #7717 Fixes an issue when using integers in the radians expression.
• #7744 Fixes an issue where spawning a tropical fish of a specific type would spawn the incorrect type.

Removals

• #7638 Removes undocumented expression [is] event cancelled as it has been superseded by CondCancelled for years.

API Changes

• #7478 Deprecates Skript's EquipSlot in favour of Bukkit's EquipmentSlot.
• [#7512](https://github.com/SkriptLang/S...

Patch Release 2.10.2

Skript 2.10.2

Skript 2.10.2 is here with some more bug fixes and some docs enhancements!

We would like to welcome two new additions to the team, who will be focused mainly on triaging issues and bug fixes:
@Burbulinis
@TheMug06
Thank you to everyone who applied!

We are also updating our release schedule, which you can view here. To summarize the changes, we are introducing minor feature releases in April and October, which will be focused on additions and minimize breaking changes. This is to keep the update size more reasonable and to be quicker about responding to Minecraft's 'drops' update system. This means 2.11 will be next month, rather than in July.

As always, you can report any issues on our issue tracker.

Happy Skripting!

Changelog

Bug Fixes

• #7499 Fixes empty event requirement sections in the docs.
• #7513 Fixes issue with getting blocks between two locations.
• #7584 Updates the compass target expression's description to include 1.21.4 behavior changes.
• #7591 Adds a vehicle class-info to allow event-vehicle to work properly.
• #7603 Fixes a bad example in the text display alignment examples.
• #7632 Fixes an internal test for dates that was intermittently failing.
• #7641 Fixes issues with using various projectile entity datas, like fireballs and wind charges
• #7646 Fixes decimal multiplication/division with timespans resulting in truncated values.
• aliases#123 Fixes brick/bricks confusion with item names.
• aliases#125 Fixes issue when checking whether an entity is a wind charge.

API Changes

• #7470 Adds an Example annotation that can be applied multiple times, intended to eventually replace Examples. See PR for details.
• #7558 Allows the test platform to run on a Spigot server. This is not supported and may cause test failures among the existing tests if used.
• #7633 Improves the consistency and information provided by Skript's generated JSON documentation.

Click here to view the full list of commits made since 2.10.1

Notices

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:

• @Efnilite
• @erenkarakal
• @JakeGBLP
• @Moderocky
• @ShaneBeee
• @sovdeeth
• @TheAbsolutionism

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.

Patch Release 2.10.1

Skript 2.10.1

Skript 2.10.1 is here to address some of the most prominent issues reported with 2.10.0.

As always, you can report any issues on our issue tracker.

Happy Skripting!

Breaking Changes

There have been a few minor breaking changes:

• When using "send" in the 'connect' effect, "server" is now a required keyword.
• Removed the pattern "[a] %*color% %bannerpatterntype%"

Changelog

Bug Fixes

• #7450 Fixes an issue where tag lookups for the 'tag' expression would not check all possible tag sources.
• #7455 Fixes an issue with the experimental queue serialization.
• #7474 Fixes an issue where using 'or' in the 'is tagged' condition would not check against all tags.
• #7503 Fixes an issue where getting or changing the name of a block did not work.
• #7519 Fixes a syntax conflict between the 'send' effect and the 'connect' effect.
• #7521 Fixes multiple issues with 'fishing' documentation.
• #7525 Fixes an issue where the 'wearing' condition could check invalid slots, resulting in an exception.
• #7527 Fixes an issue where checking whether something is tagged as a different type (e.g. check if an entity is tagged as a type of item) would result in an exception.
• #7528 Fixes an issue where loot tables could not be serialized.
• #7537 Fixes an issue where the 'for each' loop did not fully iterate over the elements.
• #7540 Fixes an issue where some language entries could mistakenly be associated with non-Minecraft additions (e.g. custom biomes).
• #7546 Removes the pattern "[a] %*color% %bannerpatterntype%" which caused significant parsing slowdowns in some Skript environments.
• #7557 Fixes an issue where the tests could fail if a locale other than English was used.
• #7559 Fixes an issue where some syntaxes contained "the" multiple times at the beginning.
• #7570 Fixes an issue where date variables from older versions would fail to load on 2.10.0.

API Changes

• #7526 Added support for regex-based highlighting for runtime errors.

Click here to view the full list of commits made since 2.10.0

Notices

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:

• @APickledWalrus
• @Burbulinis
• @erenkarakal
• @Fusezion
• @Moderocky
• @Phill310
• @ShaneBeee
• @sovdeeth
• @TheAbsolutionism
• @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.