Skript 2.10.0-pre1

Today, we are kicking off the new year with Skript 2.10.0 Pre-Release 1! As a pre-release, be warned that there may be bugs! We do not recommend running this version on your production servers. This release contains more than 150 new features, bug fixes, and API updates to play around with!

Below, you can familiarize yourself with the changes. Additionally, by clicking here, you can view the list of new syntax on our documentation site. As always, report any issues to our issues page!

Per our release model, we plan to release 2.10.0 on January 15th. We may release additional pre-releases before then should the need arise.

Happy Skripting!

Major Changes

rabbit's foot -> rabbit foot
gold helmet -> golden helmet
any sword -> tag "swords"
waterlogged oak stairs -> oak_stairs[waterlogged=true]

Minecraft Tags

Skript now supports the ability to use Minecraft tags (#minecraft:swords, #minecraft:logs, etc.). These are being introduced as a replacement for the current category aliases (any sword, any log) and should provide much more flexibilty. You can even create your own tags!

set {_tag} to tag "swords"
give the player a random item out of {_tag}'s tag values
if the player's tool is tagged as item tag "minecraft:piglin_food":
    send "Yum!"
register an item tag named "my_favorite_blocks" using oak log, stone, and podzol

Display Entities

The long-awaited support for display entities is finally here! 2.10 includes a lot of syntax for creating, manipulating, and using display entities.

spawn an oak log block display at player:
    set the display scale of the display to vector(1, 10, 1)
    set the display translation of the display to vector(0.5, 0.5, 0.5)
    rotate display around its local y axis by 45 degrees
    set the view range of display to 2

More display syntax can be found on the docs.

Variable Starting Character Reservations

Some characters are reserved at the start of variable names. Users will receive a warning when trying to use them.
This is so that these characters will be available for special variable functionality in future versions.

The following characters are reserved:

• {~variable}
• {.variable}
• {$variable}
• {!variable}
• {&variable}
• {^variable}
• {*variable}
• {+variable}
• {-variable}

Registration API (Preview)

This update includes the initial preview of a new Skript/Addon API, starting with addon registration and syntax registration.

The main Skript (JavaPlugin) class now has a new method, instance(), which provides access to the modern Skript class. This class contains the registered addons and the new SyntaxRegistry, which holds all of Skript's (and its addon's) registered syntax.

A tutorial with full usage information will be coming in the near future. For now, the full details are available at the pull request.

🧪 Experimental Features

Experimental features allow users to enable syntax on a per-script basis: some of these features are new proposals that we are testing, others may have unsafe or complex elements that regular users don't want.

Experimental features can be enabled by adding 'using %feature name%' at the top of a script.

Please note that anything marked as experimental is subject to changes in future versions.

For-Each Loop

A new kind of loop syntax that stores the loop index and value in variables for convenience.

This can be used to avoid confusion when nesting multiple loops inside each other.

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

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

All existing loop features are also available in this section.

Enabling Flag

using for loops

Queue

A collection that removes elements whenever they are requested.

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

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

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

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

# queue is empty

set {queue} to a new queue of all players

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

Queues can be looped over like a regular list.

Enabling Flag

using queues

Script Reflection

This feature includes:

• The ability to reference a script in code.
• Finding and running functions by name.
• Reading configuration files and values.

Enabling Flag

using script reflection

⚠ Breaking Changes

• Out-of-range dates will now return '0 seconds' instead of 'none' in the 'time since' expression:

if time since {_date} is less than 3 seconds:

# Previously, if {_date} was in the future, this would be false.
# Now, this is true, since `time since {_date}` evaluates to 0 seconds.

# These situations will not change:
# {_date} more than 3 seconds ago     -> false
# {_date} between 0 and 3 seconds ago -> true

• The existing 'fish' event has been replaced by more specific and useful events.
• The 'kill' effect now bypasses totems of undying.
• For the 'script' effect, support for using 'skript %string%' was removed. Simply use 'script %string%' or 'skript file %string%'.
• The 'future event-block' in the 'block break' event was removed. It did not work in many cases due to API limitations.
• In the VariablesStorage class, the field 'databaseName' is no longer 'protected', and the constructor parameter now represents the database type rather than name. See #7074 for full details.
• In the Skript class, the syntax element info getters (e.g. 'getStatements') now return unmodifiable collections.
• Numerous API classes were deprecated, and many long deprecated API classes were removed. As a result, addons will need to be recompiled against 2.10 to work. See the pull request for full details.

