CommandAPI · JorelAli · Dec 4, 2024 · Oct 28, 2024 · Jul 4, 2024 · Jul 5, 2024
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -20,6 +20,7 @@ body:
       description: What version of Minecraft are you using? _(If using a minor version that isn't specified, such as 1.18.1, just select the latest version below it such as 1.18)_
       multiple: false
       options:
+        - "1.21.4"
         - "1.21.3"
         - "1.21.2"
         - "1.21.1"

diff --git a/Doxyfile b/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NAME           = CommandAPI
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 9.6.1
+PROJECT_NUMBER         = 9.7.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

diff --git a/README.md b/README.md
@@ -53,24 +53,25 @@ The list of what version of the CommandAPI you'll need to run on a specific vers
 | **1.16.2**         | v4.0 - 5.12, 8.3.0  - 9.4.2 | 9.4.2                        | 16                                                        |
 | **1.16.3**         | v4.2 - 5.12, 8.3.0  - 9.4.2 | 9.4.2                        | 16                                                        |
 | **1.16.4**         | v5.2 - 5.12, 8.3.0  - 9.4.2 | 9.4.2                        | 16                                                        |
-| **1.16.5**         | v5.7 - 7.0.0, 8.3.0 - 9.6.1 | 9.6.1                        | 16                                                        |
-| **1.17**           | 6.0.x - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.17.1**         | 6.1.x - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.18, 1.18.1**   | 6.5.2 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.18.2**         | 6.5.4 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.19**           | 8.3.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.19.1**         | 8.5.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.19.2**         | 8.5.1 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.19.3**         | 8.7.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.19.4**         | 8.8.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.20**           | 9.0.2 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.20.1**         | 9.0.3 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.20.2**         | 9.2.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.20.3, 1.20.4** | 9.3.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.20.5, 1.20.6** | 9.4.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.21**           | 9.5.0 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.21.1**         | 9.5.2 - 9.6.1               | 9.6.1                        | 16                                                        |
-| **1.21.2, 1.21.3** | 9.6.0 - 9.6.1               | 9.6.1                        | 16                                                        |
+| **1.16.5**         | v5.7 - 7.0.0, 8.3.0 - 9.7.0 | 9.7.0                        | 16                                                        |
+| **1.17**           | 6.0.x - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.17.1**         | 6.1.x - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.18, 1.18.1**   | 6.5.2 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.18.2**         | 6.5.4 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.19**           | 8.3.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.19.1**         | 8.5.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.19.2**         | 8.5.1 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.19.3**         | 8.7.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.19.4**         | 8.8.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.20**           | 9.0.2 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.20.1**         | 9.0.3 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.20.2**         | 9.2.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.20.3, 1.20.4** | 9.3.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.20.5, 1.20.6** | 9.4.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.21**           | 9.5.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.21.1**         | 9.5.2 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.21.2, 1.21.3** | 9.6.0 - 9.7.0               | 9.7.0                        | 16                                                        |
+| **1.21.4**         | 9.7.0                       | 9.7.0                        | 16                                                        |
 
 -----
 
@@ -410,6 +411,21 @@ This is the current roadmap for the CommandAPI (as of 30th April 2024):
         </tr>
     </thead>
     <tbody>
+        <tr>
+            <td valign="top"><b>9.7.0</b></td>
+            <td valign="top">December 2024</td>
+            <td valign="top">
+                <b>Minecraft Version Changes:</b>
+                <ul>
+                    <li>Adds support for Minecraft 1.21.4</li>
+                </ul>
+                <b>CommandAPI Changes:</b>
+                <ul>
+                    <li>https://github.com/CommandAPI/CommandAPI/pull/575 Adds a NMS independent test toolkit to allow developers to test their commands with MockBukkit</li>
+                    <li>https://github.com/CommandAPI/CommandAPI/pull/613 Adds a <code>thenNested</code> method for <code>CommandTree</code>s to reduce nesting</li>
+                </ul>
+            </td>
+        </tr>
         <tr>
             <td valign="top"><b>9.6.1</b></td>
             <td valign="top">October 2024</td>

diff --git a/commandapi-annotations/pom.xml b/commandapi-annotations/pom.xml
@@ -18,7 +18,7 @@
 	<parent>
 		<groupId>dev.jorel</groupId>
 		<artifactId>commandapi</artifactId>
-		<version>9.6.1</version>
+		<version>9.7.0</version>
 	</parent>
 
 	<artifactId>commandapi-annotations</artifactId>

diff --git a/commandapi-codecov/pom.xml b/commandapi-codecov/pom.xml
@@ -20,7 +20,7 @@
 	<parent>
 		<groupId>dev.jorel</groupId>
 		<artifactId>commandapi</artifactId>
-		<version>9.6.1</version>
+		<version>9.7.0</version>
 	</parent>
 
 	<artifactId>commandapi-codecov</artifactId>
@@ -58,6 +58,12 @@
 			<version>${project.version}</version>
 			<scope>test</scope>
 		</dependency>
+		<dependency>
+			<groupId>dev.jorel</groupId>
+			<artifactId>commandapi-bukkit-test-toolkit</artifactId>
+			<version>${project.version}</version>
+			<!-- This should not have the test scope because it contains classes whose coverage we want to analyze -->
+		</dependency>
 
 		<!-- From commandapi-bukkit-nms-dependency-mojang-mapped -->
 

diff --git a/commandapi-core/pom.xml b/commandapi-core/pom.xml
@@ -19,7 +19,7 @@
 	<parent>
 		<artifactId>commandapi</artifactId>
 		<groupId>dev.jorel</groupId>
-		<version>9.6.1</version>
+		<version>9.7.0</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 

diff --git a/commandapi-core/src/main/java/dev/jorel/commandapi/AbstractArgumentTree.java b/commandapi-core/src/main/java/dev/jorel/commandapi/AbstractArgumentTree.java
@@ -3,6 +3,7 @@
 import dev.jorel.commandapi.arguments.AbstractArgument;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 
 /**
@@ -60,6 +61,41 @@ public Impl then(final AbstractArgumentTree<?, Argument, CommandSender> tree) {
 		return instance();
 	}
 
+	/**
+	 * Creates a chain of child branches starting at this node
+	 * <p>
+	 * {@code thenNested(a, b, c)} is equivalent to {@link #then}{@code (a.then(b.then(c)))}.
+	 *
+	 * @param trees The child branches to add in a chain.
+	 * @return this tree node
+	 */
+	public final Impl thenNested(List<AbstractArgumentTree<?, Argument, CommandSender>> trees) {
+		int length = trees.size();
+		if (length == 0) {
+			return instance();
+		}
+
+		AbstractArgumentTree<?, Argument, CommandSender> combined = trees.get(length - 1);
+		for (int i = length - 2; i >= 0; i--) {
+			combined = trees.get(i).then(combined);
+		}
+
+		return then(combined);
+	}
+
+	/**
+	 * Creates a chain of child branches starting at this node
+	 * <p>
+	 * {@code thenNested(a, b, c)} is equivalent to {@link #then}{@code (a.then(b.then(c)))}.
+	 *
+	 * @param trees The child branches to add in a chain.
+	 * @return this tree node
+	 */
+	@SafeVarargs
+	public final Impl thenNested(final AbstractArgumentTree<?, Argument, CommandSender>... trees) {
+		return thenNested(Arrays.asList(trees));
+	}
+
 	List<Execution<CommandSender, Argument>> getExecutions() {
 		List<Execution<CommandSender, Argument>> executions = new ArrayList<>();
 		// If this is executable, add its execution

diff --git a/commandapi-core/src/main/java/dev/jorel/commandapi/AbstractCommandTree.java b/commandapi-core/src/main/java/dev/jorel/commandapi/AbstractCommandTree.java
@@ -3,6 +3,7 @@
 import dev.jorel.commandapi.arguments.AbstractArgument;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 
 /**
@@ -43,6 +44,41 @@ public Impl then(final AbstractArgumentTree<?, Argument, CommandSender> tree) {
 		return instance();
 	}
 
+	/**
+	 * Creates a chain of child branches starting at this node
+	 * <p>
+	 * {@code thenNested(a, b, c)} is equivalent to {@link #then}{@code (a.then(b.then(c)))}.
+	 *
+	 * @param trees The child branches to add in a chain.
+	 * @return this tree node
+	 */
+	public final Impl thenNested(List<AbstractArgumentTree<?, Argument, CommandSender>> trees) {
+		int length = trees.size();
+		if (length == 0) {
+			return instance();
+		}
+
+		AbstractArgumentTree<?, Argument, CommandSender> combined = trees.get(length - 1);
+		for (int i = length - 2; i >= 0; i--) {
+			combined = trees.get(i).then(combined);
+		}
+
+		return then(combined);
+	}
+
+	/**
+	 * Creates a chain of child branches starting at this node
+	 * <p>
+	 * {@code thenNested(a, b, c)} is equivalent to {@link #then}{@code (a.then(b.then(c)))}.
+	 *
+	 * @param trees The child branches to add in a chain.
+	 * @return this tree node
+	 */
+	@SafeVarargs
+	public final Impl thenNested(final AbstractArgumentTree<?, Argument, CommandSender>... trees) {
+		return thenNested(Arrays.asList(trees));
+	}
+
 	/**
 	 * Registers the command with a given namespace
 	 *

diff --git a/commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIHandler.java b/commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIHandler.java
@@ -185,9 +185,8 @@ public CommandAPIPlatform<Argument, CommandSender, Source> getPlatform() {
 	 * @param executor   code to be ran when the command is executed
 	 * @param converted  True if this command is being converted from another plugin, and false otherwise
 	 * @return a brigadier command which is registered internally
-	 * @throws CommandSyntaxException if an error occurs when the command is ran
 	 */
-	Command<Source> generateCommand(Argument[] args, CommandAPIExecutor<CommandSender, AbstractCommandSender<? extends CommandSender>> executor, boolean converted) {
+	public Command<Source> generateCommand(Argument[] args, CommandAPIExecutor<CommandSender, AbstractCommandSender<? extends CommandSender>> executor, boolean converted) {
 
 		// Generate our command from executor
 		return cmdCtx -> {

diff --git a/commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIPlatform.java b/commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIPlatform.java
@@ -136,7 +136,8 @@ public interface CommandAPIPlatform<Argument
 	public abstract void createDispatcherFile(File file, CommandDispatcher<Source> dispatcher) throws IOException;
 
 	/**
-	 * @return A new default Logger meant for the CommandAPI to use
+	 * @return A new default Logger meant for the CommandAPI to use. This logger will be used by the CommandAPI
+	 * if one is not set using {@link CommandAPI#setLogger(CommandAPILogger)}.
 	 */
 	public default CommandAPILogger getLogger() {
 		return new CommandAPILogger() {

diff --git a/commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIVersionHandler.java b/commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIVersionHandler.java
@@ -5,7 +5,7 @@
  * file within the commandapi-core module is NOT used at run time. Instead, the platform modules
  * replace this class with their own version that handles loads the correct class for their version.
  */
-public interface CommandAPIVersionHandler {
+public abstract class CommandAPIVersionHandler {
 
 	/**
 	 * Returns an instance of the version's implementation of CommandAPIPlatform.

diff --git a/commandapi-documentation-code/pom.xml b/commandapi-documentation-code/pom.xml
@@ -7,7 +7,7 @@
 	<parent>
 		<artifactId>commandapi</artifactId>
 		<groupId>dev.jorel</groupId>
-		<version>9.6.1</version>
+		<version>9.7.0</version>
 	</parent>
 
 	<artifactId>commandapi-documentation-code</artifactId>
@@ -48,7 +48,6 @@
 			<groupId>net.kyori</groupId>
 			<artifactId>adventure-platform-bukkit</artifactId>
 			<version>4.2.0</version>
-			<scope>test</scope>
 		</dependency>
 		<dependency>
 			<groupId>io.papermc.paper</groupId>
@@ -57,6 +56,25 @@
 			<scope>provided</scope>
 		</dependency>
 
+		<!-- Testing examples dependencies -->
+		<dependency>
+			<groupId>com.github.seeseemelk</groupId>
+			<artifactId>MockBukkit-v1.20</artifactId>
+			<version>3.9.0</version>
+		</dependency>
+		<dependency>
+			<!-- Note: This is before the other CommandAPI dependencies so example `testLoadMockCommandAPI2`
+			     can resolve the correct instance of the CommandAPIVersionHandler class -->
+			<groupId>dev.jorel</groupId>
+			<artifactId>commandapi-bukkit-test-toolkit</artifactId>
+			<version>${project.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter-engine</artifactId>
+			<version>5.8.2</version>
+		</dependency>
+
 		<!-- CommandAPI -->
 		<dependency>
 			<groupId>dev.jorel</groupId>

diff --git a/commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java b/commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java
@@ -20,6 +20,8 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  *******************************************************************************/
 
+import be.seeseemelk.mockbukkit.MockBukkit;
+import be.seeseemelk.mockbukkit.ServerMock;
 import com.mojang.brigadier.LiteralMessage;
 import com.mojang.brigadier.Message;
 import com.mojang.brigadier.ParseResults;
@@ -74,6 +76,8 @@
 import org.bukkit.scoreboard.Scoreboard;
 import org.bukkit.scoreboard.Team;
 import org.bukkit.util.EulerAngle;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
 
 import java.util.*;
 import java.util.Map.Entry;
@@ -2519,6 +2523,60 @@ void subcommands() {
 /* ANCHOR_END: subcommands4 */
 }
 
+class test {
+class Main extends JavaPlugin {
+
+}
+
+class example1 {
+/* ANCHOR: testLoadMockCommandAPI1 */
+@BeforeEach
+public void setUp() {
+    // Set up MockBukkit server
+    ServerMock server = MockBukkit.mock();
+
+    // Load the CommandAPI plugin
+    MockCommandAPIPlugin.load(config -> config
+        .missingExecutorImplementationMessage("This command cannot be run by %S")
+    );
+
+    // Load our plugin
+    MockBukkit.load(Main.class);
+}
+
+@AfterEach
+public void tearDown() {
+    // Reset for a clean slate next test
+    MockBukkit.unmock();
+}
+/* ANCHOR_END: testLoadMockCommandAPI1 */
+}
+
+class example2 {
+/* ANCHOR: testLoadMockCommandAPI2 */
+public class CustomMockCommandAPIBukkit extends MockCommandAPIBukkit {
+    // Implement a method that usually throws `UnimplementedMethodException`
+    @Override
+    public void reloadDataPacks() {
+        CommandAPI.logInfo("Simulating data pack reload");
+        // Further logic
+    }
+}
+
+@BeforeEach
+public void setUp() {
+    // Set up MockBukkit server
+    MockBukkit.mock();
+
+    // Tell the CommandAPI to use your custom platform implementation
+    CommandAPIVersionHandler.usePlatformImplementation(new CustomMockCommandAPIBukkit());
+
+    // Load CommandAPI and your plugin as mentioned above...
+}
+/* ANCHOR_END: testLoadMockCommandAPI2 */
+}
+}
+
 class tooltips {
 {
 /* ANCHOR: tooltips1 */

diff --git a/commandapi-documentation-velocity-code/pom.xml b/commandapi-documentation-velocity-code/pom.xml
@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>dev.jorel</groupId>
 		<artifactId>commandapi</artifactId>
-		<version>9.6.1</version>
+		<version>9.7.0</version>
 	</parent>
 
 	<artifactId>commandapi-documentation-velocity-code</artifactId>

diff --git a/commandapi-kotlin/commandapi-bukkit-kotlin/pom.xml b/commandapi-kotlin/commandapi-bukkit-kotlin/pom.xml
@@ -7,7 +7,7 @@
 	<parent>
 		<groupId>dev.jorel</groupId>
 		<artifactId>commandapi-kotlin</artifactId>
-		<version>9.6.1</version>
+		<version>9.7.0</version>
 	</parent>
 
 	<artifactId>commandapi-bukkit-kotlin</artifactId>