Pre-Release 2.14.0-pre2

[sovdeeth]

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

• Rework Potions #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.
• Replace the Visual Effect system #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.
• Re-range text opacity from [-128, 127] to [0, 255] #8330 The text opacity expression for text displays has been modified to make it much more intuitive and easier to use. Previously, opacity was as follows:

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

defaults to -1.

This has been changed to

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

defaults to 255

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

• [API] Stabilize Registration API #8316/Syntax Info Improvements #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

• Fix HTML Documentation Generation #8341 Fixes an issue with HTML documentation generation.
• Fix duplicate indices in ExprIndices #8343 Fixes an issue where the results of the 'indices of list' expression could have duplicate values.
• Fix function parameter stringification #8344 Fixes an issue where function parameters were not properly converted to strings (primarily for documentation).
• Rename lang entry for ParticleEffect to just particle #8348 Renames the language entry for ParticleEffect to particle (rather than particle effect) for consistency with other particles.
• Fix named function arguments conflicts #8350 Fixes an issue where function arguments containing colons could fail to parse.
• Implement better function argument ordering parsing #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.
• Property Implementation Fixes #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.
• Syntax Info Improvements #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.
• Add a default expression on itemstaack #8356 Fixes an issue where item stacks could not be used as default expressions.
• Fix oversights in particle rework #8360 Fixes some particle syntax not working as expected.
• Use better event example estimation #8361 Fixes an issue with how event documentation is processed for events registered using legacy methods.

Additions

• Facing Relative Vector Offset #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.
• Function package rework and named function arguments #8112 Adds support for specifying named function arguments when calling functions.
• Allow ExprIndicesOfValue to search for the indices of multiple values #8252 Adds support for obtaining the indices of multiple values at once with the 'indices of value' expression.
• feat: setting block data on FallingBlock #8261 Adds support for obtaining and changing the BlockData of falling blocks.
• Adds interaction entity syntaxes #8291 Adds support for working with interaction entities.
• stabilize for loops and reflection #8280 Moves 'for-each loops' out of experimental status.
• Converting bases, color hex codes, and ranged function parameters #8314 Adds two expressions for converting colors to and from hex codes: hex code of %colors% and color from hex code %strings%.
• Converting bases, color hex codes, and ranged function parameters #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).
• Respawn Reason #8323 Adds support for obtaining the 'respawn reason' in a 'respawn' event.
• Update to Paper 1.21.11 #8328 Adds support for Minecraft 1.21.11.

Changes

• Rework Potions #4183 Reworks potion syntax from the ground up. Read more in its dedicated section above.
• Expand the key API to allow for nested keys #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.
• stabilize for loops and reflection #8280 Marks the Script Reflection experiment as stable (that is, not subject to breaking changes).
• Replace the Visual Effect system #8302 Completely replaces Visual Effects with a new system of particle effects, game effects, and entity effects. Read more in its dedicated section above.
• Add support for a negation/fail check on CondChance #8320 Adds a negation option to the 'chance' condition: if chance of 50% fails.
• Re-range text opacity from [-128, 127] to [0, 255] #8330 Reworks the 'text display opacity' expression to go from 0 to 255, rather than from -128 to 127.
• Optimize looping reversed lists #8335 Improves loop performance for the 'elements' and 'reversed list' expressions.
• Rename lang entry for ParticleEffect to just particle #8348 Changes the lang entry for particles effects from particle effect to simply particle to match its code name and docs name.

Bug Fixes

• Expand the key API to allow for nested keys #8243 Fixes an error that occurs when attempting to get the sorted indices of a list with empty values (sublists).
• Expand the key API to allow for nested keys #8243 Fixes an error that occurs when calling a function with two lists with values corresponding to the same keys.
• Base default values for attributes on the entity's defaults, not the global ones. #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.
• Fix EffLook requiring a default entity to parse. #8315 Fixes an issue where the 'look' effect mistakenly required an entity in some cases (even though it was unused).
• prevent bad arithmetic operators in gendocs #8332 Fixes arithmetic operations used for testing showing up on the documentation site.
• fix non-finite yaw/pitch issue, clean ExprYawPitch, and remove VectorMath #8334 Fixes an error that could occur when attempting to change the 'yaw/pitch' to a non-finite value.
• Fix duplicate indices in ExprIndices #8343 Fixes an issue where indices of nested lists would contain duplicates.
• Fix function parameter stringification #8344 Fixes issue with the docs not showing function parameters properly.

