> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/cn-er/pei-zhi/info-of-abilities/blocks-world.md). # 方块与世界能力 本页面会将每一种已注册能力作为完整条目进行说明。所有条目也支持[能力](/cn-er/pei-zhi/info-of-abilities.md)页面中介绍的通用能力字段。 ## 本页面的注册键 * `nearby_block` * `break_blocks` * `break_block` * `replace_block` * `change_block_face` * `grow_crop` * `scan_blocks` * `locate_structure` * `locate_biome` *** ## `nearby_block` \*\*用途：\*\*按照与解析中心的距离顺序，为附近方块执行子能力。 \*\*上下文：\*\*需要能够解析出的世界位置和嵌套能力。 ### 字段 | 字段 | 默认值 | 说明 | | -------------------------------- | -------- | ---------------------- | | `radius` | `1` | 三个坐标轴共同使用的默认半径，最小值为 0。 | | `radius-x / radius-y / radius-z` | `radius` | 各坐标轴分别使用的半径。 | | `max-blocks` | `0` | 最多处理的方块数量；零表示无限制。 | | `abilities` | 必填 | 以每个方块作为上下文执行的子能力。 | ### 示例 ```yaml type: nearby_block radius-x: 3 radius-y: 1 radius-z: 3 max-blocks: 16 abilities: grow: type: grow_crop stages: 1 ``` ### 行为与限制 * 会按照由近到远的顺序访问长方体范围内的每个方块；此能力本身不会筛选材质。 * 结果会记录执行子能力后实际发生变化的方块数量。 *** ## `break_blocks` \*\*用途：\*\*选择并筛选一组有数量限制的方块，然后分批将其破坏。 \*\*上下文：\*\*需要作为 `breaker` 的玩家、起点方块或位置、工具上下文，以及保护插件许可。 ### 字段 | 字段 | 默认值 | 说明 | | ----------------------- | ------------- | -------------------------------------------------------------------- | | `breaker` | `SOURCE` | 玩家选择器，可填写 `SOURCE`、`SKILL` 或 `TARGET`。 | | `center` | `EVENT_BLOCK` | 起点选择器，可填写 `EVENT_BLOCK`、实体角色或解析出的位置。 | | `shape` | `CUBE` | 可填写 `CUBE`、`SPHERE`、`PLANE`、`LAYER`、`TUNNEL`/`LINE` 或 `VEIN`。 | | `radius` | 由形状决定 | 通用半径，最大限制为 16。 | | `radius-x/y/z` | `radius` | 立方体各坐标轴的半径。 | | `vertical-radius` | `0` | `LAYER` 的垂直半径。 | | `depth` | `0` | `PLANE` 的深度。 | | `length` | `3` | `TUNNEL` 的长度，最大限制为 32。 | | `size` | 未设置 | 仅接受奇数的立方体尺寸别名，内部会转换为半径。 | | `max-blocks` | 全局限制 | 当前能力的数量上限；`VEIN` 默认为 64，并始终受全局配置限制。 | | `include-origin` | `false` | 是否允许包含起点方块。 | | `same-type` | `false` | 是否要求候选方块与起点材质相同。 | | `diagonal` | `true` | 连锁搜索时是否使用 26 个相邻方向，而不是只使用六个正方向。 | | `load-chunks` | `false` | 是否允许处理尚未加载区块中的方块。 | | `whitelist / blacklist` | 空 | 由 `BlockPriceUtil` 解析的方块规格。 | | `use-default-blacklist` | `true` | 是否排除受保护的坚硬方块或容器，例如基岩、屏障、传送门框架、强化深板岩、刷怪笼和箱子。 | | `require-sneaking` | `false` | 是否要求破坏者正在潜行。 | | `disable-when-sneaking` | `false` | 破坏者潜行时是否跳过执行。 | | `mode` | `NATURAL` | `NATURAL` 使用 `breakNaturally(tool)`；`PLAYER` 使用 `Player#breakBlock`。 | | `blocks-per-tick` | `16` | 每个 Tick 处理的批次数量，最小值为 1。 | | `before-abilities` | 空 | 每次尝试破坏方块前执行的子能力。 | | `abilities` | 空 | 每次成功破坏方块后执行的子能力。 | ### 示例 ```yaml type: break_blocks breaker: SOURCE center: EVENT_BLOCK shape: VEIN same-type: true diagonal: true include-origin: false max-blocks: 32 blocks-per-tick: 8 whitelist: - DIAMOND_ORE - DEEPSLATE_DIAMOND_ORE abilities: particles: type: particle particle: END_ROD ``` ### 行为与限制 * 每个候选方块都会经过保护插件挂钩检查；空气和无效方块会被跳过。 * 全局配置 `powers.break-block.max-blocks-per-activation` 的默认上限为 512。 * 在 Folia 上，自然破坏会按照方块所在区域调度；玩家模式使用内部破坏递归标记。 * 每次自然破坏都会克隆工具。 *** ## `break_block` \*\*用途：\*\*使用自然破坏或玩家破坏行为，破坏当前上下文方块。 \*\*上下文：\*\*需要 `BLOCK`、作为破坏者的玩家、上下文物品或工具，以及保护插件许可。 ### 字段 | 字段 | 默认值 | 说明 | | --------- | --------- | -------------------------------------- | | `breaker` | `SOURCE` | 玩家选择器，可填写 `SOURCE`、`SKILL` 或 `TARGET`。 | | `mode` | `NATURAL` | 自然破坏别名或玩家破坏别名。 | ### 示例 ```yaml type: break_block breaker: SOURCE mode: PLAYER ``` ### 行为与限制 * 自然模式会使用克隆后的上下文物品调用 `breakNaturally`。 * 玩家模式使用 `Player#breakBlock` 和内部递归标记。 * 破坏前会检查保护插件挂钩。 *** ## `replace_block` \*\*用途：\*\*根据按顺序检查的“来源方块到目标方块”映射，替换当前上下文方块。 \*\*上下文：\*\*需要 `BLOCK` 和非空的 `replacements` 部分。 ### 字段 | 字段 | 默认值 | 说明 | | -------------- | --- | --------------------- | | `replacements` | 必填 | 映射的键为来源方块规格，值为目标方块规格。 | ### 示例 ```yaml type: replace_block replacements: WHEAT: AIR '#minecraft:logs': OAK_PLANKS ``` ### 行为与限制 * 使用 `BlockPriceUtil` 选择第一个匹配的来源规格。 * 无效、不是字符串或内容为空的映射条目会被忽略。 *** ## `change_block_face` \*\*用途：\*\*修改方向型或可旋转方块数据的朝向或旋转角度。 \*\*上下文：\*\*需要 `BLOCK`；存在玩家时会检查保护插件的使用许可。 ### 字段 | 字段 | 默认值 | 说明 | | ------------------------------------ | ------- | ------------------------------------------------------------------ | | `mode` | `FIXED` | `FIXED` 使用 `face`；`NEXT`、`CYCLE` 和 `NEXT_AVAILABLE` 会旋转到下一个受支持的方向。 | | `face` | `NORTH` | 固定模式使用的 Bukkit `BlockFace`。 | | `apply-physics` | `false` | 设置方块数据时是否应用物理更新。 | | `abilities` | 空 | 成功修改后执行的子能力。 | | `failure-abilities / else-abilities` | 空 | 无法应用修改时执行的子能力。 | ### 示例 ```yaml type: change_block_face mode: NEXT apply-physics: false abilities: sound: type: sound sound: BLOCK_LEVER_CLICK ``` ### 行为与限制 * 方向型方块只接受其支持的朝向；可旋转方块使用 16 个水平方向旋转值。 * 成功修改会增加已更改方块结果计数器。 *** ## `grow_crop` \*\*用途：\*\*让实现了年龄数据的上下文方块向最大生长阶段推进。 \*\*上下文：\*\*需要 `BLOCK`，且其方块数据必须实现 Bukkit `Ageable`。 ### 字段 | 字段 | 默认值 | 说明 | | -------- | --- | ----------------- | | `stages` | `1` | 增加的生长阶段数量，最小值为 1。 | ### 示例 ```yaml type: grow_crop stages: 2 ``` ### 行为与限制 * 生长阶段不会超过该方块的最大年龄。 * 不支持年龄数据的方块会被跳过。 *** ## `scan_blocks` \*\*用途：\*\*扫描上下文方块或来源玩家周围的立方体，并可选择高亮匹配方块。 \*\*上下文：\*\*需要作为 `SOURCE` 的玩家；存在 `BLOCK` 时以该方块为中心，否则以玩家所在方块为中心。 ### 字段 | 字段 | 默认值 | 说明 | | ------------- | ------- | ----------------------------- | | `radius` | `5` | 立方体半径，最小值为 1。 | | `same-type` | `false` | 是否匹配中心方块材质，而不是使用默认的矿石和远古残骸规则。 | | `max-results` | `256` | 最多高亮的匹配数量，最小值为 1。 | | `highlight` | `true` | 是否在每个匹配方块处生成一个 `END_ROD` 粒子。 | ### 示例 ```yaml type: scan_blocks radius: 6 same-type: false max-results: 128 highlight: true ``` ### 行为与限制 * 默认匹配材质名称以 `_ORE` 结尾的方块，以及 `ANCIENT_DEBRIS`。 * 扫描范围是完整立方体，因此计算成本会随半径的三次方增长。 *** ## `locate_structure` \*\*用途：\*\*寻找距离最近的已配置结构类型，并发送格式化结果消息。 \*\*上下文：\*\*需要作为 `SOURCE` 的玩家和 Paper 注册表访问能力。 ### 字段 | 字段 | 默认值 | 说明 | | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------- | | `structures` | 空 | 结构类型键；未填写命名空间的值会使用 `minecraft`。 | | `radius` | `32` | 传递给 Bukkit 的搜索半径，最小值为 1。 | | `find-unexplored` | `false` | 是否只搜索尚未探索的结构。 | | `found` | 空 | 成功消息，可使用 `{distance}`、`{direction}`、`{x}`、`{y}`、`{z}`、`{structure}` 和 `{structure_key}`。 | | `not-found` | 空 | 搜索失败时的消息。 | | `structure-names.` | 注册表键 | 结构显示名称映射。 | | `directions.north/south/east/west` | 英文键名 | 本地化方向文本。 | ### 示例 ```yaml type: locate_structure structures: - minecraft:village - minecraft:ancient_city radius: 100 find-unexplored: false found: '{structure} is {distance} blocks {direction} at {x}, {z}.' not-found: 'No structure found.' ``` ### 行为与限制 * 会分别搜索每一种配置的结构，并选择距离最近的结果。 * 世界生成搜索可能消耗较多性能，建议配置冷却时间。 *** ## `locate_biome` \*\*用途：\*\*寻找距离最近的已配置生物群系，并发送格式化结果消息。 \*\*上下文：\*\*需要作为 `SOURCE` 的玩家和 Paper 注册表访问能力。 ### 字段 | 字段 | 默认值 | 说明 | | --------------------- | ------ | -------------------------- | | `biomes` | 空 | 生物群系注册表键。 | | `radius` | `1024` | 最大搜索半径，最小值为 1。 | | `horizontal-interval` | `32` | 水平采样间隔，最小值为 1。 | | `vertical-interval` | `64` | 垂直采样间隔，最小值为 1。 | | `found` | 空 | 成功消息，可使用距离、方向、坐标、生物群系名称和键。 | | `not-found` | 空 | 搜索失败时的消息。 | | `biome-names.` | 注册表键 | 生物群系显示名称映射。 | | `directions.*` | 英文键名 | 本地化方向文本。 | ### 示例 ```yaml type: locate_biome biomes: - minecraft:cherry_grove radius: 1024 horizontal-interval: 32 vertical-interval: 64 found: '{biome} is {distance} blocks {direction}.' not-found: 'No biome found.' ``` ### 行为与限制 * 无效或重复的生物群系键会被忽略。 * 大范围搜索可能消耗较多性能，建议配置冷却时间。 ***