feat: block-predicate-arguments page, and better tabs behavior

MC-XiaoHei · MC-XiaoHei · commit be8789f77008 · 2024-12-02T09:06:01.000+08:00
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -4,7 +4,7 @@ import {defineConfig, UserConfig} from 'vitepress';
 import {withI18n} from 'vitepress-i18n';
 import {VitePressI18nOptions} from 'vitepress-i18n/dist/types';
 import {VitePressSidebarOptions, withSidebar} from "vitepress-sidebar";
-import {tabsPlugin} from "./theme/tabs/codesMarkdownPlugin";
+import {tabsPlugin} from "./theme/tabs/markdownPlugin";
 import fs from "fs";
 import {exampleAutoAnchorPreprocessor} from "./theme/anchor/exampleAutoAnchorPreprocessor";
 
diff --git a/docs/.vitepress/theme/tabs/markdownPlugin.ts b/docs/.vitepress/theme/tabs/markdownPlugin.ts
@@ -10,22 +10,23 @@ type Params = {
     shareStateKey: string | undefined
 }
 
-const parseTabsParams = (): Params => {
-    return {
-        shareStateKey: "always"
-    }
-}
-
 export const tabsPlugin = (md: MarkdownIt) => {
     md.use(container, 'tabs', {
         render(tokens: Token[], index: number) {
+            let i = index + 1;
+            let tabsCnt = 0;
+            while(tokens[i].type !== 'container_tabs_close') {
+                if (tokens[i].type === 'tab_open') {
+                    tabsCnt++;
+                }
+                i++;
+                if (i >= tokens.length) {
+                    break;
+                }
+            }
             const token = tokens[index]
             if (token.nesting === 1) {
-                const params = parseTabsParams()
-                const shareStateKeyProp = params.shareStateKey
-                    ? `sharedStateKey="${md.utils.escapeHtml(params.shareStateKey)}"`
-                    : ''
-                return `<PluginTabs ${shareStateKeyProp}>\n`
+                return `<PluginTabs sharedStateKey="${tabsCnt}">\n`
             } else {
                 return `</PluginTabs>\n`
             }
diff --git a/docs/en/create-commands/arguments/types/predicate/block-predicate-arguments.md b/docs/en/create-commands/arguments/types/predicate/block-predicate-arguments.md
@@ -0,0 +1,52 @@
+---
+order: 1
+authors:
+  - misode
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# Block predicate arguments
+
+The `BlockPredicateArgument` is used to represent a "test" for Minecraft blocks. This can consist of tags, such as the ones listed [here on the MinecraftWiki](https://minecraft.wiki/w/Tag#Blocks), or individual blocks. If a block matches the tag or block, then the predicate is satisfied.
+
+For example, if we were to use the predicate `#leaves`, then the following blocks will be satisfied by that predicate: `jungle_leaves`, `oak_leaves`, `spruce_leaves`, `dark_oak_leaves`, `acacia_leaves`, `birch_leaves`.
+
+When used, this argument must be casted to a `Predicate<Block>`. As with other similar arguments with parameterized types, you can ignore Java's unchecked cast type safety warning.
+
+::::tip Example – Replacing specific blocks in a radius
+
+Say you want to replace blocks in a given radius. To do this, we'll use the following command structure:
+
+```mccmd
+/replace <radius> <fromBlock> <toBlock>
+```
+
+Of course, we could simply use a `BlockStateArgument` or even an `ItemStackArgument` as our `<fromBlock>` in order to get the material to replace, but the block predicate argument provides a test for a given block, which if satisfied, allows certain code to be executed.
+
+First, we declare our arguments. We want to use the `BlockPredicateArgument` since it also allows us to use Minecraft tags to identify blocks, as well as individual blocks. We then use `BlockStateArgument` to set the block to a given type. The `BlockStateArgument` also allows the user to provide any block data (e.g. contents of a chest or a stair's orientation).
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/predicate/BlockPredicateArguments.java#useBlockStateArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/predicate/BlockPredicateArguments.kt#useBlockStateArgumentsExample
+:::
+
+We then register our `/replace` command. First, we parse the arguments making sure to cast to `Predicate<Block>` and `BlockData` (and not `BlockState`). After that, we use a few simple for loops to find the blocks within a radius sphere from the player.
+
+In our most nested loop, we can then check if the block meets the requirements of our predicate. This is simply performed using `predicate.test(block)`, and if satisfied, we can set the block's type.
+
+Lastly, we register our command as normal using the `register()` method.
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/predicate/BlockPredicateArguments.java#blockPredicateArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/predicate/BlockPredicateArguments.kt#blockPredicateArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/predicate/BlockPredicateArguments.kt#blockPredicateArgumentsExampleDSL
+:::
+
+::::
diff --git a/docs/en/create-commands/arguments/types/predicate/index.md b/docs/en/create-commands/arguments/types/predicate/index.md
@@ -0,0 +1,4 @@
+---
+order: 10
+title: Predicate arguments
+---
diff --git a/reference-code/src/main/java/createcommands/arguments/types/predicate/BlockPredicateArguments.java b/reference-code/src/main/java/createcommands/arguments/types/predicate/BlockPredicateArguments.java
@@ -0,0 +1,55 @@
+package createcommands.arguments.types.predicate;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.Argument;
+import dev.jorel.commandapi.arguments.BlockPredicateArgument;
+import dev.jorel.commandapi.arguments.BlockStateArgument;
+import dev.jorel.commandapi.arguments.IntegerArgument;
+import org.bukkit.Location;
+import org.bukkit.block.Block;
+import org.bukkit.block.data.BlockData;
+
+import java.util.function.Predicate;
+
+class BlockPredicateArguments {
+    {
+        // #region useBlockStateArgumentsExample
+        Argument<?>[] arguments = new Argument<?>[] {
+            new IntegerArgument("radius"),
+            new BlockPredicateArgument("fromBlock"),
+            new BlockStateArgument("toBlock"),
+        };
+        // #endregion useBlockStateArgumentsExample
+
+        // #region blockPredicateArgumentsExample
+        new CommandAPICommand("replace")
+            .withArguments(arguments)
+            .executesPlayer((player, args) -> {
+                // Parse the arguments
+                int radius = (int) args.get("radius");
+                @SuppressWarnings("unchecked")
+                Predicate<Block> predicate = (Predicate<Block>) args.get("fromBlock");
+                BlockData blockData = (BlockData) args.get("toBlock");
+
+                // Find a (solid) sphere of blocks around the player with a given radius
+                Location center = player.getLocation();
+                for (int x = -radius; x <= radius; x++) {
+                    for (int y = -radius; y <= radius; y++) {
+                        for (int z = -radius; z <= radius; z++) {
+                            if (Math.sqrt(((x * x) + (y * y) + (z * z))) <= radius) {
+                                Block block = center.getWorld().getBlockAt(x + center.getBlockX(), y + center.getBlockY(), z + center.getBlockZ());
+
+                                // If that block matches a block from the predicate, set it
+                                if (predicate.test(block)) {
+                                    block.setType(blockData.getMaterial());
+                                    block.setBlockData(blockData);
+                                }
+                            }
+                        }
+                    }
+                }
+            })
+            .register();
+        // #endregion blockPredicateArgumentsExample
+    }
+}
diff --git a/reference-code/src/main/kotlin/createcommands/arguments/types/predicate/BlockPredicateArguments.kt b/reference-code/src/main/kotlin/createcommands/arguments/types/predicate/BlockPredicateArguments.kt
@@ -0,0 +1,92 @@
+package createcommands.arguments.types.predicate
+
+import dev.jorel.commandapi.CommandAPICommand
+import dev.jorel.commandapi.arguments.Argument
+import dev.jorel.commandapi.arguments.BlockPredicateArgument
+import dev.jorel.commandapi.arguments.BlockStateArgument
+import dev.jorel.commandapi.arguments.IntegerArgument
+import dev.jorel.commandapi.executors.PlayerCommandExecutor
+import dev.jorel.commandapi.kotlindsl.arguments
+import dev.jorel.commandapi.kotlindsl.commandAPICommand
+import dev.jorel.commandapi.kotlindsl.playerExecutor
+import org.bukkit.block.Block
+import org.bukkit.block.data.BlockData
+import java.util.function.Predicate
+import kotlin.math.sqrt
+
+fun blockPredicateArguments() {
+    // #region useBlockStateArgumentsExample
+    val arguments = arrayOf<Argument<*>>(
+        IntegerArgument("radius"),
+        BlockPredicateArgument("fromBlock"),
+        BlockStateArgument("toBlock"),
+    )
+    // #endregion useBlockStateArgumentsExample
+
+    // #region blockPredicateArgumentsExample
+    CommandAPICommand("replace")
+        .withArguments(*arguments)
+        .executesPlayer(PlayerCommandExecutor { player, args ->
+            // Parse the arguments
+            val radius = args["radius"] as Int
+            val predicate = args["fromBlock"] as Predicate<Block>
+            val blockData = args["toBlock"] as BlockData
+
+            // Find a (solid) sphere of blocks around the player with a given radius
+            val center = player.location // for (i in 1 until 11) { }
+            for (x in -radius until radius + 1) {
+                for (y in -radius until radius + 1) {
+                    for (z in -radius until radius + 1) {
+                        if (sqrt((x * x + y * y + z * z).toDouble()) <= radius) {
+                            val block = center.world.getBlockAt(x + center.blockX, y + center.blockY, z + center.blockZ)
+
+                            // If that block matches a block from the predicate, set it
+                            if (predicate.test(block)) {
+                                block.type = blockData.material
+                                block.blockData = blockData
+                            }
+                        }
+                    }
+                }
+            }
+        })
+        .register()
+    // #endregion blockPredicateArgumentsExample
+}
+
+fun blockPredicateArgumentsDSL() {
+    val arguments = arrayOf<Argument<*>>(
+        IntegerArgument("radius"),
+        BlockPredicateArgument("fromBlock"),
+        BlockStateArgument("toBlock"),
+    )
+    // #region blockPredicateArgumentsExampleDSL
+    commandAPICommand("replace") {
+        arguments(*arguments)
+        playerExecutor { player, args ->
+            // Parse the arguments
+            val radius = args["radius"] as Int
+            val predicate = args["fromBlock"] as Predicate<Block>
+            val blockData = args["toBlock"] as BlockData
+
+            // Find a (solid) sphere of blocks around the player with a given radius
+            val center = player.location // for (i in 1 until 11) { }
+            for (x in -radius until radius + 1) {
+                for (y in -radius until radius + 1) {
+                    for (z in -radius until radius + 1) {
+                        if (Math.sqrt((x * x + y * y + z * z).toDouble()) <= radius) {
+                            val block = center.world.getBlockAt(x + center.blockX, y + center.blockY, z + center.blockZ)
+
+                            // If that block matches a block from the predicate, set it
+                            if (predicate.test(block)) {
+                                block.type = blockData.material
+                                block.blockData = blockData
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // #endregion blockPredicateArgumentsExampleDSL
+}

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +order: 10
 +title: Predicate arguments
 +---