# 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](https://github.com/SkriptLang/Skript/blob/master/.github/contributing.md).

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

Per our [new release model](https://stable.skriptlang.org/clockwork-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!
## Major Changes
> [!IMPORTANT]
> Skript now requires **Java 11** to run. While most users are running Java 11 or newer, some may be required to update for this version. Java 11 is supported on all versions Skript supports.

- Skript can now listen to events cancelled by other plugins! Your current scripts will behave the same as they always have, but there's now the option to listen to cancelled, uncancelled, or both kinds at once:

on break of stone:
    # Normal behavior, only listens to uncancelled break events.

on uncancelled break of stone:
    # Same as 'on break of stone', only uncancelled.
    
on cancelled break of stone:
    # Will only listen to cancelled events. For example, 
    # when Worldguard prevents a block break in a protected region.

on any break of stone:
    # Will listen to both cancelled and uncancelled events.
    # Finally, 'event is cancelled' will be useful!
    
on all break of stone:
    # Same as 'on any break of stone'.

- Alternatively, you can set the new `listen to cancelled events by default` config option to `true` to allow events to listen to both uncancelled and cancelled events by default:

on break of stone:
    # Now listens to both cancelled and uncancelled events
    # if the config option is set to true.

- Added a config option to allow case-insensitive commands, so your accidental capslock won't mess you up as much!

# default: only /test
# insensitive: /test, /TEST, /tEsT...
command /test:
    trigger:
        broadcast "test!"

- Adds multi-line comments. Comments are opened and closed with **three** hashtags `###` alone on a line.

    This is code
    ###
    |
    This is a comment
    |
    ###
    This is code (again)

- Triple-hashtags in the middle of a line (e.g. `hello ### there`) will **not** start or end a comment.
- Support for string 'concatenation'!
- Text can be appended to other text (e.g. `set {text} to "hello" + "there"`) with the addition operator.
- The `concat(...)` function joins any text or objects together into a single text.
- We have exposed the `load default aliases` option in `config.sk`, which allows you to tell Skript to only load aliases in the `plugins/Skript/aliases` folder. You can provide as many or as few (even none, if you want!) aliases as you like. We will provide the default folder in the GitHub release for your convenience.

## ⚠ Breaking Changes
- `#` characters in strings no longer need to be doubled! Skript can now tell that you are writing a string and will not start a comment in the middle of it. This change means all your `##` will now appear as two `#` instead of one! This won't break hex colours, those support either one or two `#`'s, but it may break other text!

# before:
"<##aabbcc>I'm ##1, baby!" -> "I'm #1, baby!"

# after
"<##aabbcc>I'm ##1, baby!" -> "I'm ##1, baby!"
"<#aabbcc>I'm #1, baby!" -> "I'm #1, baby!"

- Timespans will now show the weeks and years instead of stopping at days:

broadcast "%{_timespan}%"
- "378 days and 20 minutes"
+ "1 year and 1 week and 6 days and 20 minutes"

- The names of function parameters can no longer include the following characters: `(){}\",`.
- `newl` and `nline` are no longer valid syntaxes for the `newline` expression, but `new line` is now valid.
- As mentioned above, `#` characters in strings no longer need to be doubled. This will mean existing doubled `#`s will appear as two, rather than one.
- The option to use `non-air` instead of `solid` in the `highest solid block` expression has been removed.
- Using `on teleport` will now trigger for non-player entities. To detect only player teleports, use `on player teleport`.

## Changelog

### Additions
- [#4661](<https://github.com/SkriptLang/Skript/pull/4661>) Added support for using weeks, months, and years in timespans. They are treated as 7 days, 30 days, and 365 days respectively. Additionally, an expression to obtain a timespan as a specific unit of time (e.g. as hours, days, etc.).
- [#5284](<https://github.com/SkriptLang/Skript/pull/5284>) Added a `lowest solid block` expression for obtaining the lowest solid block at a location.
- [#5298](<https://github.com/SkriptLang/Skript/pull/5298>) Added the ability to directly set entity and player pitch/yaw.
- [#5422](<https://github.com/SkriptLang/Skript/pull/5422>) Added support for enforcing the whitelist and working with offline players for it.
- [#5691](<https://github.com/SkriptLang/Skript/pull/5691>) Added documentation details for whether an event can be cancelled.
- [#5698](<https://github.com/SkriptLang/Skript/pull/5698>) Added support for obtaining the player represented by a player head block.
- [#6105](<https://github.com/SkriptLang/Skript/pull/6105>) Added an expression to determine whether a player is connected rather than online. Specifically, `is online` may continue to return true for players that have disconnected and then reconnected.
- [#6131](<https://github.com/SkriptLang/Skript/pull/6131>) Added the ability to play sounds from entities and specify a sound seed (instead of it being randomized each time).
- [#6160](<https://github.com/SkriptLang/Skript/pull/6160>) Added the option of using `breakable` with the existing unbreakable syntaxes.
- [#6164](<https://github.com/SkriptLang/Skript/pull/6164>) Added more internal tests for item-related syntaxes.
- [#6207](<https://github.com/SkriptLang/Skript/pull/6207>) Added the ability to listen to cancelled events.
- [#6272](<https://github.com/SkriptLang/Skript/pull/6272>) Added Russian translations.
- [#6334](<https://github.com/SkriptLang/Skript/pull/6334>) Added an expression for obtaining the codepoint of a character and the character reresented by a codepoint.
- [#6339](<https://github.com/SkriptLang/Skript/pull/6339>) Added support for filtering a heal event by entity types and by heal reason.
- [#6393](<https://github.com/SkriptLang/Skript/pull/6393>) Added `invincible` as a synonym of `invulnerable` in related syntaxes.
- [#6422](<https://github.com/SkriptLang/Skript/pull/6422>) Added a distinction when using the `actual` part of the target block expression. When `actual` is used, the hitboxes of blocks will be considered.
- [#6456](<https://github.com/SkriptLang/Skript/pull/6456>) Added syntax for bells and bell events.
- [#6506](<https://github.com/SkriptLang/Skript/pull/6506>) Added a condition for whether an entity is pathfinding.
- [#6530](<https://github.com/SkriptLang/Skript/pull/6530>) Expanded the `teleport` event to trigger when non-player entities are teleported. **NOTE: This means `on teleport` will now trigger for entities other than players. Use `on player teleport` for detecting only player teleports.**
- [#6549](<https://github.com/SkriptLang/Skript/pull/6549>) Added support for suppressing deprecated syntax warnings.
- [#6558](<https://github.com/SkriptLang/Skript/pull/6558>) Added multi-line comments using `###` (see above).
- [#6576](<https://github.com/SkriptLang/Skript/pull/6576>) Added support for combining strings using the addition (`+`) symbol.
- [#6577](<https://github.com/SkriptLang/Skript/pull/6577>) Added a configuration option to allow case-insensitive Skript commands.
- [#6596](<https://github.com/SkriptLang/Skript/pull/6596>) Added an event for when endermen become enraged.
- [#6627](<https://github.com/SkriptLang/Skript/pull/6627>) Added the ability to use expressions in the command usage entry.
- [#6639](<https://github.com/SkriptLang/Skript/pull/6639>) Added a condition, effect, and expression for managing the fire resistance property of an item.
- [#6659](<https://github.com/SkriptLang/Skript/pull/6659>) Added support for logging messages with warning and error severities.
- [#6680](<https://github.com/SkriptLang/Skript/pull/6680>) Added a configuration option to allow all events by default to trigger even when the event is already cancelled.
- [#6712](<https://github.com/SkriptLang/Skript/pull/6712>) Added an effect to show/hide item tooltips and a condition to check whether an item's tooltip is visible.
- [#6748](<https://github.com/SkriptLang/Skript/pull/6748>) Added a `whether <condition>` expression to get the boolean (true/false) representation of a condition (example: `send "Flying: %whether player is flying%"`).
- [#6749](<https://github.com/SkriptLang/Skript/pull/6749>) Added support for dividing timespans by timespans to get numbers. (`1 minute / 15 seconds = 4`)
- [#6791](<https://github.com/SkriptLang/Skript/pull/6791>) Added support for numerous 1.21 attributes.
- [#6687](<https://github.com/SkriptLang/Skript/pull/6687>) Added support for using (not creating) custom enchantments and referencing enchantments by namespace/key.
- [#6828](<https://github.com/SkriptLang/Skript/pull/6828>) Added the ability to explictly delete the message in join/death/quit events.
- [#6831](<https://github.com/SkriptLang/Skript/pull/6831>) Added the ability to prevent online lookups when using the offlineplayer function.
- [#6835](<https://github.com/SkriptLang/Skript/pull/6835>) Added the ability to also kick a player when using the ban effect.
- [#6895](<https://github.com/SkriptLang/Skript/pull/6895>) Added support for 1.21 damage causes and spawn reasons.

### Bug Fixes
- [#5422](<https://github.com/SkriptLang/Skript/pull/5422>) Fixed several issues that resulted in the whitelist condition returning incorrect results.
- [#6573](<https://github.com/SkriptLang/Skript/pull/6573>) Fixes `is connected` pattern to support only Paper server.
- [#6737](<https://github.com/SkriptLang/Skript/pull/6737>) Adds an effect to sort a list by an arbitrary mapping expression. (ex: `sort {_list-of-players::*} by {hide-and-seek::%input%::score}`)
- [#6797](<https://github.com/SkriptLang/Skript/pull/6797>) Fixes issues with the `last damage` expression.
- [#6803](<https://github.com/SkriptLang/Skript/pull/6803>) Fixes an issue where custom maximum durability did not work for items with a custom durability.
- [#6821](<https://github.com/SkriptLang/Skript/pull/6829>) Fixes block datas not being cloned upon use.
- [#6823](<https://github.com/SkriptLang/Skript/pull/6823>) Fixes inability to get the location of a double chest via the inventory.
- [#6832](<https://github.com/SkriptLang/Skript/pull/6832>) Fixes a bug where potion types could not be compared.
- [#6836](<https://github.com/SkriptLang/Skript/pull/6836>) Fixes an issue when trying to remove air from an empty slot.
- [#6846](<https://github.com/SkriptLang/Skript/pull/6846>) Fixed an issue where obtaining the slot index of the player's tool did not work.
- [#6870](<https://github.com/SkriptLang/Skript/pull/6870>) Fixed an error that could occur when attempting to set the damage of an item to a negative number.

### Removals
- [#5606](<https://github.com/SkriptLang/Skript/pull/5606>) Removed the warnings in the default variable test.
- [#6505](<https://github.com/SkriptLang/Skript/pull/6505>) Removed the player name/UUID in variables warning.
- [#6673](<https://github.com/SkriptLang/Skript/pull/6673>) Removed deprecated vector arithmetic syntax in favour of regular arithmetic.

### Changes
- [#5676](<https://github.com/SkriptLang/Skript/pull/5676>) Made Player UUIDs used by default in variables **for new config files**. That is, `{variable::%player%}` is the same as `{variable::%player's uuid%}`. If you need to continue using the name, use `{variable::%player's name%}`. Variables **will not** automatically migrate. Click to view [this discussion](https://github.com/SkriptLang/Skript/discussions/6270) for further information.
- [#5979](<https://github.com/SkriptLang/Skript/pull/5979>) Updated the `broadcast` effect to trigger message broadcast event.
- [#6361](<https://github.com/SkriptLang/Skript/pull/6361>) Strengthened function header rules to prevent the usage of invalid headers.
- [#6389](<https://github.com/SkriptLang/Skript/pull/6389>) Modified element-wise comparision to support checking whether two `and` lists are equal.
- [#6550](<https://github.com/SkriptLang/Skript/pull/6550>)/[#6694](<https://github.com/SkriptLang/Skript/pull/6694>) enhance pattern keywords to improve parsing speeds.
- [#6583](<https://github.com/SkriptLang/Skript/pull/6583>) Comment parsing has been updated to allow single `#` characters within strings. Existing strings will need updated to remove duplicate `#` characters. This change does not affect hex color tags.
- [#6733](<https://github.com/SkriptLang/Skript/pull/6733>) Updated the new line expression to remove the options of `nline` and `newl`. Additionally, `new line` is now a valid option.
- [#6834](<https://github.com/SkriptLang/Skript/pull/6834>) Exposed the `load default aliases` config option.

### API Changes
- [#6118](<https://github.com/SkriptLang/Skript/pull/6118>) Added a way to create returnable sections (a section that can return a value using the `return` effect)
- [#6276](<https://github.com/SkriptLang/Skript/pull/6276>) Fixed JUnit before and after methods being called on cleanup regardless of override.
- [#6291](<https://github.com/SkriptLang/Skript/pull/6291>) Added a parse result structure for testing scripts.
- [#6306](<https://github.com/SkriptLang/Skript/pull/6306>) Added additional parsing methods within SkriptParser.
- [#6307](<https://github.com/SkriptLang/Skript/pull/6307>) Added an exception that occurs when attempting to register an abstract class as syntax.
- [#6349](<https://github.com/SkriptLang/Skript/pull/6349>) Added a SectionExitHandler interface which allows Sections to define behavior when the `exit` or `return` syntax is used (and the section is exited).
- [#6531](<https://github.com/SkriptLang/Skript/pull/6531>) Added a ClassInfoReference system for getting more details about the usage of a ClassInfo in a script (e.g. plurality).
- [#6551](<https://github.com/SkriptLang/Skript/pull/6551>) Added support simple structures that do not have entries.
- [#6556](<https://github.com/SkriptLang/Skript/pull/6556>) Added element look-behind support for sectionless effect sections during init.
- [#6568](<https://github.com/SkriptLang/Skript/pull/6568>) Added function contracts, allowing functions to modify their return type/plurality based on their arguments.
- [#6718](<https://github.com/SkriptLang/Skript/pull/6718>) Added support for using strings as literals (e.g. `%*string%` in syntax)
- [#6798](<https://github.com/SkriptLang/Skript/pull/6798>) Added 1.21 support and modified ItemType#getRandom() to be nullable as not all Materials can be represented as an ItemStack.
- [#6806](<https://github.com/SkriptLang/Skript/pull/6806>) Switched more Skript-based types over to registries where possible.

[Click here to view the full list of commits made since 2.8.7](<https://github.com/SkriptLang/Skript/compare/2.8.7...2.9.0>)

## Notices

### Help Us Test
We have an [official Discord community](https://discord.gg/ZPsZAg6ygu) for beta testing Skript's new features and releases.

### Thank You

Special thanks to the contributors whose work was included in this version:
- @APickledWalrus
- @Asleeepp
- @AyhamAl-Ali
- @bluelhf
- @cheeezburga
- @envizar
- @EquipableMC
- @Fusezion
- @Lotzyprod
- @Moderocky
- @Mwexim
- @NotSoDelayed
- @Phill310
- @Pikachu920
- @ShaneBeee
- @sovdeeth
- @takejohn
- @TFSMads_
- @TheLimeGlass
- @TPGamesNL
- @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.