Changelog

Additions

• #5518 Adds support for obtaining multiple random numbers at once with the 'random numbers' expression.
• #5601 Adds syntax for working with display entities. Involves spawning, translating, scaling, rotating, and many other interations with displays.
• #6203 Adds a 'time until' expression along with a condition for whether a date is in the past or future.
• #6419 Adds an expression for changing the custom chat completions of players.
• #6427 Adds support for entity leashing events.
• #6439 Adds a '/skript list' command which displays the current enabled and disabled scripts.
• #6498 Adds support for teleport flags to the 'teleport' effect. Teleport flags allow retaining entity properties such as position and direction during a teleport.
• #6532 Adds the entity potion effect event, which occurs when an entity gains or loses an effect.
• #6562 Adds experimental support for a 'for each index/value' loop syntax.
• #6638 Adds syntax for interacting with the enchantment glint of an item.
• #6698 Adds support for the changing of max stack sizes for items and inventories.
• #6719 Adds experimental support for configuration reading and navigation.
• #6741 Adds the ability to use gamemodes with the 'is invulnerable' condition.
• #6768 Adds the piglin barter event (with barter input & output expressions).
• #6780 Adds a configuration option for all operators to see information when a script is reloaded.
• #6849 Adds a condition to check whether an entity is saddled.
• #6849 Adds support for wolf armor in the 'is wearing' condition and the 'equip' effect.
• #6850 Adds an effect to tame an entity and a condition to test whether an entity is tamed.
• #6851 Adds a configuration option to limit the number of variable backup files stored.
• #6859 Adds an expression to get the command of a command block, as well as a condition and effect to check and set the conditionality of a command block.
• #6860 Adds support for using wither projectiles in the 'is charged' condition and 'charge' effect.
• #6861 Adds an expression to get or modify the taming level of horses.
• #6867 Adds non-player (other entity) support to the 'can see' condition and 'visibility' effect.
• #6898 Adds an effect to immediately detonate a creeper, tnt minecart, primed tnt, firework, or windcharge.
• #6900 Adds support for obtaining all entities within a cuboid region in the 'entities' expression.
• #6912 Adds a section to filter lists, like the filter expression but with the ability to retain indices.
• #6930 Adds the option to exclude trailing empty strings from the 'join/split' expression.
• #6958 Adds a warning that is printed when Skript is reloaded via '/reload' or similar means.
• #6960 Adds a warning for unreachable code (for example, code following a return effect in a function).
• #6970 Adds support for deleting/resetting the prefix/suffix of players.
• #6989 Adds a new option to the 'connect' effect for transfering players to a different server (using the transfer packet in 1.20.5+).
• #6997 Adds an explicit sort order to the sort effect.
• #7001 Adds support for using shortened timespan units in commands: /my_ban_command sovde 1y 2d 3s.
• #7013 Adds support for withers to the 'is charged' condition.
• #7019 Adds an expression to get various sounds of entities, like their death sound, fall damage sound, or sound for eating a certain item.
• #7028 Adds a list transformation (mapping) expression and effect.
• #7030 Adds support for using underscores in numbers for readability: 100_000_000.
• #7040 Adds an expression to get various sound of blocks, like their break sound, footstep sound, or place sound.
• #7041 Adds basic support for wolf variants.
• #7044 Adds proper support for using custom damage causes in the 'damage' effect.
• #7045 Adds a last death location expression for players.
• #7058 Improves the description of the 'sort' effect.
• #7061 Adds body armor support to the 'armor slot' expression. Body armor is for entities such as horses and wolves (e.g. horse armor and wolf armor).
• #7064 Adds experimental support for queues, a new type of data structure.
• #7065 Adds support for updating blocks without triggering physics updates.
• #7075 Adds an event for when blocks drop items when broken.
• #7076 Adds an expression for the experience pickup cooldown of players, as well as an event for when it changes.
• #7079 Adds events and syntax for beacons.
• #7083 Adds the ability to change the 'affected entities' in an 'area of effect cloud effect' event.
• #7086 Adds expressions to interact with the item flags of items.
• #7088 Adds syntax to show, hide, and check the visibility of the custom name of an entity.
• #7088 Adds a condition to check whether a mob was spawned from a spawner.
• #7088 Adds a condition to check whether an entity is currently ticking.
• #7088 Adds support for obtaining the maximum on-fire duration to the 'entity fire burn duration' expression.
• #7093 Improves existing syntax and adds new syntax for interacting with furnaces.
• #7094 Adds an effect to open/close the lids of lidded blocks (e.g. chests, shulker boxes), as well as a condition to check whether a lid is open or not.
• #7104 Adds a condition to check whether a number is evenly divisible by another.
• #7105 Adds syntax to obtain some client chat options on Paper servers, such as whether a player has chat coloring disabled.
• #7110 Adds syntax related to animal breeding and age.
• #7113 Adds 'add' and 'remove' change support to the 'metadata' expression.
• #7126 Adds automatically generated aliases for modded items. mod:item is accessible as mod's item or item from mod. This feature is not officially supported, as Skript does not officially support any modded platforms.
• #7127 Adds support for Minecraft tags and custom tags.
• #7129 Adds a specific error message to catch incorrect usages of 'pretty quotes' instead of the regular quotation mark character.
• #7130 Allows blockdata to be used as a filter for 'click' events.
• #7131 Adds a colors event-value to the 'firework' event.
• #7132 Adds support for obtaining the 'previous' and 'next' loop-values in a loop.
• #7136 Converts the shoot effect to an effect-section for more control.
• #7137 Adds new fishing events and syntax in place of the existing 'fish' event.
• #7139 Adds universal support for using 'x degrees' and 'x radians' to represent numbers. Radians will be converted to degrees, and degrees simply represent 'x' (i.e. it has no effects).
• #7166 Adds a function to format a number based on Java's DecimalFormat system.
• #7167 Adds support for regular expression replacement in the 'replace' effect.
• #7174 Adds item support to the 'skull owner' expression.
• #7190 Adds syntax for working with player input events, including the ability to listen for specific key presses and releases.
• #7215 Adds an expression to obtain the alpha, red, green, or blue value of a color.
• #7216 Adds syntax for interacting with the patterns of banners.
• #7220 Adds syntax for using entity snapshots, which represents an entity at a specific point in time.
• #7228 Adds a warning when running with server pausing enabled.
• #7233 Adds support for salmon size variants.
• #7235 Adds 'thrice' to the 'x times' expression.
• #7242 Adds advanced support for working with loot tables.
• #7250/#7318 Add syntax for working with villager professions and types.
• #7260 Adds events for when vehicles move or collide.
• #7283 Adds the 'elytra boost' event and syntax for interacting with it.
• #7312 Adds a unicode tag for usage in text formatting.
• #7320 Adds support for using 'event-block' in command events for commands executed from a command block.
• #7334 Adds experimental support for advanced Script interaction and reflection.
  • #6702 Adds a Script type and reworks existing script-related syntax to work with this new type.
  • #6706 Improves the 'using' condition to support passing 'script' values rather than text.
  • #6713 Adds dynamic function calling through new syntax.
  • #6719 Adds configuration navigation syntax (e.g. working with the raw content of script files).

