- Author SkriptLang
- Creation date
- Featured
-
Welcome to skUnity!
Welcome to skUnity! This is a forum where members of the Skript community can communicate and interact. Skript Resource Creators can post their Resources for all to see and use.
If you haven't done so already, feel free to join our official Discord server to expand your level of interaction with the community!
Now, what are you waiting for? Join the community now!
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.
Code:set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} [SIZE=7]"hello" is now removed[/SIZE] broadcast the first element of {queue} [SIZE=7]"world" is now removed[/SIZE] [SIZE=7]queue is empty[/SIZE]
Code: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} [SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]
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:
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.Code:set {_a} to 5 set {_b} to "some string" ... do stuff ... set {[i]c} to {[/i]a} in lowercase # oops i used the wrong variable
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:
Code:{_var} # can use type hints {_var::%player's name%} # can't use type hints
Runtime Error Catching
Enable by adding using error catching to your script.
A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors.
Code:catch runtime errors: ... set worldborder center of {[i]border} to {[/i]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:
Code: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 {[i]item} to {[/i]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
Code:set the equipment slot of {_item} to helmet slot set {[i]component} to the equippable component of {[/i]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-XeijiFirst contribution!
- @Efnilite
- @erenkarakal
- @kayerajava
- @mvanhorn
- @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.
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.
Code:set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} [SIZE=7]"hello" is now removed[/SIZE] broadcast the first element of {queue} [SIZE=7]"world" is now removed[/SIZE] [SIZE=7]queue is empty[/SIZE]
Code: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} [SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]
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:
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.Code:set {_a} to 5 set {_b} to "some string" ... do stuff ... set {[i]c} to {[/i]a} in lowercase # oops i used the wrong variable
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:
Code:{_var} # can use type hints {_var::%player's name%} # can't use type hints
Runtime Error Catching
Enable by adding using error catching to your script.
A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors.
Code:catch runtime errors: ... set worldborder center of {[i]border} to {[/i]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:
Code: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 {[i]item} to {[/i]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
Code:set the equipment slot of {_item} to helmet slot set {[i]component} to the equippable component of {[/i]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
- @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.
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 RELEASE[/i]MODEL.md]release model, 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:
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:Code:send "<red>Hello there <bold>%player%!"
Code:send "<rainbow>Wow this text is super colorful!"You can read more on Paper's documentation website about using MiniMessage and the features it offers: https://docs.papermc.io/adventure/minimessage/formatCode:[SIZE=7]this will show a stone block in the message[/SIZE] [SIZE=7]sprite tags are not processed automatically, so we use the formatted expression[/SIZE] send formatted "Look at my <sprite:blocks:block/stone>!"
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:
If we wanted to add another tag, say sprites, we simply add it to the list:Code:safe tags: color, decorations, gradient, rainbow, reset, transition, pride, shadowColor
Code: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:
Code: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 {[i]bonus} to data tag "myserver:damage[/i]bonus" of attacker's tool if {_bonus} is set: add {_bonus} to damage
You can read more about Persistent Data in the new tutorial available on our new documentation site (in beta).
Region Hook Deprecation
With this release, we are deprecating Skript's region hooks for future removal. They have been unmaintained for some time and are full of difficult to resolve issues.
As an alternative, we have developed skript-worldguard, an official addon providing far more extensive support for WorldGuard.
You can read more about skript-worldguard on its repository: https://github.com/SkriptLang/skript-worldguard
We do not currently have any plans to offer addons for other region plugins.
(API) Event Value Registry
Following our efforts to modernize syntax registration, we are introducing a new, registry-based approach for event values. This system features new benefits such as custom identifiers (event-X), enhanced event validation, and support for changers (other than SET).
Here is an example of the full process:
Code:// Obtaining the event value registry EventValueRegistry registry = addon.registry(EventValueRegistry.class); // Registering a simple event value registry.register(EventValue.simple(WorldEvent.class, World.class, WorldEvent::getWorld)); // Builder option for more complex values (changers, time state) registry.register(EventValue.builder(PlayerItemConsumeEvent.class, ItemStack.class) .getter(PlayerItemConsumeEvent::getItem) .registerChanger(ChangeMode.SET, PlayerItemConsumeEvent::setItem) .time(Time.NOW) .build());
For more information, you can consult the relevant pull request: 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.
Code:set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} [SIZE=7]"hello" is now removed[/SIZE] broadcast the first element of {queue} [SIZE=7]"world" is now removed[/SIZE] [SIZE=7]queue is empty[/SIZE]
Code: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} [SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]
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:
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.Code:set {_a} to 5 set {_b} to "some string" ... do stuff ... set {[i]c} to {[/i]a} in lowercase # oops i used the wrong variable
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:
Code:{_var} # can use type hints {_var::%player's name%} # can't use type hints
Runtime Error Catching
Enable by adding using error catching to your script.
A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors.
Code:catch runtime errors: ... set worldborder center of {[i]border} to {[/i]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:
Code: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 {[i]item} to {[/i]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
Code:set the equipment slot of {_item} to helmet slot set {[i]component} to the equippable component of {[/i]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
- @Efnilite
- @erenkarakal
- @miberss
- @MrScopes
- @Pesekjak
- @sovdeeth
- @tibisabau
- @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.
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 RELEASE[/i]MODEL.md]release model, we plan to release 2.15.0 on April 15th. We may release additional pre-releases before then should the need arise.
Happy Skripting!
Major Changes
Adventure and MiniMessage Integration
After several months of testing, we are excited to share that Skript is now using Adventure and MiniMessage!
What is Adventure and/or MiniMessage?
Adventure is Paper's approach for supporting Minecraft's user interface elements. This includes chat messages, titles, player tablists, and more. These elements support all kinds of features, the most notable being colors and text decorations (e.g., bold, italic, etc.). Adventure is used throughout Paper, so by making this change, Skript is better aligned to support Paper's current and upcoming features.
MiniMessage is a way of representing these features in a text-based format. Skript has long used its own similar system, which most skripters are familiar with:
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:Code:send "<red>Hello there <bold>%player%!"
Code:send "<rainbow>Wow this text is super colorful!"You can read more on Paper's documentation website about using MiniMessage and the features it offers: https://docs.papermc.io/adventure/minimessage/formatCode:[SIZE=7]this will show a stone block in the message[/SIZE] [SIZE=7]sprite tags are not processed automatically, so we use the formatted expression[/SIZE] send formatted "Look at my <sprite:blocks:block/stone>!"
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:
If we wanted to add another tag, say sprites, we simply add it to the list:Code:safe tags: color, decorations, gradient, rainbow, reset, transition, pride, shadowColor
Code: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:
Code: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 {[i]bonus} to data tag "myserver:damage[/i]bonus" of attacker's tool if {_bonus} is set: add {_bonus} to damage
You can read more about Persistent Data in the new tutorial available on our new documentation site (in beta).
Region Hook Deprecation
With this release, we are deprecating Skript's region hooks for future removal. They have been unmaintained for some time and are full of difficult to resolve issues.
As an alternative, we have developed skript-worldguard, an official addon providing far more extensive support for WorldGuard.
You can read more about skript-worldguard on its repository: https://github.com/SkriptLang/skript-worldguard
We do not currently have any plans to offer addons for other region plugins.
(API) Event Value Registry
Following our efforts to modernize syntax registration, we are introducing a new, registry-based approach for event values. This system features new benefits such as custom identifiers (event-X), enhanced event validation, and support for changers (other than SET).
Here is an example of the full process:
Code:// Obtaining the event value registry EventValueRegistry registry = addon.registry(EventValueRegistry.class); // Registering a simple event value registry.register(EventValue.simple(WorldEvent.class, World.class, WorldEvent::getWorld)); // Builder option for more complex values (changers, time state) registry.register(EventValue.builder(PlayerItemConsumeEvent.class, ItemStack.class) .getter(PlayerItemConsumeEvent::getItem) .registerChanger(ChangeMode.SET, PlayerItemConsumeEvent::setItem) .time(Time.NOW) .build());
For more information, you can consult the relevant pull request: 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.
Code:set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} [SIZE=7]"hello" is now removed[/SIZE] broadcast the first element of {queue} [SIZE=7]"world" is now removed[/SIZE] [SIZE=7]queue is empty[/SIZE]
Code: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} [SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]
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:
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.Code:set {_a} to 5 set {_b} to "some string" ... do stuff ... set {[i]c} to {[/i]a} in lowercase # oops i used the wrong variable
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:
Code:{_var} # can use type hints {_var::%player's name%} # can't use type hints
Runtime Error Catching
Enable by adding using error catching to your script.
A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors.
Code:catch runtime errors: ... set worldborder center of {[i]border} to {[/i]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:
Code: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 {[i]item} to {[/i]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
Code:set the equipment slot of {_item} to helmet slot set {[i]component} to the equippable component of {[/i]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
- @Efnilite
- @erenkarakal
- @miberss
- @MrScopes
- @Pesekjak
- @sovdeeth
- @tibisabau
- @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.
Skript 2.15.0-pre1
Today, we are excited to release the first pre-release for Skript 2.15.0. This release includes a few new major features and enhancements as we lay the groundwork for some exciting things coming later this year. It's no joke either, these features are real and available now!
In accordance with supporting the last 18 months of Minecraft updates, Skript 2.15.0 supports Minecraft 1.21.1 to 1.21.11. Newer versions may also work but were not tested at time of release. Paper is required.
Below, you can familiarize yourself with the changes. Additionally, by clicking here, you can view the list of new syntax on our documentation site. As always, report any issues to our issues page!
Per our RELEASE[/i]MODEL.md]release model, we plan to release 2.15.0 on April 15th. We may release additional pre-releases before then should the need arise.
Happy Skripting!
Major Changes
Adventure and MiniMessage Integration
After several months of testing, we are excited to share that Skript is now using Adventure and MiniMessage!
What is Adventure and/or MiniMessage?
Adventure is Paper's approach for supporting Minecraft's user interface elements. This includes chat messages, titles, player tablists, and more. These elements support all kinds of features, the most notable being colors and text decorations (e.g., bold, italic, etc.). Adventure is used throughout Paper, so by making this change, Skript is better aligned to support Paper's current and upcoming features.
MiniMessage is a way of representing these features in a text-based format. Skript has long used its own similar system, which most skripters are familiar with:
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:Code:send "<red>Hello there <bold>%player%!"
Code:send "<rainbow>Wow this text is super colorful!"You can read more on Paper's documentation website about using MiniMessage and the features it offers: https://docs.papermc.io/adventure/minimessage/formatCode:[SIZE=7]this will show a stone block in the message[/SIZE] send "Look at my <sprite:blocks:block/stone>!"
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:
Code: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 {[i]bonus} to data tag "myserver:damage[/i]bonus" of attacker's tool if {_bonus} is set: add {_bonus} to damage
You can read more about Persistent Data in the new tutorial available on our new documentation site (in beta).
Region Hook Deprecation
With this release, we are deprecating Skript's region hooks for future removal. They have been unmaintained for some time and are full of difficult to resolve issues.
As an alternative, we have developed skript-worldguard, an official addon providing far more extensive support for WorldGuard.
You can read more about skript-worldguard on its repository: https://github.com/SkriptLang/skript-worldguard
We do not currently have any plans to offer addons for other region plugins.
(API) Event Value Registry
Following our efforts to modernize syntax registration, we are introducing a new, registry-based approach for event values. This system features new benefits such as custom identifiers (event-X), enhanced event validation, and support for changers (other than SET).
Here is an example of the full process:
Code:// Obtaining the event value registry EventValueRegistry registry = addon.registry(EventValueRegistry.class); // Registering a simple event value registry.register(EventValue.simple(WorldEvent.class, World.class, WorldEvent::getWorld)); // Builder option for more complex values (changers, time state) registry.register(EventValue.builder(PlayerItemConsumeEvent.class, ItemStack.class) .getter(PlayerItemConsumeEvent::getItem) .registerChanger(ChangeMode.SET, PlayerItemConsumeEvent::setItem) .time(Time.NOW) .build());
For more information, you can consult the relevant pull request: 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.
Code:set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} [SIZE=7]"hello" is now removed[/SIZE] broadcast the first element of {queue} [SIZE=7]"world" is now removed[/SIZE] [SIZE=7]queue is empty[/SIZE]
Code: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} [SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]
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:
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.Code:set {_a} to 5 set {_b} to "some string" ... do stuff ... set {[i]c} to {[/i]a} in lowercase # oops i used the wrong variable
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:
Code:{_var} # can use type hints {_var::%player's name%} # can't use type hints
Runtime Error Catching
Enable by adding using error catching to your script.
A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors.
Code:catch runtime errors: ... set worldborder center of {[i]border} to {[/i]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:
Code: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 {[i]item} to {[/i]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
Code:set the equipment slot of {_item} to helmet slot set {[i]component} to the equippable component of {[/i]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
- @Efnilite
- @erenkarakal
- @miberss
- @MrScopes
- @Pesekjak
- @sovdeeth
- @tibisabau
- @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.
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.
Code:set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} [SIZE=7]"hello" is now removed[/SIZE] broadcast the first element of {queue} [SIZE=7]"world" is now removed[/SIZE] [SIZE=7]queue is empty[/SIZE]
Code: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} [SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]
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:
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.Code:set {_a} to 5 set {_b} to "some string" ... do stuff ... set {[i]c} to {[/i]a} in lowercase # oops i used the wrong variable
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:
Code:{_var} # can use type hints {_var::%player's name%} # can't use type hints
Runtime Error Catching
Enable by adding using error catching to your script.
A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors.
Code:catch runtime errors: ... set worldborder center of {[i]border} to {[/i]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:
Code:damage all players by 5 using a custom damage source: set the damage type to magic set the causing entity to {_player} set the direct entity to {_arrow} set the damage location to location(0, 0, 10)
For more details about the syntax, visit damage source on our documentation website.
Equippable Components
Enable by adding using equippable components to your script.
Equippable components allows retrieving and changing the data of an item in the usage as equipment/armor.
Below is an example of creating a blank equippable component, modifying it, and applying it to an item:
Code: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 {[i]item} to {[/i]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
Code:set the equipment slot of {_item} to helmet slot set {[i]component} to the equippable component of {[/i]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
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.
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 RELEASE[/i]MODEL.md]release model, 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:
However, it is now also possible to obtain specific potion effects:Code:set {_potions::*} to the potion effects of the player
Code: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:
The current effect has been replaced with one for applying potion effects.Code:apply an ambient potion effect of speed of tier 5 to the player for 15 seconds: hide the particles hide the icon
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:
Code:set the amplifier of {_potion} to 5 apply {[i]potion} to {[/i]entity}
Even better, it is now possible to modify potion effects that are actively applied to entities and items:
Code:set the duration of the player's active speed effect to 5 minutes set the amplifier of the player's slowness effect to 10 make the potion effects of the player's tool infinite
Hidden Effects
Full support for hidden effects has been implemented too. Hidden effects allow a player to have multiple effects of the same type. For example, if a player has speed 1 for 30 seconds, and is then affected by speed 2 for 15 seconds, after those 15 seconds, the player will have 15 seconds of speed 1 remaining.
Support for obtaining these effects has been implemented:
Code:set {_effects::*} to the player's potion effects # only active effects set {_effects::*} to the player's active effects # only active effects set {_effects::*} to the player's hidden effects # only hidden effects set {_effects::*} to the player's active and hidden effects # all effects
Just as with active effects, hidden effects support being changed too! Note that modifying a hidden effect may result in it taking precedence over the active effect.
Comparisons
Support for more lenient comparisons has been implemented too:
The 'comparison' condition (as in, x is y), can be used for exact comparisons.Code:player has speed 10 # checks type, amplifier player has a potion effect of speed for 30 seconds # checks type, duration
These comparisons are also used for removals:
Code:remove speed 10 from the player's potion effects # removed effects must match type, amplifier remove potion effect of speed for 30 seconds from the player's potion effects # removed effects must match type, duration
Complete Visual Effect Rework
Skript's visual effect system has been in dire need of repair, with limited to no documentation and multiple errors and outdated syntaxes. We've tackled this with a full rework of visual effects, meaning likely all code using visual effects will suffer breaking changes, but it was sadly necessary to get to a better state.
Visual effects are now split into 3 different types: particle effects, game effects, and entity effects. Entity effects are generally animations that can be played on specific entities, like the ravager attack animation effect. Game effects compose a variety of built-in game sounds and/or particle effects, like the combined sound+particles of the composter, or the footstep sound for a specific block. Particle effects are the standard particles you all know and love from /particle. We've overhauled the system to provide easier access to data-driven particles like dust; you can now draw red dust particle at player!
We've also added some syntax to help users better understand and use the admittedly labyrinthine particle api in the form of scale, distribution, and velocity support, rather than simply offset (though you can still set offset manually!).
Drawing a particle should look more like this, now:Code:[SIZE=7]sets the random distribution of the particle[/SIZE] set particle distribution of {_flame particle} to vector(1,2,1) [SIZE=7]set the velocity of the flame particle. [/SIZE] [SIZE=7]Note this only works for 'directional particles' and it will override the random distribution [/SIZE] [SIZE=7](distribution and special effects like scale/velocity are mutually exclusive)[/SIZE] set the velocity of {_flame particle} to vector(1,2,1) [SIZE=7]set the scale of the explostion particle. [/SIZE] [SIZE=7]Note this only works for 'scalable particles' (explosion, sweeping edge) and it will override the random distribution [/SIZE] [SIZE=7](distribution and special effects like scale/velocity are mutually exclusive)[/SIZE] set the scale of {_explosion particle} to 2.5
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.Code: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
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.
Code:function multiply(a: number, b: number) returns number: return {[i]a} * {[/i]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.
Code:function add(a: number, b: number) returns number: return {[i]a} + {[/i]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.
Code:for {[i]index}, {[/i]value} in {my list::*}: broadcast "%{[i]index}%: %{[/i]value}%"
Code:for each {_player} in all players: send "Hello %{[i]player}%!" to {[/i]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:
Code:set {_list::a} to "Hello" set {_list::b} to "World!" set {_list::sublist::c} to "I'm nested!" [SIZE=7]This behaves the same as the same as 'print[i]list(recursive keyed {[/i]list::*})'.[/SIZE] [SIZE=7]This is only true for function parameter.[/SIZE] print[i]list(keyed {[/i]list::*}) [SIZE=7]Prints:[/SIZE] [SIZE=7]a -[quote][/quote]Hello[/SIZE] [SIZE=7]b -[quote][/quote]World![/SIZE] [SIZE=7]sublist::c -[quote][/quote]I'm nested![/SIZE] function print_list(list: objects): loop {_list::*}: broadcast "%loop-index% -[quote][/quote]%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:
This has been changed toCode: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.
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.Code: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
- [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.
Code:set {queue} to a new queue of "hello" and "world" broadcast the first element of {queue} [SIZE=7]"hello" is now removed[/SIZE] broadcast the first element of {queue} [SIZE=7]"world" is now removed[/SIZE] [SIZE=7]queue is empty[/SIZE]
Code: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} [SIZE=7]players 1 and 2 are guaranteed to be distinct[/SIZE]
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:
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.Code:set {_a} to 5 set {_b} to "some string" ... do stuff ... set {[i]c} to {[/i]a} in lowercase # oops i used the wrong variable
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:
Code:{_var} # can use type hints {_var::%player's name%} # can't use type hints
Runtime Error Catching
Enable by adding using error catching to your script.
A new catch [run[ ]time] error[s] section allows you to catch and suppress runtime errors within it and access them later with [the] last caught [run[ ]time] errors.
Code:catch runtime errors: ... set worldborder center of {[i]border} to {[/i]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:
Code:damage all players by 5 using a custom damage source: set the damage type to magic set the causing entity to {_player} set the direct entity to {_arrow} set the damage location to location(0, 0, 10)
For more details about the syntax, visit damage source on our documentation website.
Equippable Components
Enable by adding using equippable components to your script.
Equippable components allows retrieving and changing the data of an item in the usage as equipment/armor.
Below is an example of creating a blank equippable component, modifying it, and applying it to an item:
Code: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 {[i]item} to {[/i]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
Code:set the equipment slot of {_item} to helmet slot set {[i]component} to the equippable component of {[/i]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
- @Fusezion
- @isuniverseok-ua
- @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.