Volume Effects

Unlike Entity or Block effects (which execute against specific targets found in the world), Volume Effects (SpellFieldVolumeEffect) execute globally against the entire abstract geometry of the spell field.

These effects are typically evaluated a specific number of times per execution cycle, sampling random coordinates from within the defined volumes.

Probability Distributions

To determine where a volume effect occurs, the API uses a ProbabilityDistribution.

The distribution logic samples random coordinates within the bounding boxes. By default, this is a uniform distribution (any point in the box is equally likely).

However, if the volume has a FieldTopology defined, the distribution logic will perform multiple sampling_attempts. It will calculate the topological multiplier for the random point and use it as a probability weight. This causes volume effects (like random lightning strikes) to naturally cluster near the epicenter where the field is strongest, while occasionally striking near the edges.

Available Effects

• explode: Computes and spawns physical explosion payloads within the volume.
  • explosion: An ExplosionDefinition object detailing radius, block interactions, and entity damage rules.
  • count: The total number of separate explosions to generate per execution.
  • fuse_ticks & fuse_variance: Delays the explosion payload, allowing for cascading or delayed detonations.
  • spatial_delay: Adds additional delay ticks explicitly based on the target coordinate's distance from the epicenter. (Useful for explosions that ripple outward from the center).
• lightning_strike: Spawns lightning bolts at sampled locations.
  • visual_only: If true, the lightning bolt renders and plays sound, but does not start fires or deal entity damage.
• surface_hazard: Spawns an entity specifically tracking the highest solid block surface near the sampled coordinate (e.g., Evoker Fangs snapping from the ground).
  • vertical_search: Determines how far up and down the Y-axis the engine will scan to find a valid ground plane before giving up.
• play_sound_volume: Triggers a global audio event explicitly at the volume epicenter, regardless of where targets are located.