Bug Fixes

• #6970 Fixes an issue where the 'prefix/suffix' expression could error with some Vault-supporting plugins.
• #7023 Fixes performance issues with the 'book author' expression.
• #7055 Fixes the inability to spawn chest boats.
• #7124 Fixes incorrect use of 'wait' in tests.
• #7125 Fixes incorrect warnings when running tests.
• #7131 Fixes the firework event not properly filtering by color.
• #7163 Fixes the remove changer of variables so that it will only remove the first matching element in the list.
• #7165 Fixes expression conversion in some edge cases.
• #7185 Fixes several outstanding issues with boats.
• #7205 Fixes sound syntax in line with Minecraft changes.
• #7251 More types are able to be compared successfully.
• #7252 Fixes an issue where the incorrect event block was used in an 'ignition'.
• #7268 Fixes an issue where the using 'x of' expression with an invalid amount could cause an error.
• #7271 Fixes an issue where play sound on some Spigot-based servers would cause exceptions.
• #7279 Prevents illegal inventory types from being created.
• #7301 Fixes an error with boat data using any boat.
• #7304 Fixes an issue registering types with unusual plurals (gui, etc.).

Removals

• #7239 Removes the unnecessary download argument from skript command.
• #7338 Removes the 'future event-block' event-value for the 'block break' event. It did not work properly due to API limitations.

Changes

