Volumes & Topologies

The behavior and targeting scope of a Spell Field is defined by its volumes array. A SpellFieldVolume dictates the spatial boundaries (where the field exists) and the topology (how the field strength behaves inside those boundaries).

Spatial Vectors

Before understanding volumes, it is crucial to understand SpatialVector. A SpatialVector is a composite offset used to translate coordinates. It combines:

1. Absolute Cartesian Coordinates (x, y, z): Standard global world offsets.
2. Relative Orientational Coordinates (forward, up, right): Local offsets based on the caster's line of sight and rotation.

Example: Setting forward: 5.0 will shift the epicenter 5 blocks in whatever direction the caster is currently looking.

Shapes (Hard Boundaries)

A SpellFieldShape defines a strict, boolean bounding box (AABB). Targets inside the shape are processed; targets outside are ignored.

• cube: Uniform expansion in all axes.
• cuboid: Explicit and independent x, y, and z radii.
• deep_cuboid: Extends a box forward along the caster's line of sight (depth_radius) and outwards perpendicular to it (height_width_radius).
• wide_cuboid: Extends a box laterally based on the caster's horizontal facing.

Implicit Boundaries (Shape Omission)

Every property within a SpellFieldVolume (shape, offset, topology) is technically optional. If you omit an explicit shape but define a topology, the API will automatically calculate and generate a bounding box perfectly fitted to the outer limits of that topology (e.g., deriving bounds from the origin_range). If both shape and topology are omitted, the volume collapses into a single-point AABB.

⚠️ Performance Warning: Relying on implicitly generated bounding boxes from complex topologies can be more computationally expensive than defining a strict, simple shape (like a cube). While this auto-fitting allows for highly creative and dynamic enchantment implementations, it should be used with caution. Always use the in-game Debug Renderer to verify that your implicit bounding boxes aren't evaluating unnecessarily large areas of the world, which could lead to severe server lag during target scanning.

Topologies (Soft Boundaries & Falloffs)

While Shapes dictate where the field evaluates, Topologies dictate how strong the field is at a given point. Topologies return a scalar multiplier between 0.0 and 1.0.

A FieldTopology is defined by:

• Ranges: origin_range, axial_range, and radial_range define the maximum evaluation distances.
• Metric: The mathematical distance calculation.
  • euclidean: Standard straight-line spherical distance.
  • manhattan: Grid-based, diamond-shaped distance calculation.
• Axes: The axis parameter (a SpatialVector) establishes a directional orientation for the field, allowing you to create cylinders or cones of influence instead of just spheres.
• Scaling Functions: Dictate how the multiplier degrades as distance increases.

Distance Scaling Functions

Scaling functions calculate the drop-off from the center (1.0) to the defined range edge (0.0).

• constant: No drop-off. The multiplier is exactly 1.0 everywhere within range.
• linear: Smooth, straight-line degradation toward the edge.
• polynomial: Scaled by a degree curve (e.g., quadratic or cubic falloff).
• exponential: Rapid drop-off dictated by a decay_rate.
• logarithmic: Compressed curve mapped by a steepness factor.
• sigmoid: An S-curve that crosses the 50% power threshold at a defined midpoint_ratio.

By combining an axial_scaling function and a radial_scaling function on a specific axis, you can create highly complex shapes, such as a beam that maintains full strength along its length but decays exponentially at its edges.

Field Axes (Directional Vectors)

Certain effects (like impulses or particle vectors) need to know which direction to flow. The FieldAxis enumeration defines geometric vectors relative to the entity:

• Standard Axes: vertical (Up), longitudinal (Forward/Line of Sight), lateral (Right/Horizontal Plane).
• Relative Axes: radial (Flowing outward from the epicenter).
• Orbital Axes: azimuthal (Horizontal orbit), nutational (Pitching orbit), torsional (Rolling orbit).

Effects that implement DirectionalSpellFieldEffect will broadcast their chosen FieldAxis to the visual rendering engine, ensuring particles automatically flow in the correct direction.