Skript 2.14.0-pre2

We are starting the weekend with the second pre-release for Skript 2.14.0, now with more bug fixes! This release includes dozens of major contributions to enhance Skript's existing features, along with a handful of exciting new features. Major changes means some breaking changes though, so we hope you all forgive us for doing some early spring cleaning (especially with visual effects). Please remember to look through the Breaking Changes section to see if anything impacts you!

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 is required.

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[/i]MODEL.md]release model, we plan to release 2.14.0 on January 15th. 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:

Code:

set {_potions::*} to the potion effects of the player

However, it is now also possible to obtain specific potion effects:

Code:

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:

Code:

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:

Code:

set the amplifier of {_potion} to 5
apply {[i]potion} to {[/i]entity}

Even better, it is now possible to modify potion effects that are actively applied to entities and items:

Code:

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:

Code:

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:

Code:

player has speed 10 # checks type, amplifier
player has a potion effect of speed for 30 seconds # checks type, duration

The 'comparison' condition (as in, x is y), can be used for exact comparisons.

These comparisons are also used for removals:

Code:

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!).

Code:

[SIZE=7]sets the random distribution of the particle[/SIZE]
set particle distribution of {_flame particle} to vector(1,2,1) 

[SIZE=7]set the velocity of the flame particle. [/SIZE]
[SIZE=7]Note this only works for 'directional particles' and it will override the random distribution [/SIZE]
[SIZE=7](distribution and special effects like scale/velocity are mutually exclusive)[/SIZE]
set the velocity of {_flame particle} to vector(1,2,1) 

[SIZE=7]set the scale of the explostion particle. [/SIZE]
[SIZE=7]Note this only works for 'scalable particles' (explosion, sweeping edge) and it will override the random distribution [/SIZE]
[SIZE=7](distribution and special effects like scale/velocity are mutually exclusive)[/SIZE]
set the scale of {_explosion particle} to 2.5

Drawing a particle should look more like this, now:

Code:

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.

Code:

