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

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

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

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:

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:

set the amplifier of {_potion} to 5
apply {_potion} to {_entity}

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

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:

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:

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:

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

# sets the random distribution of the particle
set particle distribution of {_flame particle} to vector(1,2,1) 

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

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

Drawing a particle should look more like this, now:

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.

function multiply(a: number, b: number) returns number:
    return {_a} * {_b}
  
on load:
    assert multiply(1, 2) is 2
    assert multiply(a: 1, b: 2) is 2
    assert multiply(1, b: 2) is 2
    assert multiply(a: 1, 2) is 2
    assert multiply(b: 2, a: 1) is 2

Mixing named and unnamed function arguments is allowed, as long as the order of the function parameters is followed, as specified in the function definition.

function add(a: number, b: number) returns number:
    return {_a} + {_b}
    
on load:
    assert multiply(a: 1, 2) is 2 # allowed! 
    assert multiply(1, b: 2) is 2 # allowed!
    assert multiply(b: 2, 2) is 2 # not allowed!
    assert multiply(2, a: 2) is 2 # not allowed!

For-Each Loop

For loops are now available by default for all users and no longer require opting into the for loops experiment. As a reminder, for loops are a kind of loop syntax that stores the loop index and value in variables for convenience.

This can be used to avoid confusion when nesting multiple loops inside each other.

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

for each {_player} in all players:
    send "Hello %{_player}%!" to {_player}

All existing loop features are also available in this section.

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:

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

# This behaves the same as the same as 'print_list(recursive keyed {_list::*})'.
# This is only true for function parameter.
print_list(keyed {_list::*})
# Prints:
# a -> Hello
# b -> World!
# sublist::c -> I'm nested!

function print_list(list: objects):
    loop {_list::*}:
        broadcast "%loop-index% -> %loop-value%"

For more information, you can review the pull request.

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

0 to 3, fully opaque;
4 to 26, fully transparent;
27 to 127, gradually more opaque until half-opaque at 127;
-127 to -1, gradually more opaque from half to fully opaque at -1. 

defaults to -1.

This has been changed to

0 to 3, fully opaque; (this is mojang's fault, don't ask us why!)
4 to 26, fully transparent;
27 to 255, gradually more opaque from transparent to fully opaque at 255.

defaults to 255

The expression can still be set to values between -1 and -128, which correspond to 255 to 128 respectively, but the returned value will be positive and add/subtract will not allow opacity to leave the 0-255 range.

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

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.

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

broadcast the first element of {queue}
# "hello" is now removed

broadcast the first element of {queue}
# "world" is now removed

# queue is empty

set {queue} to a new queue of all players

set {player 1} to a random element out of {queue} 
set {player 2} to a random element out of {queue}
# players 1 and 2 are guaranteed to be distinct

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {_c} to {_a} in lowercase # oops i used the wrong variable

{_var} # can use type hints
{_var::%player's name%} # can't use type hints

catch runtime errors:
    ...
    set worldborder center of {_border} to {_my unsafe location}
    ...
if last caught runtime errors contains "Your location can't have a NaN value as one of its components":
    set worldborder center of {_border} to location(0, 0, 0)

damage 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)

set {_component} to a blank equippable component:
	set the camera overlay to "custom_overlay"
	set the allowed entities to a zombie and a skeleton
	set the equip sound to "block.note_block.pling"
	set the equipped model id to "custom_model"
	set the shear sound to "ui.toast.in"
	set the equipment slot to chest slot
	allow event-equippable component to be damage when hurt
	allow event-equippable component to be dispensed
	allow event-equippable component to be equipped onto entities
	allow event-equippable component to be sheared off
	allow event-equippable component to swap equipment
set the equippable component of {_item} to {_component}

set the equipment slot of {_item} to helmet slot
    
set {_component} to the equippable component of {_item}
allow {_component} to swap equipment

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.