Merge branch 'dev/feature' into src/main/resources

Author: yzz17

.github/workflows/checkstyle.yml

@@ -16,7 +16,7 @@ jobs:
               with:
                   submodules: recursive
             - name: validate gradle wrapper
-              uses: gradle/wrapper-validation-action@v2
+              uses: gradle/actions/wrapper-validation@v4
             - name: Set up JDK 21
               uses: actions/setup-java@v4
               with:

.github/workflows/java-17-builds.yml

@@ -16,7 +16,7 @@ jobs:
               with:
                   submodules: recursive
             - name: validate gradle wrapper
-              uses: gradle/wrapper-validation-action@v2
+              uses: gradle/actions/wrapper-validation@v4
             - name: Set up JDK 21
               uses: actions/setup-java@v4
               with:

.github/workflows/java-21-builds.yml

@@ -16,7 +16,7 @@ jobs:
               with:
                   submodules: recursive
             - name: validate gradle wrapper
-              uses: gradle/wrapper-validation-action@v2
+              uses: gradle/actions/wrapper-validation@v4
             - name: Set up JDK 21
               uses: actions/setup-java@v4
               with:

.github/workflows/junit-17-builds.yml

@@ -16,7 +16,7 @@ jobs:
               with:
                   submodules: recursive
             - name: validate gradle wrapper
-              uses: gradle/wrapper-validation-action@v2
+              uses: gradle/actions/wrapper-validation@v4
             - name: Set up JDK 21
               uses: actions/setup-java@v4
               with:

.github/workflows/junit-21-builds.yml

@@ -16,7 +16,7 @@ jobs:
               with:
                   submodules: recursive
             - name: validate gradle wrapper
-              uses: gradle/wrapper-validation-action@v2
+              uses: gradle/actions/wrapper-validation@v4
             - name: Set up JDK 21
               uses: actions/setup-java@v4
               with:

.github/workflows/repo.yml

@@ -12,7 +12,7 @@ jobs:
               with:
                   submodules: recursive
             - name: validate gradle wrapper
-              uses: gradle/wrapper-validation-action@v2
+              uses: gradle/actions/wrapper-validation@v4
             - name: Set up JDK 21
               uses: actions/setup-java@v4
               with:

.gitignore

@@ -166,6 +166,9 @@ fabric.properties
 
 # Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023
 
+# Exception for the icon
+!.idea/icon.png
+
 *.iml
 modules.xml
 .idea/misc.xml

.idea/icon.png

@@ -34,6 +34,8 @@ This document does *not* cover the distribution or publication of artifacts buil
 
 Plans for a new release model began in March 2023 and several models were discussed, with this being the final version agreed upon by the organisation's administrative group and approved by the core contributors.
 
+An update to the release model was made in February 2025 to accommodate a more frequent Minecraft release schedule and to help limit update sizes further.
+
 ### Motivations
 
 The release cycle for the `2.7.0` version was significant in that it took an unusually long time and included an unusually-large number of additions and changes.
@@ -59,6 +61,11 @@ Members of the organisation and the wider community identified several problems
 
 Of these, the principle complaint is that the `2.7.0` version took a significant amount of time to finish and this had an adverse effect on the community and the wider ecosystem.
 
+As of February 2025, Mojang has committed to 'drops', which means significant upstream changes happen much more frequently. 
+This corresponds to Skript having a much higher lag time on releasing support for new content due to the mismatch in release dates.
+In addition, an uptick in contributions has led to `2.10` being one of the largest updates yet. 
+The size of the update meant that some of the previous concerns, like short notice additions and an extensive changelog, were still persistent despite the new release schedule.
+
 ### Goals
 
 Our release model has been designed to achieve the following goals:
@@ -98,6 +105,7 @@ A 'patch' version (labelled `0.0.X`) may contain:
 - Bug fixes
 - Non-impactful<sup>2</sup> improvements to existing features
 - Changes to meta content (e.g. documentation)
+- Opt-in experiments
 
 There may be **very rare** occasions when a breaking change is necessary in a patch release. These may occur if and only if: either a breaking change is required in order to fix an issue, and the issue is significant enough to need fixing in a patch rather than waiting for a major release, or an issue occurred with an inclusion in the version immediately-prior to this, which must be changed or reverted in some way.
 
@@ -138,18 +146,20 @@ A table of (expected) dates is displayed below.
 | 15th Jan | Feature release | 0.1.0                   |
 | 1st Feb  | Patch           | 0.1.1                   |
 | 1st Mar  | Patch           | 0.1.2                   |