function multiply(a: number, b: number) returns number:
    return {[i]a} * {[/i]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.

Code:

function add(a: number, b: number) returns number:
    return {[i]a} + {[/i]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.

Code:

for {[i]index}, {[/i]value} in {my list::*}:
    broadcast "%{[i]index}%: %{[/i]value}%"

Code:

for each {_player} in all players:
    send "Hello %{[i]player}%!" to {[/i]player}

All existing loop features are also available in this section.

Interaction Entities
Syntax has been added for working with interaction entities. 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.

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:

Code:

set {_list::a} to "Hello"
set {_list::b} to "World!"
set {_list::sublist::c} to "I'm nested!"

[SIZE=7]This behaves the same as the same as 'print[i]list(recursive keyed {[/i]list::*})'.[/SIZE]
[SIZE=7]This is only true for function parameter.[/SIZE]
print[i]list(keyed {[/i]list::*})
[SIZE=7]Prints:[/SIZE]
[SIZE=7]a -[quote][/quote]Hello[/SIZE]
[SIZE=7]b -[quote][/quote]World![/SIZE]
[SIZE=7]sublist::c -[quote][/quote]I'm nested![/SIZE]

function print_list(list: objects):
    loop {_list::*}:
        broadcast "%loop-index% -[quote][/quote]%loop-value%"

For more information, you can review the pull request.

(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. 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:

Code:

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

Code:

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 SequencedCollections rather than regular Collections. 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.

Changelog

Since pre-1
- #8341 Fixes an issue with HTML documentation generation.
- #8343 Fixes an issue where the results of the 'indices of list' expression could have duplicate values.
- #8344 Fixes an issue where function parameters were not properly converted to strings (primarily for documentation).
- #8348 Renames the language entry for ParticleEffect to particle (rather than particle effect) for consistency with other particles.
- #8350 Fixes an issue where function arguments containing colons could fail to parse.
- #8352 Fixes an issue where optional function parameters could not be excluded when using only named arguments. Also reduces the restrictions in how named and unnamed arguments can be combined.
- #8354 Fixes an issue where property expressions could allow a change operation at parse time but then unexpectedly fail at performing the change during runtime. Also fixes an issue where the contains property condition failed to use converted input values during runtime.
- #8355 Improves SyntaxInfo creation through automatic Priority detection (when a Priority is not specified). Tweaks some properties (such as patterns) to be a SequencedCollection rather than a regular Collection. Further, AddonModule now has a required name method to be implemented (as a result, it is no longer a FunctionalInterface). This is a breaking change from 2.13.2. Finally, the newly introduced module method on AddonModule now takes an AddonModule rather than a String.
- #8356 Fixes an issue where item stacks could not be used as default expressions.
- #8360 Fixes some particle syntax not working as expected.
- #8361 Fixes an issue with how event documentation is processed for events registered using legacy methods.

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' 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' 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' in a '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', 'reversed list', 'shuffled list', 'sorted list', and 'elements' 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' condition: if chance of 50% fails.
- #8330 Reworks the 'text display opacity' expression to go from 0 to 255, rather than from -128 to 127.
- #8335 Improves loop performance for the 'elements' and 'reversed list' 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' 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' 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-pre2>)

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.

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

Code:

set {queue} to a new queue of "hello" and "world"

broadcast the first element of {queue}
[SIZE=7]"hello" is now removed[/SIZE]

broadcast the first element of {queue}
[SIZE=7]"world" is now removed[/SIZE]

[SIZE=7]queue is empty[/SIZE]

Code:

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}
[SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]

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:

Code:

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {[i]c} to {[/i]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:

Code:

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

Code:

catch runtime errors:
    ...
    set worldborder center of {[i]border} to {[/i]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' 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:

Code:

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.

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:

Code:

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 {[i]item} to {[/i]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

Code:

set the equipment slot of {_item} to helmet slot
    
set {[i]component} to the equippable component of {[/i]item}
allow {_component} to swap equipment

For more details about the syntax, visit equippable component on our documentation website.
</details>

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

Skript 2.14.0-pre1

We are kicking off the new year with the first pre-release for 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. Major changes means some breaking changes though, so we hope you all forgive us for doing some early spring cleaning (especially with visual effects). Please remember to look through the Breaking Changes section to see if anything impacts you!

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 is required.

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[/i]MODEL.md]release model, we plan to release 2.14.0 on January 15th. 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:

Code:

set {_potions::*} to the potion effects of the player

However, it is now also possible to obtain specific potion effects:

Code:

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:

Code:

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:

Code:

set the amplifier of {_potion} to 5
apply {[i]potion} to {[/i]entity}

Even better, it is now possible to modify potion effects that are actively applied to entities and items:

Code:

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:

Code:

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:

Code:

player has speed 10 # checks type, amplifier
player has a potion effect of speed for 30 seconds # checks type, duration

The 'comparison' condition (as in, x is y), can be used for exact comparisons.

These comparisons are also used for removals:

Code:

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!).

Code:

[SIZE=7]sets the random distribution of the particle[/SIZE]
set particle distribution of {_flame particle} to vector(1,2,1) 

[SIZE=7]set the velocity of the flame particle. [/SIZE]
[SIZE=7]Note this only works for 'directional particles' and it will override the random distribution [/SIZE]
[SIZE=7](distribution and special effects like scale/velocity are mutually exclusive)[/SIZE]
set the velocity of {_flame particle} to vector(1,2,1) 

[SIZE=7]set the scale of the explostion particle. [/SIZE]
[SIZE=7]Note this only works for 'scalable particles' (explosion, sweeping edge) and it will override the random distribution [/SIZE]
[SIZE=7](distribution and special effects like scale/velocity are mutually exclusive)[/SIZE]
set the scale of {_explosion particle} to 2.5

Drawing a particle should look more like this, now:

Code:

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.

Code:

function multiply(a: number, b: number) returns number:
    return {[i]a} * {[/i]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.

Code:

function add(a: number, b: number) returns number:
    return {[i]a} + {[/i]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.

Code:

for {[i]index}, {[/i]value} in {my list::*}:
    broadcast "%{[i]index}%: %{[/i]value}%"

Code:

for each {_player} in all players:
    send "Hello %{[i]player}%!" to {[/i]player}

All existing loop features are also available in this section.

Interaction Entities
Syntax has been added for working with interaction entities. 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.

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:

Code:

set {_list::a} to "Hello"
set {_list::b} to "World!"
set {_list::sublist::c} to "I'm nested!"

[SIZE=7]This behaves the same as the same as 'print[i]list(recursive keyed {[/i]list::*})'.[/SIZE]
[SIZE=7]This is only true for function parameter.[/SIZE]
print[i]list(keyed {[/i]list::*})
[SIZE=7]Prints:[/SIZE]
[SIZE=7]a -[quote][/quote]Hello[/SIZE]
[SIZE=7]b -[quote][/quote]World![/SIZE]
[SIZE=7]sublist::c -[quote][/quote]I'm nested![/SIZE]

function print_list(list: objects):
    loop {_list::*}:
        broadcast "%loop-index% -[quote][/quote]%loop-value%"

For more information, you can review the pull request.

(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. 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:

Code:

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

Code:

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.

Changelog

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' 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' 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' in a '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', 'reversed list', 'shuffled list', 'sorted list', and 'elements' 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' condition: if chance of 50% fails.
- #8330 Reworks the 'text display opacity' expression to go from 0 to 255, rather than from -128 to 127.
- #8335 Improves loop performance for the 'elements' and 'reversed list' expressions.

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' 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' to a non-finite value.

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.

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

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

Code:

set {queue} to a new queue of "hello" and "world"

broadcast the first element of {queue}
[SIZE=7]"hello" is now removed[/SIZE]

broadcast the first element of {queue}
[SIZE=7]"world" is now removed[/SIZE]

[SIZE=7]queue is empty[/SIZE]

Code:

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}
[SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]

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:

Code:

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {[i]c} to {[/i]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:

Code:

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

Code:

catch runtime errors:
    ...
    set worldborder center of {[i]border} to {[/i]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' 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:

Code:

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.

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:

Code:

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 {[i]item} to {[/i]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

Code:

set the equipment slot of {_item} to helmet slot
    
set {[i]component} to the equippable component of {[/i]item}
allow {_component} to swap equipment

For more details about the syntax, visit equippable component on our documentation website.
</details>

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

Skript 2.13.2
Supports: Paper 1.21.0 - 1.21.10

Today, we are releasing Skript 2.13.2 to resolve some various issues found with Skript 2.13, as well as solving a few older bugs.

We have also revamped our [contributor guide](github.com/SkriptLang/Skript/blob/master/.github/contributing.md) to be much more beginner-friendly, so now's a great time to try making your first PR! For existing contributors, please note the addition of the AI usage disclosure requirement for PRs:
If you relied on AI assistance to make a pull request, you must disclose it in the
pull request, together with the extent of the usage.

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

Happy Skripting!

Changelog

Additions / Changes
- #8285 Improves variable thread safety, preventing race conditions and conflicts when accessing variables on parallel threads.
- #8286 Adds 'child' as an option for the 'make adult/baby' effect.
- #8294 Updates contribution guidelines and adds AI disclosure requirement

Bug Fixes
- #8250 Fixes an issue where functions could be unloaded prior to the 'on unload' event firing, leading to Skript being unable to resolve function calls.
- #8263 Fixes issues with do-whiles not running properly in concurrent scenarios.
- #8271 Ensures legacy syntax infos have reference to their modern counterparts to support modern features like suppliers.
- #8278 Fixes vague and unclear errors when attempting to parse regions that do not exist or are ambiguous.
- #8284 Fixes an issue where on brew complete was not a valid pattern, but on brew complet was.
- #8293 Makes the auto-reload player name input case-insensitive.
- #8295 Fix an issue that prevented the use of past and future when using the level of player in the level change event.
- #8299 Fixes a bug where a delay in one event trigger could affect the behavior of another trigger of the same event that was parsed later on.
- #8304 Fixes an issue where a warning would be displayed when using an empty variable for cooldown storage.

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

<details>
<summary>Click to reveal the experiments available in this release</summary>

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.

Code:

for {[i]index}, {[/i]value} in {my list::*}:
    broadcast "%{[i]index}%: %{[/i]value}%"

Code:

for each {_player} in all players:
    send "Hello %{[i]player}%!" to {[/i]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.

Code:

set {queue} to a new queue of "hello" and "world"

broadcast the first element of {queue}
[SIZE=7]"hello" is now removed[/SIZE]

broadcast the first element of {queue}
[SIZE=7]"world" is now removed[/SIZE]

[SIZE=7]queue is empty[/SIZE]

Code:

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}
[SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]

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:

Code:

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {[i]c} to {[/i]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:

Code:

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

Code:

catch runtime errors:
    ...
    set worldborder center of {[i]border} to {[/i]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' 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:

Code:

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.

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:

Code:

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 {[i]item} to {[/i]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

Code:

set the equipment slot of {_item} to helmet slot
    
set {[i]component} to the equippable component of {[/i]item}
allow {_component} to swap equipment

For more details about the syntax, visit equippable component on our documentation website.
</details>

Join us on Discord
We have an official Discord community where we share announcements and and perform testing for upcoming features.

Thank You
Special thanks to the contributors whose work was included in this version:
- @erenkarakal
- @ericd590 First contribution!
- @HarshMehta112 First contribution!
- @JakeGBLP
- @sovdeeth
- @TFSMads
- @UnderscoreTud First contribution!

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.

Skript 2.13.1

Today, we are releasing Skript 2.13.1 to resolve some of the most common issues reported with Skript 2.13.0.

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

Happy Skripting!

Changelog

Additions / Changes
- #8225 Added support for using a list of strings in the text of expression.
- #8226 Adds support for using closest as an alias in the 'nearest entity' expression.

Bug Fixes
- #8221 Fixes an issue where functions with one plural parameter that has default values would cause an exception when the default values were used.
- #8240 Removes legacy code used in the bucket events, preventing Skript from loading legacy material support and causing a temporary server freeze.
- #8242 Fixes an extraneous the in the 'tablisted players' expression.
- #8245 Fixes an issue with matching functions that have a single list parameter.
- #8248 Fixes an issue with how the 'has scoreboard tag' condition handled OR inputs.
- #8249 Fixes an issue where the name of blocks (such as chests) would not carry over when those blocks were placed.

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

<details>
<summary>Click to reveal the experiments available in this release</summary>

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.

Code:

for {[i]index}, {[/i]value} in {my list::*}:
    broadcast "%{[i]index}%: %{[/i]value}%"

Code:

for each {_player} in all players:
    send "Hello %{[i]player}%!" to {[/i]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.

Code:

set {queue} to a new queue of "hello" and "world"

broadcast the first element of {queue}
[SIZE=7]"hello" is now removed[/SIZE]

broadcast the first element of {queue}
[SIZE=7]"world" is now removed[/SIZE]

[SIZE=7]queue is empty[/SIZE]

Code:

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}
[SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]

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:

Code:

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {[i]c} to {[/i]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:

Code:

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

Code:

catch runtime errors:
    ...
    set worldborder center of {[i]border} to {[/i]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' 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:

Code:

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.

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:

Code:

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 {[i]item} to {[/i]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

Code:

set the equipment slot of {_item} to helmet slot
    
set {[i]component} to the equippable component of {[/i]item}
allow {_component} to swap equipment

For more details about the syntax, visit equippable component on our documentation website.
</details>

Join us on Discord
We have an official Discord community where we share announcements and and perform testing for upcoming features.

Thank You
Special thanks to the contributors whose work was included in this version:
- @AfkUserMC First contribution!
- @CJH3139
- @CrebsTheCoder First contribution!
- @Efnilite
- @sovdeeth
- @TFSMads

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.

Skript 2.13.0

Today, we are excited to release Skript 2.13.0. This release includes a handful of new features, bug fixes, and behind-the-scenes API improvements to play with. For addon developers, we strongly recommend reviewing the Type Properties section below.

Please also note our changes to the supported versions. 2.13 will be 1.20.4+, and Paper is required.

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.13.1 on November 1st. We may release emergency patches before then should the need arise.

Happy Skripting!

Changes to Supported Versions and Platforms

As announced with 2.12, we have updated our policy for supported versions. Going forward, Skript will guarantee support for the last 18 months of Minecraft releases. This means 2.13 will be 1.20.4+, while 2.14 will be 1.21+.

Additionally, with Paper forking itself from Spigot, it has become increasingly difficult to support both platforms. As a result, this version of Skript has dropped support for Spigot. Skript now requires Paper or a downstream fork of Paper, such as Purpur or Pufferfish.

Major Changes

Equippable Components (Experimental)
Added in #7194
[!NOTE]
This feature is currently experimental and can be used by enabling the equippable components experiment.

Equippable components allow 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:

Code:

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 {[i]item} to {[/i]component}

Automatic Reloading
Added in #7464

A new Structure has been added that enables automatic reloading of a script when it is updated (e.g. the file is saved). This feature is only supported if asynchronous loading is enabled in Skript's configuration file (config.sk).

Code:

automatically reload this script:
    recipients: "Sahvde" # The names or uuids of players who, apart from console, will see the success/error messages in chat.
OR
auto reload:
    permission: myserver.see[i]auto[/i]reloads # all players with this permission will see the messages.

Debug Information Expression
Added in #8207

A new expression that returns additional information about a value has been added. Currently, this consists of the value itself and its class, though this is subject to change in the future.

Code:

set {my_list::*} to 1, "2", and vector(1, 2, 3)
broadcast debug info of {my_list::*}
[SIZE=7]prints:[/SIZE]
[SIZE=7]1 (integer)[/SIZE]
[SIZE=7]"2" (text)[/SIZE]
[SIZE=7]x: 1, y: 2, z: 3 (vector)[/SIZE]

Type Properties (Experimental)
Added in #8165

Included in 2.13 is an experimental opt-in API for what we're tenatively calling 'type properties'. 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 PR. We plan on making a more comprehensive API spec/tutorial once the implementation is solidified, but for now the PR description should be more than sufficient to try it out.

However, since this is still experimental and not well tested, it requires a secret config option to enable. To activate property syntaxes, add the line use type properties: true somewhere in your config.sk. Without it, Skript will still use the old syntaxes for things like name of. We hope you try out this new API and give us feedback on what works, what doesn't, and what you'd like to see for its full release in 2.14. The number of property-driven syntaxes is rather small, but we plan on adding many more in the coming months!

⚠ Breaking Changes
- #7985 Changes the method signature for the abstract EntityData#init. Adds parameter matchedCodeName and refactors matchedPattern.
- #8072 Enforces using physics instead of physic in the block update effect.

Changelog

Additions
- #7194 Adds experimental support for equippable components and all correlating data.
- #7275 Adds elements for brewing stands such as brewing stand slots, fuel, time, and events.
- #7464 Adds a structure that allows a script to be automatically reloaded when it is saved, if async loading is enabled in config.sk.
- #7878 Adds support for specifying the amount of damage in the 'force attack' effect.
- #7888 Adds a 'midpoint' expression to obtain the midpoint between two locations or vectors.
- #7985 Adds an 'is spawnable' condition to check whether an entity is spawnable in a world.
- #8008 Adds literals for the maximum 'double', 'float', 'integer', and 'long' values and the minimum 'double', 'float', 'integer', and 'long' values.
- #8092 Adds support for using 'vehicle' alone in the 'mount' event.
- #8101 Adds a 'tablisted players' expression to obtain and modify the players listed in the tablist menu for a given player.
- #8113 Adds the ability to enchant an item at as a specific level, as if an enchanting table was used, to the 'enchant' effect.
- #8134 Adds a 'time lived' expression to get the duration an entity has been alive for.
- #8196 Adds a runtime error when attempting to get the distance between locations in different worlds.
- #8197 Adds support for changing the event-location for 'portal' event.
- #8206 Adds a runtime error when using the sort effect and mapping the input to a null value, which cannot be sorted.
- #8207 Adds a 'debug info' expression that returns extra information about a value.
- #8219 Adds early support for Minecraft 1.21.10.
- #8229 Adds playtime as an alias to the 'time played' expression.
- #8230 Adds pull as an alias to the 'push' effect.

Changes
- #8072 Enforces using physics instead of physic in the block update effect.

Bug Fixes
- #7985 Fixes being unable to spawn certain entities in certain states, such as red fox and snow fox.
- #8064 Fixes an issue where it was not possible to spawn a minecart.
- #8177 Fixes the 'cannot reset' and 'cannot delete' error messages of the 'change' effect being swapped around.
- #8182 Fixes an issue where variable changes across multiple threads could be processed in the wrong order, resulting in data loss.
- #8185 Fixes the 'system time' event not triggering on the main thread.
- #8189 Fixes an issue where function calls with a single parameter to functions with 0 required parameters would fail to parse.
- #8195 Fixes an issue where the 'catch runtime errors' section would stop catching errors after the default error limit was reached.
- #8199 Fixes an issue where functions could not use Expression Sections.
- #8232 Fixes an issue where Expression Sections did not work properly with Effect Sections (used as an Effect).

API Changes
- #7797 Uses project.testEnv in build.gradle instead of updating the latest version for both.
- #7985 Changes Pattern to allow providing null as the object for generic usage.
- #8011 Exposes the script loader executor via the Task api.
- #8035 Adds support for using an EntryData multiple times.
- #8065 Adds support for custom operators.
- #8116 Makes JSONGenerator available for addons and updates the docs.json format.
- #8120 Adds a method to get a Color as an ARGB integer.
- #8138 Adds getting pattern combinations from PatternElement and tests to catch possible pattern conflicts.
- #8150 Adds SimplifiedCondition for constant conditions. Condition implements Simplifiable.
- #8165 Adds the Type Property API.
- #8180 Changes the parameter name for Expression class from expressionType to expressionClass in Skript#registerExpression.
- #8195 Improves runtime error filtering with the introduction of RuntimeErrorFilter, which allows different consumers to apply different levels of filtering to the errors they print.
- #8201 Adds support for excluding packages from being loaded in ClassLoader.
- #8211 Improves the classes ExpressionList returns for acceptChange to more accurately reflect the changers of the expressions within the list.
- #8213 Fixes Functions#getJavaFunctions to only return JavaFunctions.
- #8235 Adds additional null safety checks around certain API classes.

[Click here to view the full list of commits made since 2.12.2](<https://github.com/SkriptLang/Skript/compare/2.12.2...2.13.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.

<details>
<summary>Click to reveal the experiments available in this release</summary>

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.

Code:

for {[i]index}, {[/i]value} in {my list::*}:
    broadcast "%{[i]index}%: %{[/i]value}%"

Code:

for each {_player} in all players:
    send "Hello %{[i]player}%!" to {[/i]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.

Code:

set {queue} to a new queue of "hello" and "world"

broadcast the first element of {queue}
[SIZE=7]"hello" is now removed[/SIZE]

broadcast the first element of {queue}
[SIZE=7]"world" is now removed[/SIZE]

[SIZE=7]queue is empty[/SIZE]

Code:

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}
[SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]

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:

Code:

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {[i]c} to {[/i]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:

Code:

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

Code:

catch runtime errors:
    ...
    set worldborder center of {[i]border} to {[/i]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' 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:

Code:

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.

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:

Code:

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 {[i]item} to {[/i]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

Code:

set the equipment slot of {_item} to helmet slot
    
set {[i]component} to the equippable component of {[/i]item}
allow {_component} to swap equipment

For more details about the syntax, visit equippable component on our documentation website.
</details>

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
- @Chrissblock99 First contribution!
- @CJH3139 First contribution!
- @Efnilite
- @erenkarakal
- @MrScopes First contribution!
- @NotSoDelayed
- @Pesekjak
- @sovdeeth
- @TheLimeGlass

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.

Skript 2.13.0-pre1

Hi all, we've got a new feature pre-release for you all. Thankfully, this one's a bit more reasonable in size than the massive releases of 2.10, 2.11, and 2.12. We have some great features and a bunch of behind-the-scenes API improvements for you this go around. Addon developers should pay special attention to the Type Properties section below.

Please also note our changes to the supported versions. 2.13 is 1.20.4+, and Paper only.

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

Happy Skripting!

Changes to Supported Versions and Platforms

As announced with 2.12, we have updated our policy for supported versions. Going forward, Skript will guarantee support for the last 18 months of Minecraft releases. This means 2.13 is 1.20.4+, while 2.14 will be 1.21+.

Additionally, with Paper forking itself from Spigot, it has become increasingly difficult to support both platforms. As a result, this version of Skript is dropping support for Spigot. Skript now requires Paper or a downstream fork of Paper, such as Purpur or Pufferfish.

Major Changes
- #7194 Adds support for equippable components and all correlating data. Smurfy put in a lot of work into the backing API for components, so look forward to a lot more component support in the next few releases!

Code:

set the allowed entities of {_item} to a zombie and a skeleton
make {_item} lose durability when hurt
if {_item} can be dispensed:
	add "Dispensable" to lore of {_item}

- #7464 Adds a structure that allows a script to be automatically reloaded when it is saved, if async loading is enabled in config.sk:

Code:

automatically reload this script:
    recipients: "Sahvde" # The names or uuids of players who, apart from console, will see the success/error messages in chat.
OR
auto reload:
    permission: myserver.see[i]auto[/i]reloads # all players with this permission will see the messages.

- #8165 Adds Type Property API. See below.
- #8207 Adds a debug info expression that prints out extra information about a value. Currently this consists of the value itself and its class, though this is subject to expansion in the future!

Code:

set {my_list::*} to 1, "2", and vector(1, 2, 3)
broadcast debug info of {my_list::*}
[SIZE=7]prints:[/SIZE]
[SIZE=7]1 (integer)[/SIZE]
[SIZE=7]"2" (text)[/SIZE]
[SIZE=7]x: 1, y: 2, z: 3 (vector)[/SIZE]

Type Properties (For Addon Devs)

Included in 2.13 is an experimental opt-in API for what we're tenatively calling 'type properties'. 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 PR. We plan on making a more comprehensive API spec/tutorial once the implementation is solidified, but for now the PR description should be more than sufficient to try it out.

However, since this is still experimental and not well tested, it requires a secret config option to enable. To activate property syntaxes, add the line use type properties: true somewhere in your config.sk. Without it, Skript will still use the old syntaxes for things like name of. We hope you try out this new API and give us feedback on what works, what doesn't, and what you'd like to see for its full release in 2.14. The number of property-driven syntaxes is rather small, but we plan on adding many more in the coming months!

⚠ Breaking Changes
- #7985 Changes the method signature for the abstract EntityData#init. Adds parameter matchedCodeName and refactors matchedPattern.
- #8072 Enforces using physics instead of physic in the block update effect.

Changelog

Additions
- #7194 Adds support for equippable components and all correlating data.
- #7275 Adds elements for brewing stands such as brewing stand slots, fuel, time, and events.
- #7464 Adds a structure that allows a script to be automatically reloaded when it is saved, if async loading is enabled in config.sk.
- #7888 Adds an expression to get the midpoint between two locations or vectors.
- #7985 Adds a condition to check if an entity is spawnable in a world.
- #8008 Adds literals for the maximum and minimum numerical values, such as longs, doubles, or ints.
- #8101 Adds an expression to get and modify the players listed in the tab menu for a given player.
- #8113 Adds the ability to enchant an item at as a specific level, as if an enchanting table was used.
- #8134 Adds an expression to get the duration an entity has been alive for.
- #8207 Adds a debug info expression that prints out extra information about a value. Currently this consists of the value itself and its class, though this is subject to expansion in the future!

Changes
- #7797 Uses project.testEnv in build.gradle instead of updating the latest version for both.
- #7878 Allows specifying the amount of damage in the force entity to attack entity effect.
- #8072 Enforces using physics instead of physic in the block update effect.
- #8092 Allows using vehicle alone in the mount event.
- #8196 Adds a runtime error when attempting to get the distance between locations in different worlds.
- #8197 Adds support for changing the event-location for on portal.
- #8206 Adds a runtime error when using the sort effect and mapping the input to a null value, which cannot be sorted.

Bug Fixes
- #7985 Fixes being unable to spawn certain entities in certain states, such as red fox and snow fox.
- #8064 Fixes an issue where it was not possible to spawn a minecart.
- #8177 Fixes the 'cannot reset' and 'cannot delete' error messages being swapped around.
- #8182 Fixes the order of which queued variable changes are processed.
- #8185 Fixes at %time% [in] real time by triggering the code on the main thread.
- #8189 Fixes functions with 0 required parameters.
- #8195 Fixes an issue where the runtime error catching section would not catch errors after the default error limit is reached.
- #8199 Fixes issues with expression sections not claiming sections when used as function parameters.

API Changes
- #7985 Changes Pattern to allow providing null as the object for generic usage.
- #8011 Exposes the script loader executor via the Task api.
- #8035 Adds support for using an EntryData multiple times.
- #8065 Adds support for custom operators.
- #8116 Makes JSONGenerator available for addons and updates the docs.json format.
- #8120 Adds a method to get a Color as an ARGB integer.
- #8138 Adds getting pattern combinations from PatternElement and tests to catch possible pattern conflicts.
- #8150 Adds SimplifiedCondition for constant conditions. Condition implements Simplifiable.
- #8165 Adds the Type Property API.
- #8180 Changes the parameter name for Expression class from expressionType to expressionClass in Skript#registerExpression.
- #8195 Improves runtime error filtering with the introduction of RuntimeErrorFilter, which allows different consumers to apply different levels of filtering to the errors they print.
- #8201 Adds support for excluding packages from being loaded in ClassLoader.
- #8211 Improves the classes ExpressionList returns for acceptChange to more accurately reflect the changers of the expressions within the list.
- #8213 Fixes Functions#getJavaFunctions to only return JavaFunctions.

[Click here to view the full list of commits made since 2.12.2](<https://github.com/SkriptLang/Skript/compare/2.12.2...2.13.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.

<details>
<summary>Click to reveal the experiments available in this release</summary>

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.

Code:

for {[i]index}, {[/i]value} in {my list::*}:
    broadcast "%{[i]index}%: %{[/i]value}%"

Code:

for each {_player} in all players:
    send "Hello %{[i]player}%!" to {[/i]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.

Code:

set {queue} to a new queue of "hello" and "world"

broadcast the first element of {queue}
[SIZE=7]"hello" is now removed[/SIZE]

broadcast the first element of {queue}
[SIZE=7]"world" is now removed[/SIZE]

[SIZE=7]queue is empty[/SIZE]

Code:

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}
[SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]

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:

Code:

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {[i]c} to {[/i]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:

Code:

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

Code:

catch runtime errors:
    ...
    set worldborder center of {[i]border} to {[/i]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' 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:

Code:

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.

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:

Code:

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 {[i]item} to {[/i]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

Code:

set the equipment slot of {_item} to helmet slot
    
set {[i]component} to the equippable component of {[/i]item}
allow {_component} to swap equipment

For more details about the syntax, visit damage source on our documentation website.
</details>

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
- @Chrissblock99 First contribution!
- @Efnilite
- @erenkarakal
- @MrScopes First contribution!
- @Pesekjak
- @sovdeeth
- @TheLimeGlass

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.

Skript 2.12.2​

Today, we are releasing Skript 2.12.2 to continue resolving issues reported with 2.12.

We want to thank the contributors that made this release possible. Your work plays a crucial role in making Skript better, and we are immensely appreciative of the time and effort put into all contributions.

You can report any issues at https://github.com/SkriptLang/Skript/issues.

As always, be sure to read the changelog for full details.

Happy Skripting!
https://github.com/SkriptLang/Skript/releases/tag/2.12.2

Skript 2.12.1

Today, we are releasing Skript 2.12.1 to resolve some of the most common issues reported with Skript 2.12.0. This release includes support for Minecraft 1.21.8.

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

For the full changelog, please view our GitHub release page.

Happy Skripting!

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.

For the full changelog, please visit our GitHub release page.

Happy Skripting!

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.

For the full changelog, please visit our GitHub release page.

Happy Skripting!