API Changes

• Add expr ai test #8061 Adds tests for entity AI syntaxes.
• Experiment descriptions #8105 Adds experiments and their descriptions to the JSONGenerator.
• Function package rework and named function arguments #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.
• Use @Example annotations instead of @Examples #8224 Migrates the vast majority of syntax examples from the old @Examples annotation to the new @Example annotations.
• SyntaxStringBuilder appendIf() method #8272 Adds the appendIf() utility method to SyntaxStringBuilder.
• WXYZ property and handler reorganization #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.
• Update Fields and cleanup BukkitClasses #8300 Adds new utility methods for working with Fields objects.
• Replace the Visual Effect system #8302 Adds a new ParticleEffect class that extends Paper's ParticleBuilder class. Addons should use this class when dealing with particles.
• Remove Java 17 tests and update to Gradle 9 #8303 Removes Java 17 tests (1.20.4).
• Converting bases, color hex codes, and ranged function parameters #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.
• Converting bases, color hex codes, and ranged function parameters #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.
• Stabilize Registration API #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.
• Parallelize GitHub Action tests via a customTest task #8317 Adds a customTest gradle task to allow testing of any combination of environments. Parallelizes tests on GitHub.
• fix non-finite yaw/pitch issue, clean ExprYawPitch, and remove VectorMath #8334 Removes the long-deprecated VectorMath utility class.
• Move type properties to partial release #8336 Enables type properties by default. Read more in the dedicated section above.
• Syntax Info Improvements #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

Notices

Experimental Features

Experimental features can be used to enable syntax and other behavior on a per-script basis. Some of these features are new proposals that we are testing while others may have unsafe or complex elements that regular users may not need.

While we have tested the available experiments to the best of our ability, they are they are still in development. As a result, they are subject to change and may contain bugs. Experiments should be used at your own discretion.

Additionally, example scripts demonstrating usage of the available experiments can be found here.

Click to reveal the experiments available in this release

Queue

Enable by adding using queues to your script.

A collection that removes elements whenever they are requested.

This is useful for processing tasks or keeping track of things that need to happen only once.

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

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

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

# queue is empty

set {queue} to a new queue of all players

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

Queues can be looped over like a regular list.

Script Reflection

Enable by adding using script reflection to your script.

This feature includes:

• The ability to reference a script in code.
• Finding and running functions by name.
• Reading configuration files and values.

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:

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

Previously, the code above would parse without issue. However, Skript now understands that when it is used, {_a} could only be a number (and not a text). Thus, the code above would now error with a message about mismatched types.

Please note that this feature is currently only supported by simple local variables. A simple local variable is one whose name does not contain any expressions:

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

Runtime Error Catching

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.

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

Damage Sources

Enable by adding using damage sources to your script.

Note that type has been removed as an option for the 'damage cause' expression as damage cause and damage type now refer to different things.

Damage sources are a more advanced and detailed version of damage causes. Damage sources include information such as the type of damage, the location where the damage originated from, the entity that directly caused the damage, and more.

Below is an example of what damaging using custom damage sources looks like:

damage all players by 5 using a custom damage source:
	set the damage type to magic
	set the causing entity to {_player}
	set the direct entity to {_arrow}
	set the damage location to location(0, 0, 10)

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

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:

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

Changes can be made directly on to the existing equippable component of an item whether using the item itself or the retrieved equippable component

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

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

Help Us Test

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

Thank You

Special thanks to the contributors whose work was included in this version:

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

---

This discussion was created from the release Pre-Release 2.14.0-pre2.