Block Effects

Block effects (SpellFieldBlockEffect) evaluate specific logic against every physical coordinate within the field's geometric bounding box.

Because iterating over thousands of blocks can be performance-intensive, block effects utilize a strict TopologyEvaluator system for priority and probabilistic culling.

The Topology Evaluator

Almost all block effects require a TopologyEvaluator. This object defines a threshold (a LevelBasedValue).

The evaluator serves two purposes:

1. Priority Sorting: Before execution, all block effects are sorted descending by their calculated threshold. This ensures that a break_block effect (e.g., threshold 0.8) executes before a place_block effect (e.g., threshold 0.5) on the same coordinate.
2. Execution Probability: The threshold dictates the minimum required Volume Scalar for the effect to execute on that specific block.
   • If the block's scalar >= threshold, the effect executes.
   • If threshold is omitted entirely, the effect behaves probabilistically: the block's scalar becomes its percentage chance to execute (e.g., a scalar of 0.3 means a 30% chance to execute).

Note: The SpellFieldComponent tracks block modifications. If an effect successfully alters a block coordinate, that coordinate is marked as "modified," and subsequent block effects with lower priorities will ignore it for the remainder of the evaluation cycle.

Block Blacklist

By default, the global SpellFieldBlockBlacklist configuration prevents block effects from targeting unbreakable or critical blocks (e.g., Bedrock, End Portals, Command Blocks).

Destruction & Creation

• break_block: Destroys the block at the target coordinate.
  • drop_resources: Boolean dictating whether the block drops its item entity equivalent.
• ignite_block: Attempts to spawn a fire block at the target coordinate, provided the block below supports it.
• place_block: Permanently places a new block state.
  • block: The registry identifier of the block to place.
  • require_air: If true, the placement fails if the target coordinate is not replaceable (e.g., air or tall grass).

Transmutation & Temporary States

• transmute_block: Permanently converts specific existing blocks into a new block state.
  • target_blocks: Optional block tag or list of allowed blocks. If provided, the transmutation only occurs if the existing block matches this list.
  • replacement_block: The target state.
• temporary_transmute_block: Same as transmutation, but the block reverts to its original state after a set duration.
  • lifetime: Ticks the transmuted block remains stable.
  • decay_duration: Ticks over which the block reverts.
• place_temporary_block: Places a block that degrades back to air (or its prior state).
  • restore_previous: If true, restores the exact block state (and NBT data) that existed before placement, rather than decaying into air.

Audio & Visual

• play_sound_block: Triggers a spatial audio event exactly at the block's coordinate.
• burst_block: Spawns a cluster of particles centered within the block space.