Init

content/world/interactions/selectors.en.md

@@ -0,0 +1,270 @@
+---
+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 >}}