Merge patch into master

.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

CLOCKWORK_RELEASE_MODEL.md

@@ -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.

build.gradle

@@ -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 {

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

@@ -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());
 					}
 				}
 

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

@@ -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/classes/data/BukkitClasses.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,7 +21,6 @@
 import ch.njol.skript.util.BlockUtils;
 import ch.njol.skript.util.PotionEffectUtils;
 import ch.njol.skript.util.StringMode;
-import ch.njol.util.StringUtils;
 import ch.njol.yggdrasil.Fields;
 import io.papermc.paper.world.MoonPhase;
 import org.bukkit.*;
@@ -1536,6 +1535,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("INSERT VERSION")
+			.changer(DefaultChangers.entityChanger)
+		);
+
 	}
 
 }

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

@@ -99,21 +99,24 @@ public class DefaultOperations {
 		// Timespan - Number
 		// Number - Timespan
 		Arithmetics.registerOperation(Operator.MULTIPLICATION, Timespan.class, Number.class, (left, right) -> {
-			long scalar = right.longValue();
-			if (scalar < 0)
+			double scalar = right.doubleValue();
+			if (scalar < 0 || !Double.isFinite(scalar))
 				return null;
-			return new Timespan(Math2.multiplyClamped(left.getAs(TimePeriod.MILLISECOND), scalar));
+			double value = left.getAs(TimePeriod.MILLISECOND) * scalar;
+			return new Timespan((long) Math.min(value, Long.MAX_VALUE));
 		}, (left, right) -> {
-			long scalar = left.longValue();
-			if (scalar < 0)
+			double scalar = left.doubleValue();
+			if (scalar < 0 || !Double.isFinite(scalar))
 				return null;
-			return new Timespan(scalar * right.getAs(TimePeriod.MILLISECOND));
+			double value = right.getAs(TimePeriod.MILLISECOND) * scalar;
+			return new Timespan((long) Math.min(value, Long.MAX_VALUE));
 		});
 		Arithmetics.registerOperation(Operator.DIVISION, Timespan.class, Number.class, (left, right) -> {
-			long scalar = right.longValue();
-			if (scalar <= 0)
+			double scalar = right.doubleValue();
+			if (scalar <= 0 || !Double.isFinite(scalar))
 				return null;
-			return new Timespan(left.getAs(TimePeriod.MILLISECOND) / scalar);
+			double value = left.getAs(TimePeriod.MILLISECOND) / scalar;
+			return new Timespan((long) Math.min(value, Long.MAX_VALUE));
 		});
 
 		// Timespan / Timespan = Number

src/main/java/ch/njol/skript/doc/Documentation.java

@@ -179,7 +179,10 @@ protected static String cleanPatterns(final String patterns) {
 	}
 
 	protected static String cleanPatterns(String patterns, boolean escapeHTML) {
+		return cleanPatterns(patterns, escapeHTML, true);
+	}
 
+	protected static String cleanPatterns(String patterns, boolean escapeHTML, boolean useLinks) {
 		String cleanedPatterns = escapeHTML ? escapeHTML(patterns) : patterns;
 
 		cleanedPatterns = CP_PARSE_MARKS_PATTERN.matcher(cleanedPatterns).replaceAll(""); // Remove marks
@@ -268,8 +271,13 @@ protected static String cleanPatterns(String patterns, boolean escapeHTML) {
 					first = false;
 					final NonNullPair<String, Boolean> p = Utils.getEnglishPlural(c);
 					final ClassInfo<?> ci = Classes.getClassInfoNoError(p.getFirst());
+
 					if (ci != null && ci.hasDocs()) { // equals method throws null error when doc name is null
-						b.append("<a href='./classes.html#").append(p.getFirst()).append("'>").append(ci.getName().toString(p.getSecond())).append("</a>");
+						if (useLinks) {
+							b.append("<a href='./classes.html#").append(p.getFirst()).append("'>").append(ci.getName().toString(p.getSecond())).append("</a>");
+						} else {
+							b.append(ci.getName().toString(p.getSecond()));
+						}
 					} else {
 						b.append(c);
 						if (ci != null && ci.hasDocs())
@@ -286,7 +294,12 @@ private static void insertSyntaxElement(final PrintWriter pw, final SyntaxElemen
 		Class<?> elementClass = info.getElementClass();
 		if (elementClass.getAnnotation(NoDoc.class) != null)
 			return;
-		if (elementClass.getAnnotation(Name.class) == null || elementClass.getAnnotation(Description.class) == null || elementClass.getAnnotation(Examples.class) == null || elementClass.getAnnotation(Since.class) == null) {
+		if (elementClass.getAnnotation(Name.class) == null
+			|| elementClass.getAnnotation(Description.class) == null
+			|| (!elementClass.isAnnotationPresent(Examples.class)
+			&& !elementClass.isAnnotationPresent(Example.class)
+			&& !elementClass.isAnnotationPresent(Example.Examples.class))
+			|| elementClass.getAnnotation(Since.class) == null) {
 			Skript.warning("" + elementClass.getSimpleName() + " is missing information");
 			return;
 		}

src/main/java/ch/njol/skript/doc/Example.java

@@ -0,0 +1,50 @@
+package ch.njol.skript.doc;
+
+import java.lang.annotation.*;
+
+/**
+ * An example to be used in documentation for the annotated element.
+ * Multiple example annotations can be stacked on a single syntax element.
+ * <p>
+ * Each annotation should include a single example.
+ * This can be used instead of the existing {@link ch.njol.skript.doc.Examples} annotation.
+ * <p>
+ * <b>Multi-line examples</b> should use multi-line strings.
+ * Note that whitespace and quotes do not need to be escaped in this mode.
+ * The indentation will start from the least-indented line (and most IDEs provide a guideline to show this).
+ * <pre>{@code
+ * @Example("set player's health to 1")
+ * @Example("""
+ * 		if player's health is greater than 10:
+ * 			send "Wow you're really healthy!"
+ * 		""")
+ * @Example("""
+ * 		# sets the player's health to 1
+ * 		set player's health to 1""")
+ * public class MyExpression extends ... {
+ * }
+ * }</pre>
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Repeatable(Example.Examples.class)
+@Documented
+public @interface Example {
+
+	String value();
+
+	boolean inTrigger() default true; // todo needed?
+
+	/**
+	 * The internal container annotation for multiple examples.
+	 */
+	@Target(ElementType.TYPE)
+	@Retention(RetentionPolicy.RUNTIME)
+	@Documented
+	@interface Examples {
+
+		Example[] value();
+
+	}
+
+}