Add documentation for CommandAPI/CommandAPI#517

DerEchtePilz · DerEchtePilz · commit 8e2b80096a97 · 2025-08-22T20:52:02.000+02:00
diff --git a/docs/.vitepress/theme/upgrading/upgrading.ts b/docs/.vitepress/theme/upgrading/upgrading.ts
@@ -19,6 +19,7 @@ export const upgradingInfos: UpgradingInfo[] = [
     {from: '9.0.3', to: '9.1.0'},
     {from: '9.2.0', to: '9.3.0'},
     {from: '9.7.0', to: '10.0.0'},
+    {from: '10.1.2', to: '11.0.0'}
 ]
 
 export const keyVersions = Array.from(new Set(upgradingInfos.map(info => [info.from, info.to]).flat()));
diff --git a/docs/en/create-commands/arguments/arguments.md b/docs/en/create-commands/arguments/arguments.md
diff --git a/docs/en/create-commands/arguments/types/chat/adventure-chat-arguments.md b/docs/en/create-commands/arguments/types/chat/adventure-chat-arguments.md
@@ -8,21 +8,23 @@ authors:
 
 # Adventure chat arguments
 
-:::info
+From Paper 1.16.5 build #473 onwards, Paper now includes [Kyori's Adventure API](https://github.com/KyoriPowered/adventure-platform). This library is a replacement of the BungeeCord chat API and has all the same functionality as the BungeeCord chat API (and more!). The documentation for this API can be found [here](https://docs.adventure.kyori.net/index.html).
 
-The two following classes, `AdventureChatComponentArgument` and `AdventureChatArgument` depend on a Paper-based server which has the Adventure library. If you use this class on a server without the Adventure library, it will throw a `PaperAdventureNotFoundException`
+Since this functions very similar to the Spigot chat arguments, this page won't reiterate everything about how it works, we'll just outline some examples of how to use these arguments instead.
+Additionally, the names used here may be confusing as they are the same names as on the [Spigot chat arguments](spigot-chat-arguments.md) page but have different return types. This is because the classes on this page are only accessible using `commandapi-paper-core` or `commandapi-paper-shade`
+while the arguments on the Spigot chat arguments page are only available when using `commandapi-spigot-core` or `commandapi-spigot-shade`.
 
-:::
+:::info
 
-From Paper 1.16.5 build #473 onwards, Paper now includes [Kyori's Adventure API](https://github.com/KyoriPowered/adventure-platform). This library is a replacement of the BungeeCord chat API and has all the same functionality as the BungeeCord chat API (and more!). The documentation for this API can be found [here](https://docs.adventure.kyori.net/index.html).
+The three following classes, `ChatColorArgument`, `ChatComponentArgument` and `ChatArgument` depend on a Paper based server which has the Adventure library. If you use any of these classes on a server without the Adventure library, they will throw a `PaperAdventureNotFoundException`.
 
-Since this functions very similar to the Spigot chat arguments, this page won't reiterate everything about how it works, we'll just outline some examples of how to use these arguments instead.
+:::
 
 ## Adventure chat color argument
 
 ![Chatcolor argument in-game, displaying a list of Minecraft chat colors](/images/arguments/chatcolor.png)
 
-The `AdventureChatColorArgument` class is used to represent a given chat color (e.g., red or green). This argument returns the `NamedTextColor` object. If `reset` is passed to this argument, this will return `NamedTextColor.WHITE`.
+The `ChatColorArgument` class is used to represent a given chat color (e.g., red or green). This argument returns the `NamedTextColor` object. If `reset` is passed to this argument, this will return `NamedTextColor.WHITE`.
 
 ::::tip Example – Username color changing plugin
 
@@ -47,7 +49,7 @@ We then use the `ChatColorArgument` to change the player's name color:
 
 ## Adventure chat component argument
 
