Skript 2.15.0-pre1

Today, we are excited to release the first pre-release for Skript 2.15.0. This release includes a few new major features and enhancements as we lay the groundwork for some exciting things coming later this year. It's no joke either, these features are real and available now!

In accordance with supporting the last 18 months of Minecraft updates, Skript 2.15.0 supports Minecraft 1.21.1 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.15.0 on April 15th. We may release additional pre-releases before then should the need arise.

Happy Skripting!

Major Changes

Adventure and MiniMessage Integration

After several months of testing, we are excited to share that Skript is now using Adventure and MiniMessage!

What is Adventure and/or MiniMessage?

Adventure is Paper's approach for supporting Minecraft's user interface elements. This includes chat messages, titles, player tablists, and more. These elements support all kinds of features, the most notable being colors and text decorations (e.g., bold, italic, etc.). Adventure is used throughout Paper, so by making this change, Skript is better aligned to support Paper's current and upcoming features.

MiniMessage is a way of representing these features in a text-based format. Skript has long used its own similar system, which most skripters are familiar with:

send "<red>Hello there <bold>%player%!"

MiniMessage is a much more developed system, resolving many of the issues that became apparent in Skript's existing system. Further, it has better support for all sorts of features:

send "<rainbow>Wow this text is super colorful!"

# this will show a stone block in the message
send "Look at my <sprite:blocks:block/stone>!"

You can read more on Paper's documentation website about using MiniMessage and the features it offers: https://docs.papermc.io/adventure/minimessage/format

What does this mean for scripters?
We have put in significant effort to ensure this transition is smooth. We expect all scripts to continue working without issue. Legacy formatting codes are still supported. However, there are a few edge cases to be aware of.

In some cases, Skript's color tags went directly against their formal definition in Minecraft. As a result, you may notice some color tags appear differently than before.

For addons expecting legacy formatted strings, this formatting is no longer processed automatically. For cases where formatting is not being processed, you can attempt process the string using the colored expression: colored "This is my &4legacy &rtext!"

Persistent Data Tags

Persistent data tags, also known as persistent data containers (PDC), are a way to store custom data directly on players, entities, items, blocks, chunks, and worlds. Unlike variables, which are stored separately from the rest of the game world, persistent data tags are a direct part of the thing they are attached to.

They serve a similar role to metadata, but they persist through server restarts and attach directly to things.

Here is a simple example of storing a damage bonus on a sword:

command /enchant-sword:
    trigger:
        set data tag "myserver:damage_bonus" of player's tool to 10
        send "Your sword has been enchanted with a damage bonus!"

on damage:
    set {_bonus} to data tag "myserver:damage_bonus" of attacker's tool
    if {_bonus} is set:
        add {_bonus} to damage

You can read more about Persistent Data in the new tutorial available on our new documentation site (in beta).

Region Hook Deprecation

With this release, we are deprecating Skript's region hooks for future removal. They have been unmaintained for some time and are full of difficult to resolve issues.

As an alternative, we have developed skript-worldguard, an official addon providing far more extensive support for WorldGuard.
You can read more about skript-worldguard on its repository: https://github.com/SkriptLang/skript-worldguard

We do not currently have any plans to offer addons for other region plugins.

(API) Event Value Registry

Following our efforts to modernize syntax registration, we are introducing a new, registry-based approach for event values. This system features new benefits such as custom identifiers (event-X), enhanced event validation, and support for changers (other than SET).

Here is an example of the full process:

// Obtaining the event value registry
EventValueRegistry registry = addon.registry(EventValueRegistry.class);

// Registering a simple event value
registry.register(EventValue.simple(WorldEvent.class, World.class, WorldEvent::getWorld));

// Builder option for more complex values (changers, time state)
registry.register(EventValue.builder(PlayerItemConsumeEvent.class, ItemStack.class)
    .getter(PlayerItemConsumeEvent::getItem)
    .registerChanger(ChangeMode.SET, PlayerItemConsumeEvent::setItem)
    .time(Time.NOW)
    .build());

For more information, you can consult the relevant pull request: #8326

⚠ Breaking Changes

Some message formatting may appear differently than before (see "Adventure and MiniMessage Integration" above).
(API) Long-deprecated registration methods in the EventValues class using Getters have been removed.

Changelog

Additions

#8327 Add a 'persistent data value' expression for working with persistent data tags (see "Persistent Data Tags" above).
#8329 Adds an 'attempt attack' event for when a player attempts to attack an entity. This occurs before regular damage events, and cancelling it prevents those events from triggering and prevents any sounds from playing.
#8331 Adds a 'player pick item' event for when a player uses the pick key (default middle mouse button) and 'picked item/block/entity' expression to obtain the thing "picked".
#8351 Adds a 'location with yaw/pitch' for obtaining a copy of a location with a modified yaw and/or pitch.
#8353 Adds a 'reduce' expression for reducing a list of elements into a single value.
#8396 Adds a configuration option to compress configuration, language, and variables file backups. This is enabled by default.
#8415 Adds failure caches to the parsing system to further improve parse times.
#8412 Adds a 'vector(n)' function, which is a shortcut for 'vector(n, n, n)'.
#8483 Adds a fast path for integer indices in variables, improving comparison speeds.
#8514 Adds missing definitions for certain Mounts of Mayhem features.

Changes

#8402 Unifies the behavior of the 'type of' and 'plain' expressions for items. Both expressions now return a base item representative of the original item. For example, potions now retain their potion effect(s) rather than becoming an "uncraftable potion". This change is more significant for the type of expression, which previously only cleared the name and durability of an item.
#8414 Makes the damage source experiment mainstream, no longer requiring using damage sources to enable.
#8433 Improves the code quality of the 'brushing stage' expression.
#8516 Further improves internal code quality and organization.
#8517 Adds a warning regarding the deprecation of region hooks.

Bug Fixes

#8435 Fixes an issue where Skript would fail to properly cancel some click events.
#8463 Fixes an issue where the 'inventory close expression' failed to return a value.
#8495 Fixes an issue where 'game effects' appeared incorrectly in the documentation.
#8498 Fixes an issue where some syntax errors could be improperly overriden by a more generic error.
#8502 Fixes an issue where internal syntax definitions were improperly compared.
#8512 Fixes an error that could occur when using the 'tags of x' expression.
#8518 Fixes an issue where a delay in a section that results in the termination of execution would propagate beyond that section.

API Changes

#8326 Overhauls the event value system with a new registration process that enables support for custom identifiers, event validation and any combination of changers.
#8346 Adds a HierarchicalAddonModule, a way for modules to easily nest within other modules for better addon organization. Refactored much of the skriptlang package to utilise this.
#8376 Adds an origin-applying SyntaxRegistry, which allows obtaining a SyntaxRegistry that applies a specificed origin to all syntax info that are registered through it (assuming the syntax info does not already have an origin)
#8377 Skript's testing framework will now copy directories from provided resource files, rather than just singular files.
#8391 Adds API to modify how syntax patterns are printed to strings (e.g. omitting literal/non-literal flags).

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

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)

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:

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.

SkriptLang/Skript 2.15.0-pre1 Pre-Release 2.15.0-pre1 on GitHub