Add documentation for CommandAPI/CommandAPI#478

Author: willkroboth

docs/.vitepress/theme/upgrading/upgrading.ts

@@ -18,6 +18,7 @@ export const upgradingInfos: UpgradingInfo[] = [
     {from: '9.0.1', to: '9.0.2'},
     {from: '9.0.3', to: '9.1.0'},
     {from: '9.2.0', to: '9.3.0'},
+    {from: `9.7.0`, to: '10.0.0'},
 ]
 
 export const keyVersions = Array.from(new Set(upgradingInfos.map(info => [info.from, info.to]).flat()));

docs/en/create-commands/executors/native-sender.md

@@ -67,4 +67,23 @@ This can now be used via the following command examples:
 /execute in minecraft:overworld positioned 20 60 -20 run break
 ```
 
-::::
+::::
+
+## Constructing a `NativeProxyCommandSender`
+
+You can create a `NativeProxyCommandSender` object yourself using the static `from` method:
+
+```java
+NativeProxyCommandSender from(CommandSender caller, CommandSender callee, Location location, World world);
+```
+
+This `CommandSender` will work the same as any other `NativeProxyCommandSender` you would get while using `executesNative`. For example, you could use it to make a simple version of `/execute`, like so:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/executors/NativeSender.java#constructorExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/NativeSender.kt#constructorExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/executors/NativeSender.kt#constructorExampleDSL
+:::

docs/en/upgrading-parts/9.7.0-to-10.0.0.md

@@ -0,0 +1,15 @@
+`NativeProxyCommandSender` used to be a class, but this version changed it to an interface. Any code compiled against an earlier version that references any method of `NativeProxyCommandSender` may throw the following `IncompatibleClassChangeError` when run using the new version of the API:
+
+```
+java.lang.IncompatibleClassChangeError: Found interface dev.jorel.commandapi.wrappers.NativeProxyCommandSender, but class was expected
+```
+
+If this happens, the original code simply needs to be recompiled using the new API version.
+
+Additionally, the constructor of `NativeProxyCommandSender` is no longer available. Instead, the static `from` method should be used:
+
+```java
+new NativeProxyCommandSender(caller, callee, location, world); // [!code --]
+
+NativeProxyCommandSender.from(caller, callee, location, world); // [!code ++]
+```

reference-code/src/main/java/createcommands/executors/NativeSender.java

@@ -1,7 +1,15 @@
 package createcommands.executors;
 
 import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.CommandArgument;
+import dev.jorel.commandapi.arguments.EntitySelectorArgument;
+import dev.jorel.commandapi.arguments.LocationArgument;
+import dev.jorel.commandapi.arguments.WorldArgument;
+import dev.jorel.commandapi.wrappers.CommandResult;
+import dev.jorel.commandapi.wrappers.NativeProxyCommandSender;
 import org.bukkit.Location;
+import org.bukkit.World;
+import org.bukkit.command.CommandSender;
 
 class NativeSender {
     static {
@@ -15,5 +23,26 @@ class NativeSender {
             })
             .register();
         // #endregion breakCommandExample
+
+        // #region constructorExample
+        new CommandAPICommand("executeAs")
+            .withArguments(
+                new EntitySelectorArgument.OneEntity("target"),
+                new LocationArgument("location"),
+                new WorldArgument("world"),
+                new CommandArgument("command")
+            )
+            .executes((caller, args) -> {
+                CommandSender callee = args.getUnchecked("target");
+                Location location = args.getUnchecked("location");
+                World world = args.getUnchecked("world");
+                CommandResult command = args.getUnchecked("command");
+
+                assert callee != null && location != null && world != null && command != null;
+
+                command.execute(NativeProxyCommandSender.from(caller, callee, location, world));
+            })
+            .register();
+        // #endregion constructorExample
     }
 }

reference-code/src/main/kotlin/createcommands/executors/NativeSender.kt

@@ -1,9 +1,18 @@
 package createcommands.executors
 
 import dev.jorel.commandapi.CommandAPICommand
+import dev.jorel.commandapi.arguments.CommandArgument
+import dev.jorel.commandapi.arguments.EntitySelectorArgument
+import dev.jorel.commandapi.arguments.LocationArgument
+import dev.jorel.commandapi.arguments.WorldArgument
+import dev.jorel.commandapi.executors.CommandExecutor
 import dev.jorel.commandapi.executors.NativeCommandExecutor
-import dev.jorel.commandapi.kotlindsl.commandAPICommand
-import dev.jorel.commandapi.kotlindsl.nativeExecutor
+import dev.jorel.commandapi.kotlindsl.*
+import dev.jorel.commandapi.wrappers.CommandResult
+import dev.jorel.commandapi.wrappers.NativeProxyCommandSender
+import org.bukkit.Location
+import org.bukkit.World
+import org.bukkit.command.CommandSender
 
 fun nativeSender() {
     // #region breakCommandExample
@@ -14,6 +23,25 @@ fun nativeSender() {
         })
         .register()
     // #endregion breakCommandExample
+
+    // #region constructorExample
+    CommandAPICommand("executeAs")
+        .withArguments(
+            EntitySelectorArgument.OneEntity("target"),
+            LocationArgument("location"),
+            WorldArgument("world"),
+            CommandArgument("command")
+        )
+        .executes(CommandExecutor { caller, args ->
+            val callee = args["target"] as CommandSender
+            val location = args["location"] as Location
+            val world = args["world"] as World
+            val command = args["command"] as CommandResult
+
+            command.execute(NativeProxyCommandSender.from(caller, callee, location, world))
+        })
+        .register()
+    // #endregion constructorExample
 }
 
 fun nativeSenderDSL() {
@@ -25,4 +53,21 @@ fun nativeSenderDSL() {
         }
     }
     // #endregion breakCommandExampleDSL
+
+    // #region constructorExampleDSL
+    commandAPICommand("executeAs") {
+        entitySelectorArgumentOneEntity("target")
+        locationArgument("location")
+        worldArgument("world")
+        commandArgument("command")
+        anyExecutor { caller, args ->
+            val callee = args["target"] as CommandSender
+            val location = args["location"] as Location
+            val world = args["world"] as World
+            val command = args["command"] as CommandResult
+
+            command.execute(NativeProxyCommandSender.from(caller, callee, location, world))
+        }
+    }
+    // #endregion constructorExampleDSL
 }