• #6203 Changes out-of-range dates to return '0 seconds' instead of 'none' for the 'time since' expression.
• #6609 Reserves some special characters at the start of variables.
• #6884 Effect commands are now enabled by default in the test environment server.
• #7073 Default names are now automatically generated for enum values missing language entries. This provides automatic support for some newer Minecraft content without waiting for a Skript update.
• #7084 Aliases loading is now performed asynchronously, slightly speeding up server starts.
• #7116 Improves the full message that is printed when Skript encounters an exception.
• #7148 Improves the kill effect, which now bypasses totems of undying.
• #7224 Improves the process in which configuration files are updated for new versions.
• #7308 Improves command suggestions and the output of the '/skript test' command.
• #7348 Adds two new test-only functions: 'line_separator' and 'file_separator'.

API Changes

• #5552 Adds internal Skript API events, like script initialization and script load events.
• #5738 Documentation is now generated using GSON.
• #5809 Improvements to condition parsing order using condition types.
• #6246 Implements the initial preview of a completely new Registration API. See the pull request for full details.
• #6670 Removes numerous deprecated classes and deprecated many more. See the pull request for full details.
• #6728 Adds type converters for addons to support common properties such as 'name' and 'amount'. See the pull request description for full details.
• #6873 Allows multiple return types in an ExpressionEntryData.
• #6905 Raises the Java build version to 17.
• #6913 Automates alias submodule updates (pre-2.10 alias sunset).
• #6918 Applied new code conventions across the 'lang' package.
• #6993 Skript Timespans now implement the full Java time API, making them compatible with external resources.
• #7072 Supports assigning the indices of list variables in the SET change mode. See the pull request for full details.
• #7037 Adds Section Expressions, expressions that can have attached sections. Only one may be allowed in a given line.
• #7043 Exposes method to get the pattern strings of a property expression.
• #7047 Enforces a limit of one database per backing file/source.
• #7053 Adds support for asynchronous JUnit tests.
• #7057 Expands the Condition API to allow for compound conditions (complex nested conditions that evaluate lazily).
• #7097 Adds default supplier support for the 'EnumClassInfo' utility.
• #7106 Avoids sending join messages when testing to avoid complexities with mocking players.
• #7106 Update messages are no longer sent in the testing environment.
• #7107 Adds a method to get the syntax patterns for property conditions.
• #7142 Adds test world, block, and location expressions for use in tests.
• #7155 Adds API that allows syntaxes to throw runtime errors in a controlled manner.
• #7168 Adds a SyntaxStringBuilder utility class which makes syntax toString implementation simpler.
  • #7244 Makes the builder return itself for convenience.
• #7169 Change 'expr' in PropertyExpression to @UnknownNullability to avoid extraneous nullability warnings.
• #7175 Skript dates are now a type of Java date, making them compatible with external resources.
• #7189 Cleans up the Timespan class and proceeds with removing uses of deprecated methods.
• #7217 Adds utility methods for changing an item's meta using a consumer, along with a method for setting item meta on an object input (handling it being a slot, itemtype, etc.).
• #7240 Remove test checks for pre-1.19 versions and tests for legacy code.
• #7241 Fixes change-in-place for variables.
• #7245 Updates Paper API version for test environments.
• #7255 Adds a helper method 'Variables#withLocalVariables()' to make it easier to run sections with copied local variables.
• #7265 Adds event support for when the main Skript configuration is reloaded.
• #7267 Moves some namespaced key utilities.
• #7269 Improves registration methods for event values.
• #7281 Adds a method to syntax for specifying event compatibility.
• #7284 Adds a 'hasEntry' method for entry containers.
• #7285 Deprecates the getter class and replaces existing getters.
• #7341 Cleans up some unused registry classes.

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

Notices

Help Us Test

We have an official Discord community for beta testing Skript's new features and releases.

Thank You

Special thanks to the contributors whose work was included in this version:

• @0XPYEX0
• @Ankoki
• @APickledWalrus
• @Asleeepp
• @Burbulinis ⭐ First contribution! ⭐
• @cheeezburga
• @Efnilite
• @EquipableMC
• @erenkarakal
• @Fusezion
• @JakeGBLP
• @kyoshuske
• @Moderocky
• @NotSoDelayed
• @Nuutrai ⭐ First contribution! ⭐
• @Phill310
• @Pikachu920
• @ShaneBeee
• @sovdeeth
• @TenFont
• @TheAbsolutionism
• @TheLimeGlass
• @UnderscoreTud

As always, if you encounter any issues or have some minor suggestions, please report them at https://github.com/SkriptLang/Skript/issues.
If you have any bigger ideas or input for the future of Skript, you can share those too at https://github.com/SkriptLang/Skript/discussions.