-The `AdventureChatComponentArgument` class accepts raw chat-based JSON as valid input, as declared [here](https://minecraft.wiki/w/Raw_JSON_text_format). This is converted into Adventure's `Component` class.
+The `ChatComponentArgument` class accepts raw chat-based JSON as valid input, as declared [here](https://minecraft.wiki/w/Raw_JSON_text_format). This is converted into Adventure's `Component` class.
 
 ::::tip Example – Opening a book with raw JSON content
 
@@ -72,11 +74,11 @@ We can construct a book using the Adventure API's `Book.book(Component, Componen
 
 ## Adventure chat argument
 
-The `AdventureChatArgument` class is the equivalent Adventure API class for the `ChatArgument` - it represents infinitely long strings similar to the `GreedyStringArgument` and allows entity selectors such as `@e`, `@p` and so on. The `AdventureChatArgument` returns a `Component`, similar to the `AdventureChatComponentArgument`.
+The `ChatArgument` represents infinitely long strings similar to the `GreedyStringArgument` and allows entity selectors such as `@e`, `@p` and so on. The `ChatArgument` returns a `Component`, similar to the `ChatComponentArgument`.
 
 ::::tip Example – Sending personalized messages to players
 
-We'll take the same example from the `ChatArgument` class, but using the `AdventureChatArgument` instead - We want to create a personalized message broadcasted to all users using a chat component that allows entity selectors. For this command, we want the following syntax:
+We want to create a personalized message broadcasted to all users using a chat component that allows entity selectors. For this command, we want the following syntax:
 
 ```mccmd
 /pbroadcast <message>
diff --git a/docs/en/dev-setup/setup.md b/docs/en/dev-setup/setup.md
@@ -46,16 +46,30 @@ If you've never used a build system before, I highly recommend it! It makes it e
 
 - Add the dependency to your `pom.xml`:
 
+:::tabs
+===Paper
   ```xml
   <dependencies>
       <dependency>
           <groupId>dev.jorel</groupId>
-          <artifactId>commandapi-bukkit-core</artifactId>
+          <artifactId>commandapi-paper-core</artifactId>
           <version>11.0.0-SNAPSHOT</version>
           <scope>provided</scope>
       </dependency>
   </dependencies>
   ```
+===Spigot
+  ```xml
+  <dependencies>
+      <dependency>
+          <groupId>dev.jorel</groupId>
+          <artifactId>commandapi-spigot-core</artifactId>
+          <version>11.0.0-SNAPSHOT</version>
+          <scope>provided</scope>
+      </dependency>
+  </dependencies>
+  ```
+:::
 
 </div>
 <div class="gradle">
@@ -88,21 +102,38 @@ If you've never used a build system before, I highly recommend it! It makes it e
 
   <div class="groovy">
 
+  :::tabs
+  ===Paper
   ```groovy
   dependencies {
-      compileOnly "dev.jorel:commandapi-bukkit-core:11.0.0-SNAPSHOT"
+      compileOnly "dev.jorel:commandapi-paper-core:11.0.0-SNAPSHOT"
   }
   ```
+  ===Spigot
+  ```groovy
+  dependencies {
+      compileOnly "dev.jorel:commandapi-spigot-core:11.0.0-SNAPSHOT"
+  }
+  ```
+  :::
   
   </div>
   <div class="kts">
   
+  :::tabs
+  ===Paper
   ```kotlin
   dependencies {
-      compileOnly("dev.jorel:commandapi-bukkit-core:11.0.0-SNAPSHOT")
+      compileOnly("dev.jorel:commandapi-paper-core:11.0.0-SNAPSHOT")
   }
   ```
-  
+  ===Spigot
+  ```kotlin
+  dependencies {
+      compileOnly("dev.jorel:commandapi-spigot-core:11.0.0-SNAPSHOT")
+  }
+  ```
+  :::
   </div>
 
 </div>
diff --git a/docs/en/dev-setup/shading.md b/docs/en/dev-setup/shading.md
@@ -37,32 +37,44 @@ The `onLoad(CommandAPIConfig)` method initializes the CommandAPI's loading seque
 public class CommandAPIConfig {
     CommandAPIConfig verboseOutput(boolean value); // Enables verbose logging
     CommandAPIConfig silentLogs(boolean value);    // Disables ALL logging (except errors)
-    CommandAPIConfig useLatestNMSVersion(boolean value); // Whether the latest NMS implementation should be used or not
-    CommandAPIConfig beLenientForMinorVersions(boolean value); // Whether the CommandAPI should be more lenient with minor Minecraft versions
-    CommandAPIConfig missingExecutorImplementationMessage(String value); // Set message to display when executor implementation is missing
     CommandAPIConfig dispatcherFile(File file); // If not null, the CommandAPI will create a JSON file with Brigadier's command tree
     CommandAPIConfig setNamespace(String namespace); // The namespace to use when the CommandAPI registers a command
-
-    <T> CommandAPIConfig initializeNBTAPI(Class<T> nbtContainerClass, Function<Object, T> nbtContainerConstructor); // Initializes hooks with an NBT API. See NBT arguments documentation page for more info
 }
 ```
 
 The `CommandAPIConfig` class follows a typical builder pattern (without you having to run `.build()` at the end), which lets you easily construct configuration instances.
 
-However, the `CommandAPIConfig` class is abstract and can’t be used to configure the CommandAPI directly. Instead, you must use a subclass of `CommandAPIConfig` that corresponds to the platform you’re developing for. For example, when developing for Bukkit, you should use the `CommandAPIBukkitConfig` class.
+However, the `CommandAPIConfig` class is abstract and can’t be used to configure the CommandAPI directly. Instead, you must use a subclass of `CommandAPIConfig` that corresponds to the platform you’re developing for. For example, when developing for a Bukkit-based server, you should use the `CommandAPIPaperConfig` or the `CommandAPISpigotConfig` class.
 
 <!-- TODO: Add tabs and explanations for other platforms -->
 
+:::tabs
+===Bukkit
 ```java
-public class CommandAPIBukkitConfig extends CommandAPIConfig {
-    CommandAPIBukkitConfig(JavaPlugin plugin);
+public abstract class CommandAPIBukkitConfig extends CommandAPIConfig {
+    CommandAPIBukkitConfig useLatestNMSVersion(boolean value); // Whether the latest NMS implementation should be used or not
+    CommandAPIBukkitConfig beLenientForMinorVersions(boolean value); // Whether the CommandAPI should be more lenient with minor Minecraft versions
+    CommandAPIBukkitConfig missingExecutorImplementationMessage(String value); // Set message to display when executor implementation is missing
+    <T> CommandAPIConfig initializeNBTAPI(Class<T> nbtContainerClass, Function<Object, T> nbtContainerConstructor); // Initializes hooks with an NBT API. See NBT arguments documentation page for more info
+}
+```
+===Paper
+```java
+public class CommandAPIPaperConfig extends CommandAPIBukkitConfig {
+    CommandAPIPaperConfig(LifecycleEventOwner lifecycleEventOwner);
+}
+```
+===Spigot
+```java
+public class CommandAPISpigotConfig extends CommandAPIBukkitConfig {
+    CommandAPISpigotConfig(JavaPlugin plugin);
 
-    CommandAPIBukkitConfig shouldHookPaperReload(boolean hooked); // Whether the CommandAPI should hook into the Paper-exclusive ServerResourcesReloadedEvent
-    CommandAPIBukkitConfig skipReloadDatapacks(boolean skip); // Whether the CommandAPI should reload datapacks on server load
+    CommandAPISpigotConfig skipReloadDatapacks(boolean skip); // Whether the CommandAPI should reload datapacks on server load
 }
 ```
+:::
 
-In order to create a `CommandAPIBukkitConfig` object, you must give it a reference to your `JavaPlugin` instance. The CommandAPI always uses this to register events, so it is required when loading the CommandAPI on Bukkit. There are also Bukkit-specific features, such as the `hook-paper-reload` configuration option, which may be configured using a `CommandAPIBukkitConfig` instance.
+In order to create a `CommandAPIPaperConfig` or a `CommandAPISpigotConfig` object, you must give it a reference to your `JavaPlugin` instance. The CommandAPI always uses this to register events, so it is required when loading the CommandAPI on Bukkit. There are also platform-specific features, such as the `hook-paper-reload` configuration option on Paper, which may be configured using a `CommandAPIPaperConfig` instance.
 
 For example, to load the CommandAPI on Bukkit with all logging disabled, you can use the following:
 
@@ -112,23 +124,25 @@ Add the CommandAPI shade dependency:
 <dependencies>
     <dependency>
         <groupId>dev.jorel</groupId>
-        <artifactId>commandapi-bukkit-shade</artifactId>
+        <artifactId>commandapi-spigot-shade</artifactId>
         <version>11.0.0-SNAPSHOT</version>
     </dependency>
 </dependencies>
 ```
+
 </div>
 <div class="mojmap">
 
 ```xml
 <dependencies>
     <dependency>
         <groupId>dev.jorel</groupId>
-        <artifactId>commandapi-bukkit-shade-mojang-mapped</artifactId>
+        <artifactId>commandapi-paper-shade</artifactId>
         <version>11.0.0-SNAPSHOT</version>
     </dependency>
 </dependencies>
 ```
+
 </div>
 
 You can shade the CommandAPI easily by adding the `maven-shade-plugin` to your build sequence:
@@ -221,35 +235,39 @@ Next, we declare our dependencies:
 
 ```groovy
 dependencies {
-    implementation "dev.jorel:commandapi-bukkit-shade:11.0.0-SNAPSHOT"
+    implementation "dev.jorel:commandapi-spigot-shade:11.0.0-SNAPSHOT"
 }
 ```
+
 </div>
 <div class="mojmap">
 
 ```groovy
 dependencies {
-    implementation "dev.jorel:commandapi-bukkit-shade-mojang-mapped:11.0.0-SNAPSHOT"
+    implementation "dev.jorel:commandapi-paper-shade:11.0.0-SNAPSHOT"
 }
 ```
+
 </div>
 </div>
 <div class="kts">
 <div class="reobf">
 
 ```kotlin
 dependencies {
-    implementation("dev.jorel:commandapi-bukkit-shade:11.0.0-SNAPSHOT")
+    implementation("dev.jorel:commandapi-spigot-shade:11.0.0-SNAPSHOT")
 }
 ```
+
 </div>
 <div class="mojmap">
 
 ```kotlin
 dependencies {
-    implementation("dev.jorel:commandapi-bukkit-shade-mojang-mapped:11.0.0-SNAPSHOT")
+    implementation("dev.jorel:commandapi-paper-shade:11.0.0-SNAPSHOT")
 }
 ```
+
 </div>
 </div>
 
diff --git a/docs/en/kotlin-dsl/intro.md b/docs/en/kotlin-dsl/intro.md
@@ -15,21 +15,34 @@ This DSL provides many methods to easily add arguments to your command structure
 
 ## Installing the DSL
 
-To install the DSL, you need to add the `commandapi-bukkit-kotlin` dependency into your `pom.xml` or your `build.gradle`, making sure to specify the server flavor you are developing for:
+To install the DSL, you need to add the Kotlin DSL dependency into your build script, making sure to specify the server flavor you are developing for:
 
 ### Adding the dependency
 
 <div class="maven">
 
+:::tabs
+===Paper
 ```xml
 <dependencies>
     <dependency>
         <groupId>dev.jorel</groupId>
-        <artifactId>commandapi-bukkit-kotlin</artifactId>
+        <artifactId>commandapi-kotlin-paper</artifactId>
         <version>11.0.0-SNAPSHOT</version>
     </dependency>
 </dependencies>
 ```
+===Spigot
+```xml
+<dependencies>
+    <dependency>
+        <groupId>dev.jorel</groupId>
+        <artifactId>commandapi-kotlin-spigot</artifactId>
+        <version>11.0.0</version>
+    </dependency>
+</dependencies>
+```
+:::
 
 Next, you need to add Kotlin to your project. For this, you first need to add the dependency:
 
@@ -104,20 +117,38 @@ Next, you need to add the dependency:
 
 <div class="groovy">
 
+:::tabs
+===Paper
 ```groovy
 dependencies {
-    implementation "dev.jorel:commandapi-bukkit-kotlin:11.0.0-SNAPSHOT"
+    implementation "dev.jorel:commandapi-kotlin-paper:11.0.0"
 }
 ```
+===Spigot
+```groovy
+dependencies {
+    implementation "dev.jorel:commandapi-kotlin-spigot:11.0.0"
+}
+```
+:::
 
 </div>
 <div class="kts">
 
+:::tabs
+===Paper
+```kotlin
+dependencies {
+    implementation("dev.jorel:commandapi-kotlin-paper:11.0.0")
+}
+```
+===Spigot
 ```kotlin
 dependencies {
-    implementation("dev.jorel:commandapi-bukkit-kotlin:11.0.0-SNAPSHOT")
+    implementation("dev.jorel:commandapi-kotlin-spigot:11.0.0")
 }
 ```
+:::
 
 </div>
 
diff --git a/docs/en/upgrading-parts/10.1.2-to-11.0.0.md b/docs/en/upgrading-parts/10.1.2-to-11.0.0.md
@@ -0,0 +1,43 @@
+### CommandAPI restructure
+
+#### General module changes
+
+For 11.0.0, the `commandapi-bukkit-xxx` modules have mostly been removed in favour of new platform specific modules that have been made for Paper or Spigot respectively:
+
+- `commandapi-paper-xxx`
+- `commandapi-spigot-xxx`
+
+In order to update please replace your `commandapi-bukkit-xxx` dependency with either `commandapi-paper-xxx` or `commandapi-spigot-xxx`.
+
+:::danger **Developer's Note:**
+
+The fact that Paper is a fork of Spigot does not mean that the Spigot modules work on Paper. Paper has, especially in newer versions, made changes to internal systems the CommandAPI
+uses. There are no guarantees that the Spigot modules will work on Paper in any kind or form.
+
+Similarly, if you try to use the Paper modules on Spigot you will face registration issues and potential `NoClassDefFoundError`s, depending on the server version you use.
+There again is no guarantee for any kind of compatibility.
+
+:::
+
+Additionally, the Kotlin module artifact names have changed. Instead of following the pattern `commandapi-bukkit-xxx`, they have now been updated as follows:
+
+- `commandapi-core-kotlin`: was changed to `commandapi-kotlin-core`
+- `commandapi-bukkit-kotlin`: was changed to `commandapi-kotlin-bukkit`
+
+#### Code changes
+
+The `CommandAPIBukkitConfig` class has been converted into an abstract class and is no longer used to construct a config instance. Instead, use the new `CommandAPIPaperConfig` or
+`CommandAPISpigot` classes, depending on the module you use.
+
+Further changes have been made to arguments that work with components. The classes `AdventureChatArgument`, `AdventureChatComponentArgument` and `AdventureChatColorArgument` have been
+removed. Instead, the `ChatArgument`, `ChatComponentArgument` and `ChatColorArgument` have been implemented platform specific and return different types on Paper and Spigot.
+On Paper, Adventure components are used while Spigot uses BungeeCord components.
+
+More argument changes have been made:
+
+- The `FloatRangeArgument` has been renamed to `DoubleRangeArgument` and now returns a `DoubleRange` object
+- The `PlayerArgument` and `OfflinePlayerArgument` have been replaced by the `PlayerProfileArgument` which returns a `List&lt;PlayerProfile&gt;`. The `PlayerProfile` class changes depending on if you are on Paper or on Spigot. Use the `EntitySelectorArgument.OnePlayer` if you want a `Player` object.
+- The `AsyncOfflinePlayerArgument` has been replaced by the `AsyncPlayerProfileArgument`
+- The `ChatArgument`, `ChatComponentArgument` and `ChatColorArgument` do no longer have any `Adventure` prefixes and return different types depending on the platform.
+- The `ChatArgument` returns a `SignedMessage` object on Paper
+- The `BlockStateArgument` now returns a `BlockState` object instead of a `BlockData` object
diff --git a/docs/en/user-setup/config.md b/docs/en/user-setup/config.md

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@ export const upgradingInfos: UpgradingInfo[] = [`
`19`	`19`	`{from: '9.0.3', to: '9.1.0'},`
`20`	`20`	`{from: '9.2.0', to: '9.3.0'},`
`21`	`21`	`{from: '9.7.0', to: '10.0.0'},`
	`22`	`+ {from: '10.1.2', to: '11.0.0'}`
`22`	`23`	`]`
`23`	`24`
`24`	`25`	`export const keyVersions = Array.from(new Set(upgradingInfos.map(info => [info.from, info.to]).flat()));`