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

---
title: Selectors
type: docs
weight: 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:

```yaml
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:

```yaml
Selector:
  Type: AOECircle
  Radius: 3.0
  Height: 2.0
```

Properties:
- `Radius` - Circle radius
- `Height` - Vertical extent

### AOECylinderSelector

Selects targets in a cylindrical area:

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

### StabSelector

Close-range forward attack:

```yaml
Selector:
  Type: Stab
  Range: 2.0
  Width: 1.5
```

### HorizontalSelector

Horizontal sweep attack:

```yaml
Selector:
  Type: Horizontal
  Range: 3.0
  Angle: 90.0
```

## Selector Interface

The `Selector` interface provides methods for targeting:

```java
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:

```yaml
Matcher:
  Type: Vulnerable
```

### PlayerMatcher

Only select players:

```yaml
Matcher:
  Type: Player
```

## Static Selection Utilities

The `Selector` interface provides static methods for common operations:

### Select Nearby Blocks

```java
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

```java
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

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

### Healing Aura

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

### Mining

```yaml
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:
```java
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 >}}