-| 1st Apr  | Patch           | 0.1.3                   |
-| 1st May  | Patch           | 0.1.4                   |
-| 1st Jun  | Patch           | 0.1.5                   |
-| 1st Jul  | Pre-release     | 0.2.0-pre1              |
-| 15th Jul | Feature release | 0.2.0                   |
-| 1st Aug  | Patch           | 0.2.1                   |
-| 1st Sep  | Patch           | 0.2.2                   |
-| 1st Oct  | Patch           | 0.2.3                   |
-| 1st Nov  | Patch           | 0.2.4                   |
-| 1st Dec  | Patch           | 0.2.5                   |
-
-An estimated 14 releases are expected per year, with 10 patches, 2 pre-releases and 2 feature-releases that immediately follow them.
+| 1st Apr  | Pre-release     | 0.2.0-pre1              |
+| 15th Apr | Feature release | 0.2.0                   |
+| 1st May  | Patch           | 0.2.1                   |
+| 1st Jun  | Patch           | 0.2.2                   |
+| 1st Jul  | Pre-release     | 0.3.0-pre1              |
+| 15th Jul | Feature release | 0.3.0                   |
+| 1st Aug  | Patch           | 0.3.1                   |
+| 1st Sep  | Patch           | 0.3.2                   |
+| 1st Oct  | Pre-release     | 0.4.0-pre1              |
+| 15th Oct | Feature release | 0.4.0                   |
+| 1st Nov  | Patch           | 0.4.1                   |
+| 1st Dec  | Patch           | 0.4.2                   |
+
+An estimated 16 releases are expected per year, with 8 patches, 4 pre-releases and 4 feature-releases.
 
 Please note that the actual number may differ from this in cases such as:
 - A version requiring multiple pre-releases to correct mistakes (`0.3.0-pre1`, `0.3.0-pre2`)
@@ -160,15 +170,17 @@ There is no fixed timetable for the circulation of unpublished builds to the pub
 
 ### Major Version Schedule
 
