> 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/for-enchantmentreform/configs/info-of-abilities/blocks-world.md). # Block and World Abilities Every registered ability on this page is documented as a complete reference entry. All entries also support the common ability fields from the [Abilities](/for-enchantmentreform/configs/info-of-abilities.md) page. ## Registry keys on this page * `nearby_block` * `break_blocks` * `break_block` * `replace_block` * `change_block_face` * `grow_crop` * `scan_blocks` * `locate_structure` * `locate_biome` *** ## `nearby_block` **Purpose:** Runs child abilities for nearby blocks ordered by distance from a resolved center. **Context:** Requires a resolved world location and nested abilities. ### Fields | Field | Default | Description | | -------------------------------- | -------- | ----------------------------------------------- | | `radius` | `1` | Default radius on all axes, minimum 0. | | `radius-x / radius-y / radius-z` | `radius` | Per-axis radii. | | `max-blocks` | `0` | Maximum processed blocks; zero means unlimited. | | `abilities` | required | Children executed with each block as context. | ### Example ```yaml type: nearby_block radius-x: 3 radius-y: 1 radius-z: 3 max-blocks: 16 abilities: grow: type: grow_crop stages: 1 ``` ### Behavior and limits * Every block in the cuboid is visited nearest-first; this ability does not itself filter materials. * The result records how many blocks actually changed after child execution. *** ## `break_blocks` **Purpose:** Selects, filters, and breaks a bounded group of blocks in batches. **Context:** Requires a player `breaker`, an origin block/location, tool context, and protection permission. ### Fields | Field | Default | Description | | ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `breaker` | `SOURCE` | Player selector: `SOURCE`, `SKILL`, or `TARGET`. | | `center` | `EVENT_BLOCK` | Origin selector: `EVENT_BLOCK`, entity role, or resolved location. | | `shape` | `CUBE` | `CUBE`, `SPHERE`, `PLANE`, `LAYER`, `TUNNEL`/`LINE`, or `VEIN`. | | `radius` | shape-specific | General radius, capped at 16. | | `radius-x/y/z` | `radius` | Cube radii. | | `vertical-radius` | `0` | Layer vertical radius. | | `depth` | `0` | Plane depth. | | `length` | `3` | Tunnel length, capped at 32. | | `size` | unset | Odd cube-style size alias converted to radius. | | `max-blocks` | global limit | Local cap; vein default 64; always capped by global config. | | `include-origin` | `false` | Allow the origin block. | | `same-type` | `false` | Require origin material. | | `diagonal` | `true` | Use 26-neighbor vein search instead of six directions. | | `load-chunks` | `false` | Allow blocks in unloaded chunks. | | `whitelist / blacklist` | empty | Block specifications understood by `BlockPriceUtil`. | | `use-default-blacklist` | `true` | Exclude protected hard blocks/containers such as bedrock, barriers, portal frames, reinforced deepslate, spawners, and chests. | | `require-sneaking` | `false` | Require breaker sneaking. | | `disable-when-sneaking` | `false` | Skip while sneaking. | | `mode` | `NATURAL` | `NATURAL` uses `breakNaturally(tool)`; `PLAYER` uses `Player#breakBlock`. | | `blocks-per-tick` | `16` | Batch size, minimum 1. | | `before-abilities` | empty | Children before each break attempt. | | `abilities` | empty | Children after each successful break. | ### Example ```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 ``` ### Behavior and limits * Every candidate is checked against protection hooks; air and invalid blocks are skipped. * The global `powers.break-block.max-blocks-per-activation` cap defaults to 512. * Folia natural breaking is scheduled by block region; player mode uses an internal-break recursion marker. * The tool is cloned for each natural break. *** ## `break_block` **Purpose:** Breaks the current context block using natural or player break behavior. **Context:** Requires `BLOCK`, a player breaker, context item/tool, and protection permission. ### Fields | Field | Default | Description | | --------- | --------- | ------------------------------------------------ | | `breaker` | `SOURCE` | Player selector: `SOURCE`, `SKILL`, or `TARGET`. | | `mode` | `NATURAL` | Natural aliases or player-break aliases. | ### Example ```yaml type: break_block breaker: SOURCE mode: PLAYER ``` ### Behavior and limits * Natural mode calls `breakNaturally` with a cloned context item. * Player mode uses `Player#breakBlock` and an internal recursion marker. * Protection hooks are checked before breaking. *** ## `replace_block` **Purpose:** Replaces the current context block according to an ordered source-to-destination mapping. **Context:** Requires `BLOCK` and a non-empty `replacements` section. ### Fields | Field | Default | Description | | -------------- | -------- | ----------------------------------------------------------------------------------------------- | | `replacements` | required | Map whose keys are source block specifications and values are destination block specifications. | ### Example ```yaml type: replace_block replacements: WHEAT: AIR '#minecraft:logs': OAK_PLANKS ``` ### Behavior and limits * The first matching source specification is selected by `BlockPriceUtil`. * Invalid/non-string or blank mapping entries are ignored. *** ## `change_block_face` **Purpose:** Changes facing/rotation on directional or rotatable block data. **Context:** Requires `BLOCK`; protection-use permission is checked when a player is available. ### Fields | Field | Default | Description | | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------- | | `mode` | `FIXED` | `FIXED` uses `face`; `NEXT`, `CYCLE`, and `NEXT_AVAILABLE` rotate to the next supported face. | | `face` | `NORTH` | Configured Bukkit `BlockFace` for fixed mode. | | `apply-physics` | `false` | Whether setting block data applies physics. | | `abilities` | empty | Children after successful change. | | `failure-abilities / else-abilities` | empty | Children when no change can be applied. | ### Example ```yaml type: change_block_face mode: NEXT apply-physics: false abilities: sound: type: sound sound: BLOCK_LEVER_CLICK ``` ### Behavior and limits * Directional blocks only accept their supported faces; rotatable blocks use 16 horizontal rotations. * Successful changes increment the changed-block result counter. *** ## `grow_crop` **Purpose:** Advances an ageable context block toward maximum age. **Context:** Requires `BLOCK` whose data implements Bukkit `Ageable`. ### Fields | Field | Default | Description | | -------- | ------- | ------------------------------- | | `stages` | `1` | Growth stages added, minimum 1. | ### Example ```yaml type: grow_crop stages: 2 ``` ### Behavior and limits * Growth is clamped to the block's maximum age. * Non-ageable blocks are skipped. *** ## `scan_blocks` **Purpose:** Scans a cube around the context block or source player and optionally highlights matches. **Context:** Requires player `SOURCE`; center is `BLOCK` when present, otherwise the player's block. ### Fields | Field | Default | Description | | ------------- | ------- | ---------------------------------------------------------------------- | | `radius` | `5` | Cube radius, minimum 1. | | `same-type` | `false` | Match the center material instead of default ore/ancient-debris rules. | | `max-results` | `256` | Maximum highlighted matches, minimum 1. | | `highlight` | `true` | Spawn one `END_ROD` particle at each match. | ### Example ```yaml type: scan_blocks radius: 6 same-type: false max-results: 128 highlight: true ``` ### Behavior and limits * Default matching recognizes material names ending `_ORE` plus `ANCIENT_DEBRIS`. * The scan is a full cube, so cost grows with the third power of radius. *** ## `locate_structure` **Purpose:** Finds the nearest configured structure type and sends a formatted result message. **Context:** Requires player `SOURCE` and Paper registry access. ### Fields | Field | Default | Description | | ---------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- | | `structures` | empty | Structure type keys; unnamespaced values use `minecraft`. | | `radius` | `32` | Search radius passed to Bukkit, minimum 1. | | `find-unexplored` | `false` | Restrict search to unexplored structures. | | `found` | empty | Success message with `{distance}`, `{direction}`, `{x}`, `{y}`, `{z}`, `{structure}`, `{structure_key}`. | | `not-found` | empty | Failure message. | | `structure-names.` | registry key | Display-name mappings. | | `directions.north/south/east/west` | English key | Localized direction text. | ### Example ```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.' ``` ### Behavior and limits * Each configured structure is searched separately and the nearest result is selected. * World-generation searches can be expensive; use a cooldown. *** ## `locate_biome` **Purpose:** Finds the nearest configured biome and sends a formatted result message. **Context:** Requires player `SOURCE` and Paper registry access. ### Fields | Field | Default | Description | | --------------------- | ------------ | ---------------------------------------------------------------------- | | `biomes` | empty | Biome registry keys. | | `radius` | `1024` | Maximum search radius, minimum 1. | | `horizontal-interval` | `32` | Horizontal sampling interval, minimum 1. | | `vertical-interval` | `64` | Vertical sampling interval, minimum 1. | | `found` | empty | Success message with distance, direction, coordinates, biome name/key. | | `not-found` | empty | Failure message. | | `biome-names.` | registry key | Display-name mappings. | | `directions.*` | English key | Localized direction text. | ### Example ```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.' ``` ### Behavior and limits * Invalid or duplicate biome keys are ignored. * Large searches can be expensive; use a cooldown. ***