The Spell Field Component

To utilize the Spell Field API, you attach the root enchantment_core:spell_field effect component to your enchantment. This component acts as the master controller for the spatial evaluation pipeline.

Evaluation Pipeline

When the enchantment trigger condition is met (e.g., minecraft:post_attack), the SpellFieldComponent executes the following sequence:

1. Epicenter Calculation: The absolute center of the spell field is established. By default, this is the position of the target entity, offset vertically by half of its bounding box height.
2. Volume Aggregation: The component iterates through its defined volumes. For each volume, it calculates the global bounding box (AABB) and the active mathematical topology. If an explicit shape is omitted from the volume definition, the API will attempt to automatically fit the bounding box to the topology's maximum limits.
3. Target Scanning:
   • Entities: The server scans the world within the calculated bounding boxes for alive entities. For each entity found, the topology evaluates a scalar multiplier (0.0 to 1.0) based on the entity's exact position.
   • Blocks: If block effects are configured, the server iterates through every block coordinate within the bounding boxes, calculating a scalar for each block center.
4. Event Dispatching: The calculated scalars and targets are passed through the SpellFieldEventDispatcher, allowing external mods to intercept, modify, or cancel the targeting logic dynamically.
5. Effect Application:
   • Entity Effects: Executed for each valid entity. The effect strength is scaled by the entity's specific topological scalar.
   • Block Effects: Executed for each valid block. Block effects are sorted by priority (determined by their TopologyEvaluator thresholds) before execution. Block modifications are tracked to prevent overlapping effects from conflicting on the same block.
   • Volume Effects: Executed globally against the field geometry.
   • Visual Effects: Executed last, utilizing active vectors (axes) broadcasted by the previously executed effects (e.g., aligning particles to an impulse direction).

Configuration Schema

The root component accepts five optional lists:

{
  "type": "enchantment_core:spell_field",
  "volumes": [ ... ],
  "entity_effects": [ ... ],
  "block_effects": [ ... ],
  "volume_effects": [ ... ],
  "visual_effects": [ ... ]
}

• volumes (Required): Defines the geometric bounds of the field. While the list itself must be present, the internal properties of a volume (shape, offset, topology) are entirely optional.
• entity_effects: Logic applied to captured entities.
• block_effects: Logic applied to captured block coordinates.
• volume_effects: Logic executed globally (e.g., random explosions).
• visual_effects: Particle generation logic.

Spell Field Anchors (Lingering Fields)

Standard spell fields are transient—they evaluate instantly on the tick they are triggered. If you want to create a lingering AoE (like a poison cloud or a persistent healing aura), you use a Spell Field Anchor.

Instead of attaching enchantment_core:spell_field directly to your enchantment's effects list, you attach enchantment_core:summon_spell_field_anchor.

Anchor Mechanics

The Anchor is an invisible, non-tickable entity (SpellFieldAnchorEntity) summoned into the world. It holds a nested SpellFieldComponent inside its data payload.

The Anchor operates on a cyclic phase system:

• Life Time: Total ticks the anchor will exist before despawning.
• Activation Delay: Initial grace period before the anchor begins ticking its spell field.
• Active Phase & Rest Phase: Defines an oscillation cycle. The anchor will evaluate the spell field every tick_rate ticks during the Active Phase, then pause during the Rest Phase.

This allows you to create highly complex temporal behaviors, such as a field that pulses 3 times rapidly, goes dormant for 2 seconds, and then pulses again, applying its payload on each pulse.