Documentation/content/world/interactions/selectors.en.md

title, type, weight

title	type	weight
Selectors	docs	2

Selectors determine which entities or blocks are targeted by an interaction.

Package: com.hypixel.hytale.server.core.modules.interaction.interaction.config.selector

Selector Types

RaycastSelector

Casts a ray from the player's view to find targets:

Selector:
  Type: Raycast
  Range: 5.0
  BlockCollision: true
  EntityCollision: true

Properties:

• Range - Maximum distance
• BlockCollision - Stop at blocks
• EntityCollision - Detect entities

AOECircleSelector

Selects all targets in a circular area:

Selector:
  Type: AOECircle
  Radius: 3.0
  Height: 2.0

Properties:

• Radius - Circle radius
• Height - Vertical extent

AOECylinderSelector

Selects targets in a cylindrical area:

Selector:
  Type: AOECylinder
  Radius: 4.0
  Height: 3.0
  HeightOffset: 0.0

StabSelector

Close-range forward attack:

Selector:
  Type: Stab
  Range: 2.0
  Width: 1.5

HorizontalSelector

Horizontal sweep attack:

Selector:
  Type: Horizontal
  Range: 3.0
  Angle: 90.0

Selector Interface

The Selector interface provides methods for targeting:

import com.hypixel.hytale.component.CommandBuffer;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.function.consumer.TriIntConsumer;
import com.hypixel.hytale.math.vector.Vector4d;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import java.util.function.BiConsumer;
import java.util.function.Predicate;

public interface Selector {
    // Select target entities - consumer receives entity ref AND hit location
    void selectTargetEntities(
        CommandBuffer<EntityStore> buffer,
        Ref<EntityStore> attacker,
        BiConsumer<Ref<EntityStore>, Vector4d> consumer,
        Predicate<Ref<EntityStore>> filter
    );

    // Select target blocks
    void selectTargetBlocks(
        CommandBuffer<EntityStore> buffer,
        Ref<EntityStore> attacker,
        TriIntConsumer consumer
    );

    // Update selector state each tick
    void tick(
        CommandBuffer<EntityStore> buffer,
        Ref<EntityStore> entity,
        float startTime,
        float currentTime
    );
}

{{< callout type="info" >}} Note: The instance method selectTargetEntities() provides hit location via Vector4d, while the static selectNearbyEntities() only provides entity references. {{< /callout >}}

Entity Matchers

Filter which entities can be selected:

VulnerableMatcher

Only select entities that can take damage:

Matcher:
  Type: Vulnerable

PlayerMatcher

Only select players:

Matcher:
  Type: Player

Static Selection Utilities

The Selector interface provides static methods for common operations:

Select Nearby Blocks

Selector.selectNearbyBlocks(
    commandBuffer,
    attackerRef,
    range,
    (x, y, z) -> {
        // Process each block position
    }
);

// Or from a position
Selector.selectNearbyBlocks(
    position,
    range,
    (x, y, z) -> {
        // Process each block position
    }
);

Select Nearby Entities

import java.util.function.Consumer;
import java.util.function.Predicate;

Selector.selectNearbyEntities(
    commandBuffer,
    attackerRef,
    range,
    (Consumer<Ref<EntityStore>>) entityRef -> {
        // Process each entity
    },
    (Predicate<Ref<EntityStore>>) entityRef -> {
        // Filter predicate - return true to include
        return true;
    }
);

// Or from a position with ComponentAccessor
Selector.selectNearbyEntities(
    componentAccessor,
    position,
    range,
    entityRef -> {
        // Process each entity
    },
    entityRef -> true  // Filter or null
);

{{< callout type="info" >}} Note: The consumer receives Ref<EntityStore> only. For entity hit positions (like Vector4d), use selectTargetEntities() from a Selector instance instead. {{< /callout >}}

Practical Examples

Sword Slash

SwordSlash:
  Type: DamageCalculator
  Selector:
    Type: Horizontal
    Range: 2.5
    Angle: 120.0
  Matcher:
    Type: Vulnerable
  Damage:
    Base: 10.0
    Type: Physical

Healing Aura

HealingAura:
  Type: ChangeStatInteraction
  Selector:
    Type: AOECircle
    Radius: 5.0
    Height: 3.0
  Matcher:
    Type: Player
  Stat: Health
  Amount: 5.0

Mining

Mining:
  Type: BreakBlock
  Selector:
    Type: Raycast
    Range: 4.0
    BlockCollision: true
    EntityCollision: false

Best Practices

{{< callout type="info" >}} Selector Guidelines:

• Use appropriate range for the interaction type
• Apply filters to avoid unintended targets
• Consider performance with large AOE selectors
• Use raycast for precision attacks
• Always check entity.isValid() before accessing entity components {{< /callout >}}

{{< callout type="warning" >}} Entity Validity: Before interacting with an entity, verify it is still valid to prevent null pointer exceptions:

if (entityRef.isValid()) {
    // Safe to access entity components
    // ... perform operations
}

The server validates entity references internally, but custom code should always check validity with Ref.isValid(). {{< /callout >}}