# 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](https://papermc.io) is required**.

Below, you can familiarize yourself with the changes. Additionally, [by clicking here](https://docs.skriptlang.org/docs.html?isNew), you can view the list of new syntax on our documentation site. As always, report any issues to our [issues page](https://github.com/SkriptLang/Skript/issues)!

Per our [release model](https://stable.skriptlang.org/clockwork-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](https://papermc.io/software/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](https://docs.skriptlang.org/docs.html?search=#StructUsing) 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:

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}

### 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`).

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

set {my_list::*} to 1, "2", and vector(1, 2, 3)
broadcast debug info of {my_list::*}
# prints:
# 1 (integer)
# "2" (text)
# x: 1, y: 2, z: 3 (vector)

### 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](https://github.com/SkriptLang/Skript/pull/8165). 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](https://docs.skriptlang.org/docs.html?search=equippable) and all correlating data.
- #7275 Adds [elements for brewing stands](https://docs.skriptlang.org/docs.html?search=brewing) such as brewing stand slots, fuel, time, and events.
- #7464 Adds a [structure that allows a script to be automatically reloaded](https://docs.skriptlang.org/docs.html?search=#StructAutoReload) 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](https://docs.skriptlang.org/docs.html?search=#EffForceAttack)' effect.
- #7888 Adds a '[midpoint](https://docs.skriptlang.org/docs.html?search=#ExprMidpoint)' expression to obtain the midpoint between two locations or vectors.
- #7985 Adds an '[is spawnable](https://docs.skriptlang.org/docs.html?search=#CondIsSpawnable)' condition to check whether an entity is spawnable in a world.
- #8008 Adds literals for the maximum '[double](https://docs.skriptlang.org/docs.html?search=#LitDoubleMaxValue)', '[float](https://docs.skriptlang.org/docs.html?search=#LitFloatMaxValue)', '[integer](https://docs.skriptlang.org/docs.html?search=#LitIntMaxValue)', and '[long](https://docs.skriptlang.org/docs.html?search=#LitLongMaxValue)' values and the minimum '[double](https://docs.skriptlang.org/docs.html?search=#LitDoubleMinValue)', '[float](https://docs.skriptlang.org/docs.html?search=#LitFloatMinValue)', '[integer](https://docs.skriptlang.org/docs.html?search=#LitIntMinValue)', and '[long](https://docs.skriptlang.org/docs.html?search=#LitLongMinValue)' values.
- #8092 Adds support for using '[vehicle](https://docs.skriptlang.org/docs.html?search=#ExprVehicle)' alone in the '[mount](https://docs.skriptlang.org/events.html?search=#entity_mount)' event.
- #8101 Adds a '[tablisted players](https://docs.skriptlang.org/docs.html?search=#ExprTablistedPlayers)' 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](https://docs.skriptlang.org/docs.html?search=#EffEnchant)' effect.
- #8134 Adds a '[time lived](https://docs.skriptlang.org/docs.html?search=#ExprTimeLived)' 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](https://docs.skriptlang.org/events.html?search=#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](https://docs.skriptlang.org/docs.html?search=#ExprDebugInfo)' 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](https://docs.skriptlang.org/docs.html?search=#ExprTimePlayed)' expression.
- #8230 Adds `pull` as an alias to the '[push](https://docs.skriptlang.org/docs.html?search=#EffPush)' 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](https://docs.skriptlang.org/effects.html?search=#EffChange)' 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](https://docs.skriptlang.org/events.html?search=#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](https://docs.skriptlang.org/docs.html?search=#SecCatchErrors)' section would stop catching errors after the default error limit was reached.
- #8199 Fixes an issue where [functions](https://docs.skriptlang.org/docs.html?search=#StructFunction) 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 `JavaFunction`s.
- #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](https://github.com/SkriptLang/Skript/tree/2.13.0-pre1/src/main/resources/scripts/-examples/experimental%20features).

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

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

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

All existing loop features are also available in this section.

### Queue

**Enable by adding `using queues` to your script.**

A collection that removes elements whenever they are requested.

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

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

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

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

# queue is empty

set {queue} to a new queue of all players

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

Queues can be looped over like a regular list.

### Script Reflection

**Enable by adding `using script reflection` to your script.**

This feature includes:
- The ability to reference a script in code.
- Finding and running functions by name.
- Reading configuration files and values.

### 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](https://docs.skriptlang.org/docs.html?search=#ExprDamageCause)' 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](https://docs.skriptlang.org/docs.html?search=damage%20source) 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](https://docs.skriptlang.org/docs.html?search=equippable%20component) on our documentation website.
</details>

### Help Us Test
We have an [official Discord community](https://discord.gg/ZPsZAg6ygu) 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.