Skript by SkriptLang 
Create unique and inspiring features for Minecraft servers.
Events
249
Expressions
315
Effects
91
Conditions
100
Types
63
Sections
4
Structures
5
Total
859
Skript by SkriptLang
Patch Release 2.15.3 17 days, 4 hours and 46 minutes ago
Skript 2.15.3
Supports: Paper 1.21.1 - 26.1.2
Today, we are releasing Skript 2.15.3 to continue ironing out bugs reported with the recent 2.15 releases.
As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Changes
- #8598 Removes mentions of SQL variable storage in the configuration file as they do not currently work.
- #8671 Adds missing language definitions for certain 26.1 features.
Bug Fixes
- #8562 Fixes an issue where queue behavior was inconsistent.
- #8596 Corrects some invalid examples in the documentation of several loot table-related syntaxes.
- #8608 Fixes an issue where the 'rgb'' function did not validate the range of its parameters.
- #8609 Fixes an issue where an error could occur when 'hashing' a string using
MD5 in an effect command.
- #8623 Fixes an issue where formatting did not work in the
usage entry of 'commands'.
- #8627 Fixes an issue where uppercase characters no longer worked for legacy formatting.
- #8627 Fixes an issue where the 'contains' condition did not work as expected with text components stored in variables.
- #8628 Fixes text component (formatting) supported in the 'ban' and 'kick' effects.
- #8647 Fixes incorrect event value cache results.
- #8650 Improves the accuracy of some Turkish language translations.
- #8653 Fixes some items being stringified using legacy formatting.
- #8662 Fixes an error that could occur when indentation errors were encountered during Skript's testing process.
- #8664 Fixes an issue where using a location without a world as a variable index would cause an error.
- #8667 Fixes an issue where when reloading a script with a function, usages of that function in other scripts would not always be updated to use the latest version of the function.
Click here to view the full list of commits made since 2.15.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.
<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.
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
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 {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
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
{_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)
...
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}
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
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.
</details>
New Documentation Site
Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons.
As we continue to prepare the site for launch later this year, the beta is available for viewing at https://beta-docs.skriptlang.org.
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:
- @APickledWalrus
- @Dev-Xeiji ⭐ First contribution! ⭐
- @Efnilite
- @erenkarakal
- @kayerajava ⭐ First contribution! ⭐
- @mvanhorn ⭐ First contribution! ⭐
- @ShaneBeee
- @sovdeeth
- @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.
Emergency Patch Release 2.15.2 48 days, 4 hours and 36 minutes ago
Skript 2.15.2
Supports: Paper 1.21.1 - 26.1.2
Today, we are releasing Skript 2.15.2 as an emergency patch to fix major bug in Skript 2.15.1.
As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Bug Fixes
- #8542 Fixed an issue where certain legacy color codes (
&k,
&l,
&m,
&n,
&o and
&r) were not formatted.
Click here to view the full list of commits made since 2.15.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>
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
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 {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
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
{_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)
...
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}
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
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.
</details>
New Documentation Site
Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons.
While this site is still under heavy development, the beta is available for viewing at https://beta-docs.skriptlang.org.
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:
- @APickledWalrus
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.
Patch Release 2.15.1 48 days, 5 hours and 54 minutes ago
Skript 2.15.1
Supports: Paper 1.21.1 - 26.1.2
Today, we are releasing Skript 2.15.1 to resolve some of the issues found with Skript 2.15.
As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Additions
- #8583 Added a note in code-conventions.md about version checks.
Bug Fixes
- #8542 Lowered the parsing priority of the
parsed as expression for more predictable behvaior.
- #8551 Fixed an issue when trying to get the colour of a string with an empty tag.
- #8563 Fixed a rare issue where reloading a script containing function definitions used by other scripts with multiple script loading threads would cause an exception.
- #8576 Fixed an issue where the
on click on entity event wouldn't get called, and the
event-entity event value always being null in normal
on click events.
- #8580 Fixed an issue where arguments would pass references to functions rather than copies.
- #8585 Fixed an issue where sign indices would start from 0 rather than 1.
- #8589 Fixed an issue where double hashtag hex codes no longer work (
<##AABBCC>).
- #8589 Fixed an issue where escape characters for legacy formatting weren't removed.
- #8607 Fixed an issue
contains didn't work with components.
- #8607 Fixed an issue where some slots didn't work with the
lore expression.
- #8607 Fixed an issue where components didn't work with the
replace effect.
API Fixes
- #8529 Replaced old manual event restriction checks with the modern EventRestrictedSyntax interface.
- #8610 Registering duplicate event values now print a warning rather than throwing an exception.
Click here to view the full list of commits made since 2.15.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.
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
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 {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
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
{_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)
...
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}
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
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.
</details>
New Documentation Site
Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons.
While this site is still under heavy development, the beta is available for viewing at https://beta-docs.skriptlang.org.
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:
- @APickledWalrus
- @bluelhf
- @Efnilite
- @NotroDev ⭐ First contribution! ⭐
- @sovdeeth
- @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.
Feature Release 2.15.0 64 days, 4 hours and 52 minutes ago
Skript 2.15.0
Today, we are releasing Skript 2.15.0 with exciting features, bug fixes and enhancements. This release includes a few new major features and enhancements as we lay the groundwork for some exciting things coming later this year.
In accordance with supporting the last 18 months of Minecraft updates, Skript 2.15.0 supports Minecraft 1.21.1 to 26.1.1. 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 [url=https://github.com/SkriptLang/Skript/blob/master/CLOCKWORKRELEASEMODEL.md]release model[/url], we plan to release patch releases starting on May 1st. We may release additional emergency patch 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
sprite tags are not processed automatically, so we use the formatted expression
send formatted "Look at my <sprite:blocks:block/stone>!"
sprite tags are not processed automatically, so we use the formatted expression
send formatted "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. Legacy formatting codes are still supported. However, there are a few edge cases to be aware of.
Most importantly, we have made some changes to the tags that are processed by default. Skript will only process color and decoration based tags, such as <red> or <bold>. However, we understand that some users may have a different preference for what is parsed by default. We have added a new configuration option, safe tags, so that which tags are parsed automatically can be controlled:
safe tags: color, decorations, gradient, rainbow, reset, transition, pride, shadowColor
If we wanted to add another tag, say sprites, we simply add it to the list:
safe tags: color, decorations, gradient, rainbow, reset, transition, pride, shadowColor, sprite
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:damagebonus" of attacker's tool
if {_bonus} is set:
add {_bonus} to damage
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:damagebonus" 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());
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: https://github.com/SkriptLang/Skript/pull/8326
⚠ Breaking Changes
- Some tags are no longer parsed by default, and some 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.
- (API) Registering an already existing event value will throw a SkriptAPIException.
Changelog
Changes since pre-2
- #8505 Fixes an issue where attempting to kill an entity using the 'kill' effect would fail to do so under certain conditions.
- #8519 Significantly optimize certain list operations such as adding, deleting and getting the size of a list.
- #8536 Fixes an issue where sytaxes involving regular expressions take precedence over other possibly conflicting syntaxes
- #8538 Fixes an issue where text components were unable save in variables.
Additions
- #8327 Adds 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.
- #8522 Adds support for Paper 26.1.1.
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.
- #8519 Significantly optimize certain list operations such as adding, deleting and getting the size of a list.
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.
- #8505 Fixes an issue where attempting to kill an entity using the 'kill' effect would fail to do so under certain conditions.
- #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.
- #8536 Fixes an issue where sytaxes involving regular expressions take precedence over other possibly conflicting syntaxes
- #8538 Fixes an issue where text components were unable save in variables.
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](<https://github.com/SkriptLang/Skript/compare/2.14.3...2.15.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.
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
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 {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
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
{_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)
...
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}
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
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.
</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
- @devdinc ⭐ First contribution! ⭐
- @Efnilite
- @erenkarakal
- @miberss
- @MrScopes
- @Pesekjak
- @sovdeeth
- @tibisabau ⭐ First contribution! ⭐
- @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.
Pre-Release 2.15.0-pre2 67 days, 22 hours and 19 minutes ago
Skript 2.15.0-pre2
Today, we are releasing the second pre-release for Skript 2.15.0 with some additional fixes and enhancements. This release includes a few new major features and enhancements as we lay the groundwork for some exciting things coming later this year.
In accordance with supporting the last 18 months of Minecraft updates, Skript 2.15.0 supports Minecraft 1.21.1 to 26.1.1. Newer versions may also work but were not tested at time of release. Paper is required. Please note that Paper 26.1 is still in alpha and this build may or may not work with future Paper 26.1 releases. We will release additional compatibility updates if later Paper builds break this.
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 [url=https://github.com/SkriptLang/Skript/blob/master/CLOCKWORKRELEASEMODEL.md]release model[/url], 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
sprite tags are not processed automatically, so we use the formatted expression
send formatted "Look at my <sprite:blocks:block/stone>!"
sprite tags are not processed automatically, so we use the formatted expression
send formatted "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. Legacy formatting codes are still supported. However, there are a few edge cases to be aware of.
Most importantly, we have made some changes to the tags that are processed by default. Skript will only process color and decoration based tags, such as <red> or <bold>. However, we understand that some users may have a different preference for what is parsed by default. We have added a new configuration option, safe tags, so that which tags are parsed automatically can be controlled:
safe tags: color, decorations, gradient, rainbow, reset, transition, pride, shadowColor
If we wanted to add another tag, say sprites, we simply add it to the list:
safe tags: color, decorations, gradient, rainbow, reset, transition, pride, shadowColor, sprite
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:damagebonus" of attacker's tool
if {_bonus} is set:
add {_bonus} to damage
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:damagebonus" 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());
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: https://github.com/SkriptLang/Skript/pull/8326
⚠ Breaking Changes
- Some tags are no longer parsed by default, and some 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
Changes since pre-1
- #8522 Adds support for Paper 26.1.1.
- #8527 Fixes an issue where adding objects of the same type to a typed PDC list did not work as expected.
- #8528 Adds quality-of-life PDC syntaxes for checking whether something has a specific tag and obtaining all of the tags something has.
- #8530 Fixes an issue where event values were not properly compared when detecting duplicate registrations. Some methods have also had their return types updated.
- #8533 Adjusts the default list of safe formatting tags and adds a configuration option to allow customizing it.
Additions
- #8327 Adds 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.
- #8522 Adds support for Paper 26.1.1.
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](<https://github.com/SkriptLang/Skript/compare/2.14.3...2.15.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.
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
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 {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
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
{_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)
...
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}
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
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.
</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
- @devdinc ⭐ First contribution! ⭐
- @Efnilite
- @erenkarakal
- @miberss
- @MrScopes
- @Pesekjak
- @sovdeeth
- @tibisabau ⭐ First contribution! ⭐
- @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.
Pre-Release 2.15.0-pre1 78 days, 3 hours and 33 minutes ago
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 [url=https://github.com/SkriptLang/Skript/blob/master/CLOCKWORKRELEASEMODEL.md]release model[/url], 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>!"
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:damagebonus" of attacker's tool
if {_bonus} is set:
add {_bonus} to damage
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:damagebonus" 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());
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: https://github.com/SkriptLang/Skript/pull/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](<https://github.com/SkriptLang/Skript/compare/2.14.3...2.15.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>
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
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 {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
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
{_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)
...
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}
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
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.
</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
- @devdinc ⭐ First contribution! ⭐
- @Efnilite
- @erenkarakal
- @miberss
- @MrScopes
- @Pesekjak
- @sovdeeth
- @tibisabau ⭐ First contribution! ⭐
- @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.
Emergency Patch 2.14.3 105 days, 7 hours and 45 minutes ago
Skript 2.14.3
Supports: Paper 1.21.0 - 1.21.11
Today, we are releasing 2.14.3 as a reupload of 2.14.2 due to it being uploaded as a selfbuilt jar. Whoops!
As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
- Mark the jar as a GitHub release.
Click here to view the change log for 2.14.2
Click here to view the full list of commits made since 2.14.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.
<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.
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
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 {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
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
{_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)
...
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)
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}
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
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.
</details>
New Documentation Site
Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons.
While this site is still under heavy development, the beta is available for viewing at https://beta-docs.skriptlang.org.
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:
- No one :p
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.
Patch Release 2.14.2 108 days, 21 hours and 57 minutes ago
Skript 2.14.2
Supports: Paper 1.21.0 - 1.21.11
Today, we are releasing Skript 2.14.2 to clean up some API issues, fix up some docs oversights, and generally squash a few bugs.
As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Bug Fixes
- #8432 Fixed
delete name of tool not working and ensured all the
name of properties support set/reset/delete where appropriate.
- #8438 Fixed the
name of event-inventory returning incorrect values for the
inventory open event.
- #8439 Fixed
inventory of vehicle not returning the proper inventory.
- #8442 Fixed missing "Since" version on the draw effect.
- #8445 Fixed issue when creating
BlockStateBlocks for unplaced
BlockStates
API Fixes
- #8425 Removed some left-over experimental annotations from registration api classes.
- #8426 Fixed docs actions for archives.
- #8429 Opened up
EntryContainer and
EntryValidator methods for better extensibility.
- #8438 Added events to the convert method for type properties to allow event-specific overrides.
- #8446 Added missing documentation to the property WXYZ expression.
- #8456 Fixed mistaken return type assumptions in
ExprArithmetic
Click here to view the full list of commits made since 2.14.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>
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
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 {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
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
{_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)
...
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)
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}
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
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.
</details>
New Documentation Site
Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons.
While this site is still under heavy development, the beta is available for viewing at https://beta-docs.skriptlang.org.
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:
- @APickledWalrus
- @JakeGBLP
- @sovdeeth
- @TheLimeGlass
- @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.
Patch Release 2.14.1 137 days, 3 hours and 53 minutes ago
Skript 2.14.1
Supports: Paper 1.21.0 - 1.21.11
Today, we are releasing Skript 2.14.1 to resolve some of the issues found with Skript 2.14, and a significant number of older bugs too!
As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Additions
- #8400 Adds the ability to suppress the warning when using a single ':' in a variable name.
- #8407 Allows setting the
item of an arrow projectile, which can change the item picked up when retrieving the arrow and can change the applied potion effects if the arrow is not a spectral arrow.
Bug Fixes
- #8375 Fixes the function argument error displaying a 'null' value for the parameter name.
- #8381 Fixes an issue where
display name of <entity> returned the incorrect value.
- #8382 Fixes an issue where apostrophes (
') could not be used in literal specification (e.g.
dragon's breath (damage cause)).
- #8384 Refactors the
open inventory effect to use Paper's Menu API, which fixes issues with anvils and smithing tables not functioning correctly.
- #8390 Fixes an issue where the documentation for the 'any of' expression is missing version information.
- #8395 Fixes issues where some expression sections would be erroneously parsed as sections when they clearly should not be.
- #8401 Fixes an issue where using past/future
world of x expressions wasn't returning the correct world in some scenarios.
- #8403 Fixes an issue where parsing a region in a world where region data isn't loaded yet/is disabled would cause an exception.
- #8404 Fixes incorrect example for the particle with speed expression.
- #8405 Prevents the 'variables cannot be used here' warning from being used when it is not relevant.
- #8408 Fixes an issue where function calls would not call the most recent version of a function.
- #8416 Fixes an unintentional block on using
x of y when both inputs were literal:
5 of flame particles.
API Fixes
- #8392 Fixes an issues where the Expression and Structure syntax infos would incorrectly produce warnings about being internal.
- #8394 Fixes an issue where test servers on GitHub Actions would randomly crash during shutdown.
- #8399 Fixes an issue with comparing version strings that include postfixes like 'nightly' or 'pre1'.
Click here to view the full list of commits made since 2.14.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>
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
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 {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
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
{_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)
...
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)
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}
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
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.
</details>
New Documentation Site
Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons.
While this site is still under heavy development, the beta is available for viewing at https://beta-docs.skriptlang.org.
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:
- @3add
- @APickledWalrus
- @Efnilite
- @sovdeeth
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.
Feature Release 2.14.0 154 days, 7 hours and 27 minutes ago
Skript 2.14.0
Today, we are excited to be starting the year off strong with the formal release of 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. With all of this early spring cleaning, there are some important breaking changes to be aware of, specifically around visual effects and potions. Be sure to look through the Breaking Changes section below to see whether your scripts are impacted.
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 [url=https://github.com/SkriptLang/Skript/blob/master/CLOCKWORKRELEASEMODEL.md]release model[/url], we plan to release 2.14.1 on February 1st. 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
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}
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
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
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
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
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
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
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
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!
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}%"
broadcast "%{index}%: %{value}%"
for each {_player} in all players:
send "Hello %{player}%!" to {player}
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 'printlist(recursive keyed {list::*})'.
This is only true for function parameter.
printlist(keyed {list::*})
Prints:
a -Hello
b -World!
sublist::c -I'm nested!
function print_list(list: objects):
loop {_list::*}:
broadcast "%loop-index% -%loop-value%"
set {_list::b} to "World!"
set {_list::sublist::c} to "I'm nested!"
This behaves the same as the same as 'printlist(recursive keyed {list::*})'.
This is only true for function parameter.
printlist(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: 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:
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.
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
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-2
- #8367 Fixes misformatting in the 'sorted list' expression example.
- #8373 Improves the error message when an unknown function is used.
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>)
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.
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
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 {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
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
{_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)
...
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)
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}
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
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.
</details>
New Documentation Site
Over the past few months, we have been working hard to build our new documentation site. Not only do we have a new-and-improved syntaxes page, we are also finally launching a proper platform for official tutorials on using Skript, from writing scripts to building addons.
While this site is still under heavy development, the beta is available for viewing at https://beta-docs.skriptlang.org.
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.
Pre-Release 2.14.0-pre2 159 days, 1 hour and 51 minutes ago
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 [url=https://github.com/SkriptLang/Skript/blob/master/CLOCKWORKRELEASEMODEL.md]release model[/url], 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
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}
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
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
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
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
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
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
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
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!
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}%"
broadcast "%{index}%: %{value}%"
for each {_player} in all players:
send "Hello %{player}%!" to {player}
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 'printlist(recursive keyed {list::*})'.
This is only true for function parameter.
printlist(keyed {list::*})
Prints:
a -Hello
b -World!
sublist::c -I'm nested!
function print_list(list: objects):
loop {_list::*}:
broadcast "%loop-index% -%loop-value%"
set {_list::b} to "World!"
set {_list::sublist::c} to "I'm nested!"
This behaves the same as the same as 'printlist(recursive keyed {list::*})'.
This is only true for function parameter.
printlist(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: 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:
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.
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
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.
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
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 {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
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
{_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)
...
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)
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}
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
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.
</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.
Pre-Release 2.14.0-pre1 168 days and 12 minutes ago
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 [url=https://github.com/SkriptLang/Skript/blob/master/CLOCKWORKRELEASEMODEL.md]release model[/url], 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
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}
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
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
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
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
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
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
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
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!
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}%"
broadcast "%{index}%: %{value}%"
for each {_player} in all players:
send "Hello %{player}%!" to {player}
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 'printlist(recursive keyed {list::*})'.
This is only true for function parameter.
printlist(keyed {list::*})
Prints:
a -Hello
b -World!
sublist::c -I'm nested!
function print_list(list: objects):
loop {_list::*}:
broadcast "%loop-index% -%loop-value%"
set {_list::b} to "World!"
set {_list::sublist::c} to "I'm nested!"
This behaves the same as the same as 'printlist(recursive keyed {list::*})'.
This is only true for function parameter.
printlist(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: 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:
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.
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
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.
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
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 {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
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
{_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)
...
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)
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}
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
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.
</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.
Patch Release 2.13.2 199 days and 5 minutes ago
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:
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.
for {index}, {value} in {my list::*}:
broadcast "%{index}%: %{value}%"
broadcast "%{index}%: %{value}%"
for each {_player} in all players:
send "Hello %{player}%!" to {player}
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
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 {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
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
{_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)
...
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)
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}
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
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.
</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.
Patch Release 2.13.1 229 days, 1 hour and 45 minutes ago
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.
for {index}, {value} in {my list::*}:
broadcast "%{index}%: %{value}%"
broadcast "%{index}%: %{value}%"
for each {_player} in all players:
send "Hello %{player}%!" to {player}
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
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 {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
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
{_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)
...
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)
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}
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
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.
</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.
Feature Release 2.13.0 246 days, 7 hours and 31 minutes ago
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
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:
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 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.seeautoreloads # all players with this permission will see the messages.
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.seeautoreloads # 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)
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. 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.
for {index}, {value} in {my list::*}:
broadcast "%{index}%: %{value}%"
broadcast "%{index}%: %{value}%"
for each {_player} in all players:
send "Hello %{player}%!" to {player}
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
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 {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
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
{_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)
...
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)
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}
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
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.
</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.
Pre-Release 2.13.0-pre1 259 days, 22 hours and 57 minutes ago
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!
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}
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:
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.seeautoreloads # all players with this permission will see the messages.
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.seeautoreloads # 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!
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)
broadcast debug info of {my_list::*}
prints:
1 (integer)
"2" (text)
x: 1, y: 2, z: 3 (vector)
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.
for {index}, {value} in {my list::*}:
broadcast "%{index}%: %{value}%"
broadcast "%{index}%: %{value}%"
for each {_player} in all players:
send "Hello %{player}%!" to {player}
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
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 {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
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
{_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)
...
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)
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}
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
set {component} to the equippable component of {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.
Patch Release 2.12.2 290 days, 1 hour and 38 minutes ago
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
Patch Release 2.12.1 321 days, 5 hours and 1 minute ago
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!
Patch Release 2.11.2 382 days, 5 hours and 10 minutes ago
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!
Patch Release 2.11.1 413 days, 7 hours and 31 minutes ago
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!
Feature Release 2.11.0 413 days, 8 hours and 17 minutes ago
We apologize for the delayed post. The full changelog is available at https://github.com/SkriptLang/Skript/releases/tag/2.11.0
Patch Release 2.10.1 502 days, 5 hours and 57 minutes ago
Skript 2.10.1
Skript 2.10.1 is here to address some of the most prominent issues reported with 2.10.0.
As always, you can report any issues on our issue tracker.
Happy Skripting!
Breaking Changes
There have been a few minor breaking changes:
- When using "send" in the 'connect' effect, "server" is now a required keyword.
- Removed the pattern "[a] %\*color% %bannerpatterntype%"
Changelog
Bug Fixes
- #7450 Fixes an issue where tag lookups for the 'tag' expression would not check all possible tag sources.
- #7455 Fixes an issue with the experimental queue serialization.
- #7474 Fixes an issue where using 'or' in the 'is tagged' condition would not check against all tags.
- #7503 Fixes an issue where getting or changing the name of a block did not work.
- #7519 Fixes a syntax conflict between the 'send' effect and the 'connect' effect.
- #7521 Fixes multiple issues with 'fishing' documentation.
- #7525 Fixes an issue where the 'wearing' condition could check invalid slots, resulting in an exception.
- #7527 Fixes an issue where checking whether something is tagged as a different type (e.g. check if an entity is tagged as a type of item) would result in an exception.
- #7528 Fixes an issue where loot tables could not be serialized.
- #7537 Fixes an issue where the 'for each' loop did not fully iterate over the elements.
- #7540 Fixes an issue where some language entries could mistakenly be associated with non-Minecraft additions (e.g. custom biomes).
- #7546 Removes the pattern "[a] %\*color% %bannerpatterntype%" which caused significant parsing slowdowns in some Skript environments.
- #7557 Fixes an issue where the tests could fail if a locale other than English was used.
- #7559 Fixes an issue where some syntaxes contained "the" multiple times at the beginning.
- #7570 Fixes an issue where date variables from older versions would fail to load on 2.10.0.
API Changes
- #7526 Added support for regex-based highlighting for runtime errors.
Click here to view the full list of commits made since 2.10.0
Notices
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
- @Burbulinis
- @erenkarakal
- @Fusezion
- @Moderocky
- @Phill310
- @ShaneBeee
- @sovdeeth
- @TheAbsolutionism
- @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.
Feature Release 2.10.0 519 days, 3 hours and 35 minutes ago
Skript 2.10.0
We are excited to share that Skript 2.10.0 is now available! It is one of our largest updates, with more than 150 new features, bug fixes, and API updates to play around with!
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.10.1 on February 1st to address any immediate issues that are spotted with this release. Should it be necessary, an emergency patch release may come before then.
For the full changelog, please visit our GitHub Release Page: https://github.com/skriptlang/skript/releases/tag/2.10.0
Happy Skripting!
Patch Release 2.9.5 564 days, 1 hour and 41 minutes ago
Skript 2.9.5
Skript 2.9.5 is here with a handful of new bug fixes. As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Tweaks
- #7232 Improved the documentation of the 'projectile hit' event to be up to date with the 'victim' syntax.
Bug Fixes
- #7062 Fixed an error that would occur when attempting to place blocks between two points above the world limit.
- #7120 Fixed an issue where various expressions (enchant effect, replace effect, vector expressions, etc.) would overwrite the indices of list variables used.
- #7152 Fixed an issue where player skull textures would not immediately load on Paper (loading is now forced).
- #7188 Fixed an issue where plural event values did not work with 'past' and 'future' time states.
- #7195 Fixed a few Turkish language mistakes.
- #7199 Fixed multiple issues with playing sounds on 1.21.3+.
- #7202 Fixed an error that could occur when using invalid regular expression patterns in the split expression.
- #7210 Fixed long overflow when performing arithmetic.
- #7230 Fixed an issue that could occur when trying to grow new tree types (e.g. pale oak).
API Additions
- #7120 Added a new 'Expression#changeInPlace()' method for changing the elements of an expression without changing the entire object. For example, this allows the values of a list variable to be updated while preserving the indices.
- #7207 Updated the 'Arithmetics#exactOperationExists' and 'Arithmetics#exactDifferenceExists' methods to be public. They act as a safe way to check arithmetic operation existence during the registration period.
Click here to view the full list of commits made since 2.9.4
Notices
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:
- @Asleeepp
- @erenkarakal
- @ShaneBeee
- @sovdeeth
- @TheAbsolutionism
- @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.
Patch Release 2.9.4 594 days, 4 hours and 57 minutes ago
Skript 2.9.4
Skript 2.9.4 is here with even more bug fixes and early support for Minecraft 1.21.3. As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Bug Fixes
- #7141 Fixes leather horse armor being unequipable.
- #7143 Fixed entries being case-sensitive, preventing using capital letters in entries like 'Usage: ' for commands.
Additions
- #7163/#7176 Added early support for Minecraft 1.21.3 features
This includes: Pale Garden biome, creaking entity, baby squid entity, baby glow squid entity, baby dolphin entity
Click here to view the full list of commits made since 2.9.3
Notices
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:
- @Efnilite
- @erenkarakal
- @sovdeeth
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.
Patch Release 2.9.3 625 days, 2 hours and 8 minutes ago
Skript 2.9.3
Skript 2.9.3 is here with even more bug fixes. As always, you can report any issues on our issue tracker.
We are also excited to welcome six new members to our team! These new members were selected from the numerous applications we received, and they have already been hard at work troubleshooting issues, patching bugs, and building new features. The full list of new members is as follows:
- @cheeezburga
- @Efnilite
- @erenkarakal
- @Pesekjak
- @Romitou
- @TenFont
Happy Skripting!
Changelog
Bug Fixes
- #7024 Fixed an error that could occur when using invalid inputs in the 'look at' effect.
- #7027 Fixed some bStats reporting issues from the recent changes.
- #7031 Fixed formatting issues when reloading a directory.
- #7036 Fixed numerous and/or warnings that occurred in the tests.
- #7038 Fixed the within condition returning wrong values when negated and given a null input.
- #7052 Fixed an issue where 'Dutch' was not one of the language options listed in the config.
- #7056 Fixed removing entries from the hover list in a server ping event.
- #7060 Fixed exponents capping at long max value.
- #7066 Fixed an issue where the 'swim toggle' event could be cancelled. An error is now printed as cancelling it has no effect.
- #7067 Fixed an internal testing issue with the parse structure.
- #7082 Fixed an issue with modifying world times.
- #7085 Fixed an error message that could occur from unregistered types in changers.
- #7087 Fixed an issue where legacy materials were used in places they shouldn't.
- #7091 Fixed a bug when setting the profile of a skull to an offline player without a username.
- #7121 Fixed a redundant material namespace check.
API Updates
- #6992 Removed the usage of Eclipse annotations package. The JetBrains annotations package is now preferred.
- #7089 Introduced an official checkstyle for code formatting warnings.
- #7095 Prevents delays from being used in the testing system (excluding JUnit).
Click here to view the full list of commits made since 2.9.2
Notices
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:
- @0XPYEX0
- @Asleeepp
- @cheeezburga
- @Efnilite
- @Moderocky
- @Pesekjak
- @sovdeeth
- @Sparky200
- @TenFont
- @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.
Patch Release 2.9.2 655 days, 6 hours and 21 minutes ago
Skript 2.9.2
Skript 2.9.2 is here with more bug fixes and a few minor additions and tweaks. As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Additions
- #6942 Added Dutch language support.
- #7008 Added support trial spawners in the spawner type syntax.
Tweaks
- #6984 Enhanced and expanded the BStats charts.
- #7023 Improved the performance of the 'book authors' expression.
Bug Fixes
- #5073 Fixed an issue where items did not work with the 'is of type' condition.
- #6936 Fixed an issue with unreliable parsing of quotes in command arguments.
- #6942 Fixed a mistake in the German language support.
- #6982 Fixed some cases of incorrect word pluralization.
- #6983 Fixed a faulty error message in the 'return' effect.
- #6988 Fixed input validation errors that could occur with the 'hover list' expression on newer versions.
- #6996 Fixed a concurrency issue with default variables.
- #7018 Fixed the localization of the 'horse jump strength' attribute.
- #7016/#7022 Fixed additional version support issues with the 'play sound' effect.
- #7025 Fixed an issue with the 'vehicle' expression that could prevent Skript from loading on newer versions.
Click here to view the full list of commits made since 2.9.1
Notices
Help Us Test
We have an official Discord community for beta testing Skript's new features and releases.
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.
Patch Release 2.9.1 686 days, 6 hours and 39 minutes ago
Skript 2.9.1
Skript 2.9.1 is here to resolve some of the most notable issues reported with 2.9.0. We will continue to assess stability and make fixes as necessary. As always, you can report any issues on our issue tracker.
Happy Skripting!
Changelog
Additions
- #6906 Added some additional spawn reasons from 1.21.
- #6919 Added 'pufferfish' as an alias for the 'puffer fish' entity data.
Tweaks
- #6854 Updated the display name of potion effect types from 'potion' to 'potion effect type'.
Bug Fixes
- #6897 Fixed an issue where sorting the indices of a list with children caused an error.
- #6909 Fixed an issue with Timespan#getAs(), which was breaking timespan arithmetic.
- #6910 Fixed an issue where the 'play sound' effect would cause runtime errors on some server versions.
- #6926 Fixed an issue where Skript could fail to start on some 1.21 server versions.
- #6932 Fixed an issue with the SimplifiedChinese translation that caused a startup error.
- #6947 Fixed an issue where the 'remaining air' expression would cause runtime errors.
- #6948 Fixed an issue where using some events would cause parsetime errors.
- #6949 Fixed an issue where reloading the aliases would not automatically regenerate missing aliases.
Click here to view the full list of commits made since 2.9.0
Notices
Help Us Test
We have an official Discord community for beta testing Skript's new features and releases.
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.
Feature Release 2.9.0 703 days, 4 hours and 27 minutes ago
Skript 2.9.0
Skript 2.9.0 is here with dozens of new features, quality-of-life improvements, and bug fixes. Notably, this release includes support for Minecraft 1.21.
We especially want to thank the recent influx of new contributors, many of whom are included in this update. Every contributor means a little less work for the team and a little more progress for Skript, so please, if you want a feature in Skript, go ahead and try to make a pull request! New contributors are very welcome! You can review our contributing guide by clicking here.
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 new release model, we plan to release 2.9.1 on August 1st to address any immediate issues that are spotted with this release. Should it be necessary, an emergency patch release may come before then.
Happy Skripting!
You can view the full changelog here: https://github.com/SkriptLang/Skript/releases/tag/2.9.0
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.
Patch Release 2.8.7 733 days, 6 hours and 2 minutes ago
Skript 2.8.7
We're releasing 2.8.7 to fix some important issues that made their way into 2.8.6. We expect this to be the final version for Skript 2.8. You can report any issues through our issue tracker.
Happy Skripting!
Changelog
Bug Fixes
- #6757 Fixed an error that could occur when attempting to obtain the potion effects of a plain potion.
- #6758 Fixed arithmetic-related errors on Java 8 and when performing Vector-Vector multiplication.
- #6760 Fixed several particle definition conflicts that made it harder to use certain items and entity types with variables.
- #6763 Fixed an issue where reloading scripts with commands could cause an exception on Paper 1.20.5+.
- #6764 Fixed an issue where fireworks could not be spawned using the spawn effect/section.
- #6777 Fixed an issue with the text representation of the case expression.
Click here to view the full list of commits made since 2.8.6
Notices
Java 11
From Skript 2.9.0 onwards, we will be requiring a minimum Java version of 11 to run.
Help Us Test
We have an official Discord community for beta testing Skript's new features and releases.
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.
Patch Release 2.8.6 747 days, 5 hours and 26 minutes ago
Skript 2.8.6
Skript 2.8.6 is here. This release delivers more bug fixes with improved 1.20.5+ support. Additionally, a few quality-of-life features have made their way in. You can report any issues through our issue tracker.
Happy Skripting!
Changelog
Additions
- #6652 Added missing item drop event values (dropped item and itemstack)
- #6654 Improved the subcommand help colours in the /skript command.
- #6655 Added support for modifying the exploded blocks in an explode event.
Bug Fixes
- #6624 Fixed unexpected math parsing issues that could occur when using variables.
- #6642 Fixed an error that could occur from Skript attempting to normalize zero vectors.
- #6644 Fixed an issue with damaging and repairing items in slots.
- #6646 Fixed an issue where obtaining the max durability of a custom item did not work.
- #6679 Fixed an issue where beta releases were considered stable by the update checker.
- #6683 Fixed an issue where syntaxes could modify the stored values of literals.
- #6716 Fixed numerous particle issues that occurred when using Minecraft 1.20.5+.
- #6724 Fixed an issue where forcing an entity to at a vector failed.
- #6742 Fixed an issue with obtaining an entity's target that could occur when no blocks were within 100 meters.
- #6746 Fixed an issue where dropped items could not be spawned properly.
- #6747 Fixed an issue where obtaining the location of an inventory holder did not work.
- #6752 Fixed an issue where spawning specific fish types (other than tropical fish) did not work.
API Updates / For Addon Developers
- #6624 Expressions can now declare multiple potential return types. This allows for providing more context regarding the return type of an expression (for example, Entity and Block compared to their shared supertype Object).
- #6684 Our code standards for the project have been updated. Please review the linked PR for an overview of the changes.
- #6700 The manner in which failed JUnit tests are displayed has been improved.
Click here to view the full list of commits made since 2.8.5
Notices
Java 11
From Skript 2.9.0 onwards, we will be requiring a minimum Java version of 11 to run.
Help Us Test
We have an official Discord community for beta testing Skript's new features and releases.
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.
Patch Release 2.8.5 777 days, 11 hours and 48 minutes ago
Skript 2.8.5
Skript 2.8.5 is here with some more bug fixes and quality-of-life additions. There is also early support for 1.20.5/1.20.6 (Skript will run and some basic 1.20.5/1.20.6 features will work). Further support will come in the next releases. You can report any issues on our issue tracker.
Happy Skripting!
Changelog
Additions
- #6134 Added mushroom cow alias for mooshroom.
- #6163 Added tests for vector syntaxes.
- #6525 Added support for specifying charged creeper rather than powered creeper.
- #6526 Improved the documentation of the elements expression.
- #6528 Improved the documentation of the leash effect.
- #6628 The Skript artifact name now includes the plugin version (e.g. Skript-2.8.5.jar).
- #6632 Added basic support for the new Armadillo and Bogged entities.
Bug Fixes
- #6302 Removed the outdated Location to Chunk converter.
- #6523 Fixed an issue that could occur when attempting to spawn non-spawnable entities.
- #6561 Fix the move event's example.
- #6566 Removed redundant [the] in the hotbar expression.
- #6578 Fixed an error that could occur with the inventory click event.
- #6579 Fixed function parsing issues with ambiguous parameter lists.
- Fixes locations with no world causing an error:
- #6590 Entity look at effect.
- #6589 Blocks (below, above, etc.) expression.
- #6588 Explode effect.
- #6591 Fixed an incorrect internal check that determined whether an expression was nullable.
- #6594/#6604 Improved the efficiency of element input pattern checks.
- #6595 Fixed incorrect coloring with some error messages.
- #6600 Fixed an error that could occur when setting the value of a variable.
- #6619 Fixed an issue that could occur when reloading a command on newer Paper versions.
- #6617/#6630 Fixed multiple issues that could occur when using Skript on 1.20.5/1.20.6.
Click here to view the full list of commits made since 2.8.4
Notices
Java 11
From Skript 2.9.0 onwards, we will be requiring a minimum Java version of 11 to run.
Help Us Test
We have an official Discord community for beta testing Skript's new features and releases.
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.
Patch Release 2.8.4 799 days, 3 hours and 25 minutes ago
Skript 2.8.4
Skript 2.8.4 is here and it brings with it many bug fixes. You can report any issues on our issue tracker.
Happy Skripting!
Changelog
Bug Fixes
- #6413 Adds missing attributes for MC 1.20.5
- #6473 Fixes an issue where spawning a falling block would load the chunk at 0,0.
- #6475 Fixes issue when spawning an entity at a location with no world.
- #6484 Fixes error when trying to spawn en entity from a disabled datapack.
- #6495 Fixes strings in lists not getting sorted properly.
- #6497 Adds error message to catch null return types.
- #6502 Fixes error when using invalid amounts of random characters.
- #6510 Fixes Anvil Text examples, updates Location function examples.
- #6512 Fixes unparsed literal error with the random expression.
Click here to view the full list of commits made since 2.8.3
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.
Patch Release 2.8.3 839 days, 4 hours and 26 minutes ago
Skript 2.8.3
A new month means a new patch! Skript 2.8.3 is here and it brings with it many bug fixes. You can report any issues on our issue tracker.
Happy Skripting!
Notices
If, and only if, you have the case-insensitive-variables config option set to false, you may experience slight changes to code behavior in functions. Previously, function parameters did not respect this option. This means that if you relied the bug that made the following code work (despite your config option set to false), your code will no longer work in this update.
function test(TEST: text):
broadcast {_test} # only {_TEST} is set now, not {_test}
broadcast {_test} # only {_TEST} is set now, not {_test}
Changelog
Bug Fixes
- #6233 Fixed an issue where event values for the inventory item move event were mistakenly removed.
- #6309 Fixed an issue that caused some click events to fire multiple times for a single event.
- #6192 Fixed an issue where using the groups expression with LuckPerms would cause an exception.
- #6328 Fixed an issue where multiplying or adding timespans could overflow into negative values.
- #6387 Fixed an exception when trying to get the components of a non-vector.
- #6388 Fixed function parameters not respecting the case-insensitive-variables config option.
- #6391 Fixed plain always getting the same item for aliases representing multiple items.
- #6392 Fixed bucket events returning the wrong event-block.
- #6463 Fixed the at time event failing to property trigger when a world's time was changed.
- #6455 Fixed a parser issue that caused parsing to fail for some syntax when special characters were used.
Click here to view the full list of commits made since 2.8.2
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.
Emergency Patch Release 2.8.2 866 days, 8 hours and 12 minutes ago
Skript 2.8.2
We are releasing Skript 2.8.2 to patch a critical issue that prevented the plugin from loading on Spigot versions older than 1.18. You can report any issues on our issue tracker.
Happy Skripting!
Changelog
Bug Fixes
- #6399 Fixed an issue that prevented Skript from loading on Spigot versions older than 1.18.
Click here to view the full list of commits made since 2.8.1
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.
Bug Fixes
- #6399 Fixed an issue that prevented Skript from loading on Spigot versions older than 1.18.
Click here to view the full list of commits made since 2.8.1
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.
Patch Release 2.8.1 867 days, 16 hours and 32 minutes ago
Skript 2.8.1
Skript 2.8.1 is here to resolve some of the most notable issues reported with 2.8.0. We will continue to assess stability and make fixes as necessary. As always, you can report any issues on our issue tracker.
You can view the release on GitHub here.
Happy Skripting!
Additions
- #6367 Added support for experimental entities from 1.20.3, breeze and wind charge.
Tweaks
- #6357 armour is now valid for the player armor change event.
Bug Fixes
- #6352 Fixed a mapping issue that could cause an error on shutdown.
- #6357 Fixed an issue that caused armor of %entities% to be considered a single value.
- #6358 Fixed an issue that allowed invalid function definitions to parse successfully.
- #6360 Fixed parsing issues that caused valid code like loop-value - 1 to error. Additionally, many improvements have been made to the arithmetic expression to greatly improve parsing and general stability.
- #6374 Fixed an issue that caused the scripts expression to return absolute paths for enabled scripts.
- #6375 Fixed an error that could occur when Skript attempted to interpret an unknown enumerator as a string.
- #6378 Fixed an invalid documentation link to the text tutorial.
- #6383 Fixed a syntax conflict that prevented the usage of the vector from coordinates expression.
Click here to view the full list of commits made since 2.8.0
- #6367 Added support for experimental entities from 1.20.3, breeze and wind charge.
Tweaks
- #6357 armour is now valid for the player armor change event.
Bug Fixes
- #6352 Fixed a mapping issue that could cause an error on shutdown.
- #6357 Fixed an issue that caused armor of %entities% to be considered a single value.
- #6358 Fixed an issue that allowed invalid function definitions to parse successfully.
- #6360 Fixed parsing issues that caused valid code like loop-value - 1 to error. Additionally, many improvements have been made to the arithmetic expression to greatly improve parsing and general stability.
- #6374 Fixed an issue that caused the scripts expression to return absolute paths for enabled scripts.
- #6375 Fixed an error that could occur when Skript attempted to interpret an unknown enumerator as a string.
- #6378 Fixed an invalid documentation link to the text tutorial.
- #6383 Fixed a syntax conflict that prevented the usage of the vector from coordinates expression.
Click here to view the full list of commits made since 2.8.0
- #6352 Fixed a mapping issue that could cause an error on shutdown.
- #6357 Fixed an issue that caused armor of %entities% to be considered a single value.
- #6358 Fixed an issue that allowed invalid function definitions to parse successfully.
- #6360 Fixed parsing issues that caused valid code like loop-value - 1 to error. Additionally, many improvements have been made to the arithmetic expression to greatly improve parsing and general stability.
- #6374 Fixed an issue that caused the scripts expression to return absolute paths for enabled scripts.
- #6375 Fixed an error that could occur when Skript attempted to interpret an unknown enumerator as a string.
- #6378 Fixed an invalid documentation link to the text tutorial.
- #6383 Fixed a syntax conflict that prevented the usage of the vector from coordinates expression.
Click here to view the full list of commits made since 2.8.0
Skript 2.8.0 884 days, 2 hours and 51 minutes ago
Skript 2.8.0 is here for everyone to enjoy! This release contains many new features and bug fixes to improve the Skript experience.
Below, you can familiarize yourself with the changes. As always, report any issues to our issues page! Per our new release model, we plan to release 2.8.1 on February 1st to continue addressing bugs. In the event of any critical issues, an emergency patch release may come sooner.
Happy Skripting!
⚠ Breaking Changes
- Using players in variable names will soon change from defaulting to names to defaulting to UUIDs. Warnings have been added to help smooth out this transition. See #6270 for more information.
- Removed Projectile Bounce State condition and expression. These haven't done anything for years.
- The target entity of player expression has been improved and now uses raytracing to find the player's target. This should cut down on false positives significantly, but the change in behavior may cause issues for some users who relied on its quirks.
- Parsing players from player names is now a bit more intuitive. Previously, parsing "xyz" as a player would return the first online player to contain "xyz" somewhere in their name. Now, it only returns players that start with "xyz". See #5875 for more.
- Major changes have been made to the on grow event. The grow event now has many more options to specify how you want it to listen. These changes mean that code that uses on grow of x may fire twice as often as expected.
# x -> something
on grow[th] from X
# something -> x
on grow[th] into X
# X -> Y
on grow[th] from X [in]to Y
# x is involved in some way
on grow[th] of X
- The expression durability of %item% now actually returns the durability (a pick with durability 103/160, for example, returns 103) instead of the prior behavior, where it would act like damage of %item% (returning 57 for 103/160).
- When there are multiple valid event-values for a default expression, Skript will now error and ask you to state which one you want instead of silently picking one. See the following example:
on right click on entity:
send "test"
# This will now error, because Skript doesn't know whether to
# send it to the clicked entity or the player doing the clicking.
- Arithmetic evaluation will now return <none> for a whole chain if one of the operations is illegal. Previously, adding 1 + "hello" would treat "hello" as 0 and just return 1. This now returns <none>. However, the behavior of adding things to unset values hasn't changed. 1 + {_none} still returns 1.
Changelog
Additions
- #4198 Added syntax for interacting with item cooldowns:
- a condition that checks whether a player has a cooldown for an item
- an expression to get and change the cooldown of an item for a player
- #4593 Added raw index of slot expression.
- #4595 Added loop-(counter|iteration)[-%number%] for both normal and while loop and improved performance for loop-value.
- #4614 Added the ability to only get certain item types when using the items in inventory expression.
- #4617 Added anvil repair cost expression.
- #5098 Added an expression to repeat a given string multiple times.
- #5271 Added time states for the tool change event's event-slot and for the hotbar slot expression. Also allows the ommission of the player in hotbar slot when using it in events that have an event-player.
- #5356 Added an expression for getting and changing the portal cooldown of an entity.
- #5357 Added toggle pickup for items on living entities.
- #5359 Added is jumping for living entities condition. (Paper 1.15+)
- #5365 Added syntax for interacting with an entity's active item:
- a condition that checks whether an entity's hand(s) is raised
- an expression to get an entity's active item (e.g. a bow)
- an expression to get the time they've spent using it or how long they need to keep using it to complete the action (e.g. eating)
- an expression to get the maximum time an item can be used for
- an expression to get the arrow selected in the ready arrow event
- an effect to cancel the usage of an item
- events for when a player readies an arrow and when a player stops using an item.
- #5366 Added support for getting and modifying the inventories of items, like shulker boxes.
- #5367 Added syntax to check and set whether a sign has glowing text.
- #5456 Added the ability to get all armor pieces of an entity.
- #5460 Added an event for when a player selects a stonecutting recipe.
- #5462 Added InventoryMoveItemEvent.
- #5482 Added an expression to get the vector projection of two vectors.
- #5494 Added a condition to check if an entity is left or right handed, and adds an effect to change their handedness.
- #5502 Added syntax to create vectors from directions.
- #5562 Added a condition to check if an entity has unbstructed line of sight to another entity or location.
- #5571 Added a condition to check if an entity is shorn or not. Also expands the entities that can be shorn with the shear effect.
- #5573 Added a function to clamp a value between two others.
- #5588 Added player arrow pickup event.
- #5589 Added hit block of projectile.
- #5618 Added is climbing for living entities condition.
- #5636 Added Free/Max/Total Server Memory expression.
- #5662 Added expression to return the loaded chunks of worlds.
- #5678 Added item damage to the damage expression.
- #5680 Added inventory close reason in inventory close event.
- #5683 Added event-item and event-slot to the resurrect event. If no totem is present, these values are none.
- #5763 Added Paper 1.16.5+ quit reason for finding out why a player disconnected.
- #5800 Added an event for when an entity transforms into another entity, like a zombie villager being cured or a slime splitting into smaller slimes.
- #5811 Added the ability to execute a command as a bungeecord command like /alert.
- #5814 Added returns aliases for function definition.
- #5845 Added player and offlineplayer functions.
- #5867 Added expressions to get all characters between two characters, or an amount of random characters within a range.
- #5894 Added support for keybind components in formatted messages (<keybind:value>).
- #5898 Added apply bone meal effect.
- #5948 Added an event for when players are sent the server's list of commands, as well as an expression to modify them.
- #5949 Added an expression to get a percentage of one or more numbers.
- #5961 Added the ability to listen for entities rotating, or rotating and moving, in the on move event.
- #6101 Adds an effect to copy the contents and indices of one variable into others.
- #6146 Multiple # signs at the beginning of a line now start a comment.
- #6162 Added a function isNaN(number) to check if a number is NaN.
- #6180 The syntax to get a location from a vector and a world has been re-added.
- #6198 Added Turkish translation.
Bug Fixes
- #5308 Fixed cursor slot not always returning the correct item in inventory click events.
- #5406 Fixed some order of operation issues with the difference expression.
- #5744 Fixed an issue where the error for missing enum lang entries would be printed much more often than they should be.
- #5815 Improvements to comparators and converters.
- #5878 Fixed some issues with the parsed as expression returning arrays or throwing exceptions.
- #6224 Fixed the examples for applying potion effects.
- #6229 Fixed an exception when trying to get the text input of an anvil.
- #6231 Fixed an exception when trying to print a block state.
- #6239 Fixed an exception when removing items from drops in 1.20.2+.
- #6266 Fixed a bug that caused incorrect errors to be printed when comparing things.
Removals
- #5958 Removed the projectile bounce state condition and expression. These had no function.
Read more at https://github.com/SkriptLang/Skript/releases/tag/2.8.0
on grow[th] from X
# something -> x
on grow[th] into X
# X -> Y
on grow[th] from X [in]to Y
# x is involved in some way
on grow[th] of X
send "test"
# This will now error, because Skript doesn't know whether to
# send it to the clicked entity or the player doing the clicking.
Additions
- #4198 Added syntax for interacting with item cooldowns:
- a condition that checks whether a player has a cooldown for an item
- an expression to get and change the cooldown of an item for a player
- #4593 Added raw index of slot expression.
- #4595 Added loop-(counter|iteration)[-%number%] for both normal and while loop and improved performance for loop-value.
- #4614 Added the ability to only get certain item types when using the items in inventory expression.
- #4617 Added anvil repair cost expression.
- #5098 Added an expression to repeat a given string multiple times.
- #5271 Added time states for the tool change event's event-slot and for the hotbar slot expression. Also allows the ommission of the player in hotbar slot when using it in events that have an event-player.
- #5356 Added an expression for getting and changing the portal cooldown of an entity.
- #5357 Added toggle pickup for items on living entities.
- #5359 Added is jumping for living entities condition. (Paper 1.15+)
- #5365 Added syntax for interacting with an entity's active item:
- a condition that checks whether an entity's hand(s) is raised
- an expression to get an entity's active item (e.g. a bow)
- an expression to get the time they've spent using it or how long they need to keep using it to complete the action (e.g. eating)
- an expression to get the maximum time an item can be used for
- an expression to get the arrow selected in the ready arrow event
- an effect to cancel the usage of an item
- events for when a player readies an arrow and when a player stops using an item.
- #5366 Added support for getting and modifying the inventories of items, like shulker boxes.
- #5367 Added syntax to check and set whether a sign has glowing text.
- #5456 Added the ability to get all armor pieces of an entity.
- #5460 Added an event for when a player selects a stonecutting recipe.
- #5462 Added InventoryMoveItemEvent.
- #5482 Added an expression to get the vector projection of two vectors.
- #5494 Added a condition to check if an entity is left or right handed, and adds an effect to change their handedness.
- #5502 Added syntax to create vectors from directions.
- #5562 Added a condition to check if an entity has unbstructed line of sight to another entity or location.
- #5571 Added a condition to check if an entity is shorn or not. Also expands the entities that can be shorn with the shear effect.
- #5573 Added a function to clamp a value between two others.
- #5588 Added player arrow pickup event.
- #5589 Added hit block of projectile.
- #5618 Added is climbing for living entities condition.
- #5636 Added Free/Max/Total Server Memory expression.
- #5662 Added expression to return the loaded chunks of worlds.
- #5678 Added item damage to the damage expression.
- #5680 Added inventory close reason in inventory close event.
- #5683 Added event-item and event-slot to the resurrect event. If no totem is present, these values are none.
- #5763 Added Paper 1.16.5+ quit reason for finding out why a player disconnected.
- #5800 Added an event for when an entity transforms into another entity, like a zombie villager being cured or a slime splitting into smaller slimes.
- #5811 Added the ability to execute a command as a bungeecord command like /alert.
- #5814 Added returns aliases for function definition.
- #5845 Added player and offlineplayer functions.
- #5867 Added expressions to get all characters between two characters, or an amount of random characters within a range.
- #5894 Added support for keybind components in formatted messages (<keybind:value>).
- #5898 Added apply bone meal effect.
- #5948 Added an event for when players are sent the server's list of commands, as well as an expression to modify them.
- #5949 Added an expression to get a percentage of one or more numbers.
- #5961 Added the ability to listen for entities rotating, or rotating and moving, in the on move event.
- #6101 Adds an effect to copy the contents and indices of one variable into others.
- #6146 Multiple # signs at the beginning of a line now start a comment.
- #6162 Added a function isNaN(number) to check if a number is NaN.
- #6180 The syntax to get a location from a vector and a world has been re-added.
- #6198 Added Turkish translation.
Bug Fixes
- #5308 Fixed cursor slot not always returning the correct item in inventory click events.
- #5406 Fixed some order of operation issues with the difference expression.
- #5744 Fixed an issue where the error for missing enum lang entries would be printed much more often than they should be.
- #5815 Improvements to comparators and converters.
- #5878 Fixed some issues with the parsed as expression returning arrays or throwing exceptions.
- #6224 Fixed the examples for applying potion effects.
- #6229 Fixed an exception when trying to get the text input of an anvil.
- #6231 Fixed an exception when trying to print a block state.
- #6239 Fixed an exception when removing items from drops in 1.20.2+.
- #6266 Fixed a bug that caused incorrect errors to be printed when comparing things.
Removals
- #5958 Removed the projectile bounce state condition and expression. These had no function.
Read more at https://github.com/SkriptLang/Skript/releases/tag/2.8.0
- a condition that checks whether a player has a cooldown for an item
- an expression to get and change the cooldown of an item for a player
- a condition that checks whether an entity's hand(s) is raised
- an expression to get an entity's active item (e.g. a bow)
- an expression to get the time they've spent using it or how long they need to keep using it to complete the action (e.g. eating)
- an expression to get the maximum time an item can be used for
- an expression to get the arrow selected in the ready arrow event
- an effect to cancel the usage of an item
- events for when a player readies an arrow and when a player stops using an item.
- #5308 Fixed cursor slot not always returning the correct item in inventory click events.
- #5406 Fixed some order of operation issues with the difference expression.
- #5744 Fixed an issue where the error for missing enum lang entries would be printed much more often than they should be.
- #5815 Improvements to comparators and converters.
- #5878 Fixed some issues with the parsed as expression returning arrays or throwing exceptions.
- #6224 Fixed the examples for applying potion effects.
- #6229 Fixed an exception when trying to get the text input of an anvil.
- #6231 Fixed an exception when trying to print a block state.
- #6239 Fixed an exception when removing items from drops in 1.20.2+.
- #6266 Fixed a bug that caused incorrect errors to be printed when comparing things.
Removals
- #5958 Removed the projectile bounce state condition and expression. These had no function.
Read more at https://github.com/SkriptLang/Skript/releases/tag/2.8.0
2.7.3 929 days, 18 hours and 7 minutes ago
Bug Fixes
- #6123 Fixed a priority issue that could cause the "sets" expression to match over other, better-fitting possibilities.
- #6171 Fixed an issue that caused accessing inventories in death events as well as checking the type of a spawner to be impossible.
- #6205 Location comparisons have been improved to significantly reduce the possibility of false negative results.
API Changes
- #6201 This is a behavioral change for the asynchronous execution API that was added to SkriptEvent (SkriptEvent#canExecuteAsynchronously). The SkriptEvent#check method may now be called asynchronously if the SkriptEvent can execute asynchronously. While we will not typically include behavioral changes like this in patch releases, this change was to address major performance issues that could occur from locking threads.
- #6201 This is a behavioral change for the asynchronous execution API that was added to SkriptEvent (SkriptEvent#canExecuteAsynchronously). The SkriptEvent#check method may now be called asynchronously if the SkriptEvent can execute asynchronously. While we will not typically include behavioral changes like this in patch releases, this change was to address major performance issues that could occur from locking threads.
Skript 2.7.2 Patch 930 days, 10 hours and 41 minutes ago
Skript version 2.7.2 has been released on Nov 1st
Bug Fixes
- #6038 Fixed the JavaDocs name and title elements
- #6078 Updated documentation links to the new Minecraft wiki
- #6080 Fixed issues with language nodes in command help
- #6090 Fixed the fake player count syntax for Paper
- #6103 Fixed UTF-8 encoding when building Skript
- #6106 Fixed reloading a directory with the script file effect
- #6117 Fixed an error when printing block inventories
- #6121 Fixed an issue where Skript options would not work in functions in some cases
- #6126 Fixed permission messages not showing for Skript commands.
- #6128 Fixed issue when checking if Minecraft time is between two values that span across midnight.
- #6132 Fixed floating point error that could occur when trying to loop with "x times".
Click here to view the full list of commits made since 2.7.2
2.6.2 Release 1452 days, 11 hours and 19 minutes ago
For full information regarding this release please see https://github.com/SkriptLang/Skript/releases/tag/2.6.2
Skript 3165 days, 9 hours and 42 minutes ago
Skript is a Minecraft plugin for Spigot that enables administrators to create unique and inspiring features for their servers. It is simple to use with no experience necessary. For those who already know how to write plugins, Skript makes it easy to build prototypes that can be later developed into full plugins. Altogether, Skript is more than capable of creating a feature-rich server experience.
About Skript
Originally released in 2011 on dev.bukkit.org by Njol, Skript has always been about inclusive programming. Skript is an easy-to-use language that provides a path for server admins to easily create unique and inspiring features for their Minecraft server with no prior experience necessary. Today, the project lives on GitHub and is completely community made. With thousands of contributions and community hours poured into continued development, Skript is a very powerful plugin for any server owner.
Unlike other scripting plugins, Skript's syntax is easy to understand and follow. The focus is on simple English sentences that can be written and read by anyone. No odd syntax patterns, line breaks, or difficult setups. Plus, a large, helpful, and rapidly growing community exists to provide you with the support and directions you need.
Features
Skript is packed with useful syntax for building both simple and complex creations.
Natural Syntax
Simple-to-use and easy to understand English sentences power Skript to customize your server.
Custom Commands
Define custom commands to integrate your creations or override existing ones to change their behavior.
Functions
No need to copy and paste. Functions allow you to run the same code over and over again with customizable inputs.
Effective Error Messages
While traditional errors can be harder to understand for beginners, Skript focuses on presenting them as simply as possible. If Skript is unable to fix your error for you, it will report back in clear terms what went wrong.
Extendable
The community continues to build addons that further enhance Skript's capabilities. If Skript cannot do something, it is likely that someone has built as an addon that can.
Requirements
Skript requires Spigot to work. Paper, which is a derivative of Spigot, is recommended. Skript supports only the latest patch versions of Minecraft 1.13 and newer. For example, this means that 1.16.5 is supported, but 1.16.4 is not. Minecraft 1.12 and earlier are not supported. When new Minecraft versions are released, we will work as quickly as possible to support them. It is worth noting that the latest version of Skript may work fine on new versions, but without support for any new features.
NOTE: If you must use Skript on an older Minecraft server, Skript 2.6.4 was the final release with support for versions 1.9 through 1.12. Click here to view it on GitHub.
Contributing to Skript
Skript is a large project with many parts working together. If you are new to Java, Skript is not the project for you. Due to Skript's size and development history, working on the project demands prior Java experience. It can be useful to familiarize yourself with Skript's codebase by exploring many of the addons that have been built for it (see below). Anyone interesed in contributing should review our contributing guidelines.
Downloading Skript, Addons and Scripts
Skript
You can download the latest stable version of Skript by clicking the download button above. For pre-releases, see the project's GitHub releases page. As with any plugin, place the downloaded Skript file inside the server's plugins folder. Restart the server, and once it loads, you will be ready to begin.
Addons
Addons follow the same setup as any plugin. Place the downloaded file into the server's plugins folder and restart. Some addons may have different setups or require tweaking. Be sure to review the addon's download page for any installation instructions.
Scripts
When creating a new script, simply create a new .sk file in Skript's
scripts folder. To install a script, place the file in that same
scripts folder. Restart your server or load the script using
/sk reload <file name>.
Having an Issue with Skript?
If you experience unexpected behavior with Skript, you can report it as an issue on our GitHub Repository. Understand that this platform is for bug reports only. If you need help with your scripts, please review the linked resources below.
Resources
Getting Help
Community support is available through the Spigot Forums, the skUnity Discord Server, skUnity also hosts tutorials for those new to Skript.
Skript Documentation
You can easily and quickly view all the syntax of Skript at docs.skriptlang.org. Community-built documentation is available on skUnity.
Addons and Scripts
You can find a wide selection of addons and scripts from multiple community platforms, including Spigot, and skUnity. As with any plugin or tool that has the ability to modify your server's functionality, take caution in what you install.
Skript is packed with useful syntax for building both simple and complex creations.
Natural Syntax
Simple-to-use and easy to understand English sentences power Skript to customize your server.
Custom Commands
Define custom commands to integrate your creations or override existing ones to change their behavior.
Functions
No need to copy and paste. Functions allow you to run the same code over and over again with customizable inputs.
Effective Error Messages
While traditional errors can be harder to understand for beginners, Skript focuses on presenting them as simply as possible. If Skript is unable to fix your error for you, it will report back in clear terms what went wrong.
Extendable
The community continues to build addons that further enhance Skript's capabilities. If Skript cannot do something, it is likely that someone has built as an addon that can.
Requirements
Skript requires Spigot to work. Paper, which is a derivative of Spigot, is recommended. Skript supports only the latest patch versions of Minecraft 1.13 and newer. For example, this means that 1.16.5 is supported, but 1.16.4 is not. Minecraft 1.12 and earlier are not supported. When new Minecraft versions are released, we will work as quickly as possible to support them. It is worth noting that the latest version of Skript may work fine on new versions, but without support for any new features.
NOTE: If you must use Skript on an older Minecraft server, Skript 2.6.4 was the final release with support for versions 1.9 through 1.12. Click here to view it on GitHub.
Contributing to Skript
Skript is a large project with many parts working together. If you are new to Java, Skript is not the project for you. Due to Skript's size and development history, working on the project demands prior Java experience. It can be useful to familiarize yourself with Skript's codebase by exploring many of the addons that have been built for it (see below). Anyone interesed in contributing should review our contributing guidelines.
Downloading Skript, Addons and Scripts
Skript
You can download the latest stable version of Skript by clicking the download button above. For pre-releases, see the project's GitHub releases page. As with any plugin, place the downloaded Skript file inside the server's plugins folder. Restart the server, and once it loads, you will be ready to begin.
Addons
Addons follow the same setup as any plugin. Place the downloaded file into the server's plugins folder and restart. Some addons may have different setups or require tweaking. Be sure to review the addon's download page for any installation instructions.
Scripts
When creating a new script, simply create a new .sk file in Skript's
scripts folder. To install a script, place the file in that same
scripts folder. Restart your server or load the script using
/sk reload <file name>.
Having an Issue with Skript?
If you experience unexpected behavior with Skript, you can report it as an issue on our GitHub Repository. Understand that this platform is for bug reports only. If you need help with your scripts, please review the linked resources below.
Resources
Getting Help
Community support is available through the Spigot Forums, the skUnity Discord Server, skUnity also hosts tutorials for those new to Skript.
Skript Documentation
You can easily and quickly view all the syntax of Skript at docs.skriptlang.org. Community-built documentation is available on skUnity.
Addons and Scripts
You can find a wide selection of addons and scripts from multiple community platforms, including Spigot, and skUnity. As with any plugin or tool that has the ability to modify your server's functionality, take caution in what you install.
Skript is a large project with many parts working together. If you are new to Java, Skript is not the project for you. Due to Skript's size and development history, working on the project demands prior Java experience. It can be useful to familiarize yourself with Skript's codebase by exploring many of the addons that have been built for it (see below). Anyone interesed in contributing should review our contributing guidelines.
Downloading Skript, Addons and Scripts
Skript
You can download the latest stable version of Skript by clicking the download button above. For pre-releases, see the project's GitHub releases page. As with any plugin, place the downloaded Skript file inside the server's plugins folder. Restart the server, and once it loads, you will be ready to begin.
Addons
Addons follow the same setup as any plugin. Place the downloaded file into the server's plugins folder and restart. Some addons may have different setups or require tweaking. Be sure to review the addon's download page for any installation instructions.
Scripts
When creating a new script, simply create a new .sk file in Skript's
scripts folder. To install a script, place the file in that same
scripts folder. Restart your server or load the script using
/sk reload <file name>.
Having an Issue with Skript?
If you experience unexpected behavior with Skript, you can report it as an issue on our GitHub Repository. Understand that this platform is for bug reports only. If you need help with your scripts, please review the linked resources below.
Resources
Getting Help
Community support is available through the Spigot Forums, the skUnity Discord Server, skUnity also hosts tutorials for those new to Skript.
Skript Documentation
You can easily and quickly view all the syntax of Skript at docs.skriptlang.org. Community-built documentation is available on skUnity.
Addons and Scripts
You can find a wide selection of addons and scripts from multiple community platforms, including Spigot, and skUnity. As with any plugin or tool that has the ability to modify your server's functionality, take caution in what you install.
If you experience unexpected behavior with Skript, you can report it as an issue on our GitHub Repository. Understand that this platform is for bug reports only. If you need help with your scripts, please review the linked resources below.