-A [feature version](#feature-releases) will be released on the **15th of January** and the **15th of July**.
+A [feature version](#feature-releases) will be released on the **15th of January**, the **15th of April**, the **15th of July**, and the **15th of October**.
 
-This will include all finished content from the previous 6 months that was tested in the pre-release.
+This will include all finished content that was tested in the pre-release.
 
 Any features, additions or changes that were *not* ready or approved at the time of the pre-release may **not** be included in the feature release [according to goal 3](#goals). \
 The feature release must **not** be delayed to accomodate content that was not ready by the deadline [according to goal 5](#goals).
 
 If there is no content ready at the scheduled date of a feature release, the release will be skipped and a notice published explaining this.
 
+The April and October releases are intended to include minimal breaking changes and focus more on including new features and opt-in experiments.
+
 ### Pre-Release Schedule
 
 A [pre-release](#pre-releases) will be released on the **1st of January** and the **1st of July**, leaving two weeks before the following release for public testing to occur.

CLOCKWORK_RELEASE_MODEL.md

@@ -27,14 +27,14 @@ allprojects {
 
 dependencies {
 	shadow group: 'io.papermc', name: 'paperlib', version: '1.0.8'
-	shadow group: 'org.bstats', name: 'bstats-bukkit', version: '3.0.2'
-	shadow group: 'net.kyori', name: 'adventure-text-serializer-bungeecord', version: '4.3.2'
+	shadow group: 'org.bstats', name: 'bstats-bukkit', version: '3.1.0'
+	shadow group: 'net.kyori', name: 'adventure-text-serializer-bungeecord', version: '4.3.4'
 
 	implementation group: 'io.papermc.paper', name: 'paper-api', version: '1.21.4-R0.1-SNAPSHOT'
 	implementation group: 'com.google.code.findbugs', name: 'findbugs', version: '3.0.1'
 
 	// bundled with Minecraft 1.19.4+ for display entity transforms
-	implementation group: 'org.joml', name: 'joml', version: '1.10.5'
+	implementation group: 'org.joml', name: 'joml', version: '1.10.8'
 
 	// Plugin hook libraries
 	implementation group: 'com.sk89q.worldguard', name: 'worldguard-legacy', version: '7.0.0-SNAPSHOT', {
@@ -48,7 +48,7 @@ dependencies {
 	implementation fileTree(dir: 'lib', include: '*.jar')
 
 	testShadow group: 'junit', name: 'junit', version: '4.13.2'
-	testShadow group: 'org.easymock', name: 'easymock', version: '5.4.0'
+	testShadow group: 'org.easymock', name: 'easymock', version: '5.5.0'
 }
 
 checkstyle {

build.gradle

@@ -5,7 +5,7 @@ org.gradle.parallel=true
 
 groupid=ch.njol
 name=skript
-version=2.10.0
+version=2.10.2
 jarName=Skript.jar
 testEnv=java21/paper-1.21.4
 testEnvJavaVersion=21

gradle.properties

@@ -44,9 +44,9 @@
 import ch.njol.util.StringUtils;
 import ch.njol.util.coll.iterator.CheckedIterator;
 import ch.njol.util.coll.iterator.EnumerationIterable;
-import com.google.common.collect.Lists;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
+import io.papermc.lib.PaperLib;
 import org.bstats.bukkit.Metrics;
 import org.bukkit.*;
 import org.bukkit.command.CommandSender;
@@ -683,7 +683,7 @@ protected void afterErrors() {
 					if (TestMode.DEV_MODE) {
 						runTests(); // Dev mode doesn't need a delay
 					} else {
-						Bukkit.getWorlds().get(0).getChunkAtAsync(100, 100).thenRun(() -> runTests());
+						PaperLib.getChunkAtAsync(Bukkit.getWorlds().get(0), 100, 100).thenRun(() -> runTests());
 					}
 				}
 

skript-aliases

@@ -382,19 +382,21 @@ public boolean onCommand(CommandSender sender, Command command, String label, St
 
 			} else if (args[0].equalsIgnoreCase("gen-docs")) {
 				File templateDir = Documentation.getDocsTemplateDirectory();
+				File outputDir = Documentation.getDocsOutputDirectory();
+				outputDir.mkdirs();
+
+				Skript.info(sender, "Generating docs...");
+				JSONGenerator jsonGenerator = new JSONGenerator(templateDir, outputDir);
+				jsonGenerator.generate();
+
 				if (!templateDir.exists()) {
-					Skript.error(sender, "Cannot generate docs! Documentation templates not found at '" + Documentation.getDocsTemplateDirectory().getPath() + "'");
-					TestMode.docsFailed = true;
+					Skript.info(sender, "JSON-only documentation generated!");
 					return true;
 				}
-				File outputDir = Documentation.getDocsOutputDirectory();
-				outputDir.mkdirs();
+
 				HTMLGenerator htmlGenerator = new HTMLGenerator(templateDir, outputDir);
-				JSONGenerator jsonGenerator = new JSONGenerator(templateDir, outputDir);
-				Skript.info(sender, "Generating docs...");
 				htmlGenerator.generate(); // Try to generate docs... hopefully
-				jsonGenerator.generate();
-				Skript.info(sender, "Documentation generated!");
+				Skript.info(sender, "All documentation generated!");
 			} else if (args[0].equalsIgnoreCase("test") && TestMode.DEV_MODE) {
 				File scriptFile;
 				if (args.length == 1) {

src/main/java/ch/njol/skript/Skript.java

@@ -6,8 +6,8 @@
 import ch.njol.skript.aliases.ItemType;
 import ch.njol.skript.bukkitutil.BukkitUtils;
 import ch.njol.skript.bukkitutil.EntityUtils;
-import ch.njol.skript.bukkitutil.SkriptTeleportFlag;
 import ch.njol.skript.bukkitutil.ItemUtils;
+import ch.njol.skript.bukkitutil.SkriptTeleportFlag;
 import ch.njol.skript.classes.*;
 import ch.njol.skript.classes.registry.RegistryClassInfo;
 import ch.njol.skript.entity.EntityData;
@@ -21,6 +21,7 @@
 import ch.njol.skript.util.BlockUtils;
 import ch.njol.skript.util.PotionEffectUtils;
 import ch.njol.skript.util.StringMode;
+import ch.njol.skript.util.Utils;
 import ch.njol.util.StringUtils;
 import ch.njol.yggdrasil.Fields;
 import io.papermc.paper.world.MoonPhase;
@@ -71,10 +72,7 @@ public class BukkitClasses {
 
 	public BukkitClasses() {}
 
-	public static final Pattern UUID_PATTERN = Pattern.compile("(?i)[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}");
-
 	static {
-		final boolean GET_ENTITY_METHOD_EXISTS = Skript.methodExists(Bukkit.class, "getEntity", UUID.class);
 		Classes.registerClass(new ClassInfo<>(Entity.class, "entity")
 				.user("entit(y|ies)")
 				.name("Entity")
@@ -91,25 +89,10 @@ public BukkitClasses() {}
 				.defaultExpression(new EventValueExpression<>(Entity.class))
 				.parser(new Parser<Entity>() {
 					@Override
-					@Nullable
-					public Entity parse(final String s, final ParseContext context) {
-						UUID uuid;
-						try {
-							uuid = UUID.fromString(s);
-						} catch (IllegalArgumentException iae) {
-							return null;
-						}
-						if (GET_ENTITY_METHOD_EXISTS) {
-							return Bukkit.getEntity(uuid);
-						} else {
-							for (World world : Bukkit.getWorlds()) {
-								for (Entity entity : world.getEntities()) {
-									if (entity.getUniqueId().equals(uuid)) {
-										return entity;
-									}
-								}
-							}
-						}
+					public @Nullable Entity parse(final String s, final ParseContext context) {
+						if (Utils.isValidUUID(s))
+							return Bukkit.getEntity(UUID.fromString(s));
+
 						return null;
 					}
 
@@ -643,8 +626,10 @@ public Player parse(String string, ParseContext context) {
 						if (context == ParseContext.COMMAND || context == ParseContext.PARSE) {
 							if (string.isEmpty())
 								return null;
-							if (UUID_PATTERN.matcher(string).matches())
+
+							if (Utils.isValidUUID(string))
 								return Bukkit.getPlayer(UUID.fromString(string));
+
 							String name = string.toLowerCase(Locale.ENGLISH);
 							int nameLength = name.length(); // caching
 							List<Player> players = new ArrayList<>();
@@ -709,16 +694,11 @@ public String getDebugMessage(final Player p) {
 				.after("string", "world")
 				.parser(new Parser<OfflinePlayer>() {
 					@Override
-					@Nullable
-					public OfflinePlayer parse(final String s, final ParseContext context) {
-						if (context == ParseContext.COMMAND || context == ParseContext.PARSE) {
-							if (UUID_PATTERN.matcher(s).matches())
-								return Bukkit.getOfflinePlayer(UUID.fromString(s));
-							else if (!SkriptConfig.playerNameRegexPattern.value().matcher(s).matches())
-								return null;
+					public @Nullable OfflinePlayer parse(final String s, final ParseContext context) {
+						if (Utils.isValidUUID(s))
+							return Bukkit.getOfflinePlayer(UUID.fromString(s));
+						else if (SkriptConfig.playerNameRegexPattern.value().matcher(s).matches())
 							return Bukkit.getOfflinePlayer(s);
-						}
-						assert false;
 						return null;
 					}
 
@@ -1536,6 +1516,15 @@ public String toVariableNameString(EntitySnapshot snapshot) {
 					.description("Teleport Flags are settings to retain during a teleport.")
 					.requiredPlugins("Paper 1.19+")
 					.since("2.10"));
+
+		Classes.registerClass(new ClassInfo<>(Vehicle.class, "vehicle")
+			.user("vehicles?")
+			.name("Vehicle")
+			.description("Represents a vehicle.")
+			.since("2.10.2")
+			.changer(DefaultChangers.entityChanger)
+		);
+
 	}
 
 }

src/main/java/ch/njol/skript/SkriptCommand.java

@@ -45,6 +45,7 @@
 import org.skriptlang.skript.lang.comparator.Relation;
 
 import java.util.Objects;
+import java.util.UUID;
 
 @SuppressWarnings({"rawtypes"})
 public class DefaultComparators {
@@ -665,6 +666,10 @@ public Relation compare(EntitySnapshot snap1, EntitySnapshot snap2) {
 				}
 			});
 		}
+
+		// UUID
+		Comparators.registerComparator(UUID.class, UUID.class, (one, two) -> Relation.get(one.equals(two)));
+		Comparators.registerComparator(UUID.class, String.class, (one, two) -> Relation.get(one.toString().equals(two)));
 	}
 
 }

src/main/java/ch/njol/skript/classes/data/BukkitClasses.java

@@ -39,6 +39,8 @@
 import org.skriptlang.skript.lang.converter.Converters;
 import org.skriptlang.skript.lang.script.Script;
 
+import java.util.UUID;
+
 public class DefaultConverters {
 
 	public DefaultConverters() {}
@@ -277,6 +279,9 @@ public void setAmount(Number amount) {
 		Converters.registerConverter(Script.class, Config.class, Script::getConfig);
 		Converters.registerConverter(Config.class, Node.class, Config::getMainNode);
 
+		// UUID -> String
+		Converters.registerConverter(UUID.class, String.class, UUID::toString);
+
 //		// Entity - String (UUID) // Very slow, thus disabled for now
 //		Converters.registerConverter(String.class, Entity.class, new Converter<String, Entity>() {
 //