---
title: Interaction System
type: docs
weight: 8
---

The Interaction system is Hytale's powerful data-driven behavior framework. It defines how items, blocks, and entities behave when used or activated.

## Overview

Interactions are primarily configured through asset files rather than Java code. They form chains of operations that execute when a player performs actions like clicking, attacking, or using items.

{{< cards cols="2" >}}
  {{< card link="interaction-types" title="Interaction Types" subtitle="100+ built-in interaction types" icon="lightning-bolt" >}}
  {{< card link="selectors" title="Selectors" subtitle="Target entities and blocks" icon="cursor-click" >}}
  {{< card link="combat" title="Combat" subtitle="Damage calculation and knockback" icon="fire" >}}
{{< /cards >}}

## Key Concepts

### Interaction Assets

Interactions are assets loaded from data packs. Assets are stored in an indexed map - you first get the index, then retrieve the asset:

```java
import com.hypixel.hytale.server.core.modules.interaction.interaction.config.Interaction;
import com.hypixel.hytale.assetstore.map.IndexedLookupTableAssetMap;

// Get the asset map
IndexedLookupTableAssetMap<String, Interaction> assetMap = Interaction.getAssetMap();

// Get index from string ID
int index = assetMap.getIndex("my_interaction");

// Get interaction by index
Interaction interaction = assetMap.getAsset(index);

// Or combined (but check for null!)
if (index != Integer.MIN_VALUE) {
    Interaction myInteraction = assetMap.getAsset(index);
}
```

{{< callout type="warning" >}}
**Important:** `getAsset()` takes an `int` index, not a String. Use `getIndex()` first to convert the string ID to an index. Returns `Integer.MIN_VALUE` if not found.
{{< /callout >}}

### Interaction Context

When interactions run, they receive an `InteractionContext` with:

- **Entity reference** - The entity performing the interaction
- **Held item** - The item being used
- **Target block/entity** - What's being targeted
- **State tracking** - Progress and timing information

### Interaction States

**Package:** `com.hypixel.hytale.protocol`

```java
public enum InteractionState {
    Finished(0),     // Completed successfully
    Skip(1),         // Skipped by user
    ItemChanged(2),  // Cancelled due to item change
    Failed(3),       // Failed to execute
    NotFinished(4);  // Still running
}
```

| State | Value | Description |
|-------|-------|-------------|
| `Finished` | 0 | Interaction completed successfully |
| `Skip` | 1 | User requested to skip |
| `ItemChanged` | 2 | Cancelled because held item changed |
| `Failed` | 3 | Interaction failed to execute |
| `NotFinished` | 4 | Still running, not yet complete |

## Interaction Categories

### Block Interactions

Operations on blocks:

| Interaction | Description |
|-------------|-------------|
| `PlaceBlockInteraction` | Place a block |
| `BreakBlockInteraction` | Break a block |
| `DestroyBlockInteraction` | Destroy without drops |
| `ChangeBlockInteraction` | Change block type |
| `UseBlockInteraction` | Interact with block |
| `PlaceFluidInteraction` | Place fluid |

### Item Interactions

Operations with items:

| Interaction | Description |
|-------------|-------------|
| `AddItemInteraction` | Add item to inventory |
| `EquipItemInteraction` | Equip an item |
| `ModifyInventoryInteraction` | Modify inventory contents |

### Entity Interactions

Operations on entities:

| Interaction | Description |
|-------------|-------------|
| `UseEntityInteraction` | Interact with entity |
| `RemoveEntityInteraction` | Remove an entity |
| `ApplyEffectInteraction` | Apply status effect |
| `ClearEntityEffectInteraction` | Remove effects |

### Combat Interactions

Damage and combat:

| Interaction | Description |
|-------------|-------------|
| `DamageCalculator` | Calculate damage |
| `DamageEffects` | Apply damage effects |
| `Knockback` | Apply knockback |
| `DirectionalKnockback` | Directional knockback |
| `ForceKnockback` | Force-based knockback |

### UI Interactions

User interface:

| Interaction | Description |
|-------------|-------------|
| `OpenContainerInteraction` | Open container UI |
| `OpenPageInteraction` | Open a page |
| `OpenCustomUIInteraction` | Open custom UI |
| `SendMessageInteraction` | Send message to player |

### Structure Interactions

World modification:

| Interaction | Description |
|-------------|-------------|
| `SpawnPrefabInteraction` | Spawn a prefab/structure |
| `LaunchProjectileInteraction` | Launch projectile |

### Control Flow

Chain and condition interactions:

| Interaction | Description |
|-------------|-------------|
| `SerialInteraction` | Run interactions in sequence |
| `ParallelInteraction` | Run interactions simultaneously |
| `SelectInteraction` | Choose between interactions |
| `ConditionInteraction` | Conditional execution |
| `RepeatInteraction` | Repeat an interaction |
| `CancelChainInteraction` | Cancel the chain |

### Stat Interactions

Entity statistics:

| Interaction | Description |
|-------------|-------------|
| `ChangeStatInteraction` | Modify a stat |
| `StatsConditionInteraction` | Check stat conditions |

## Interaction Properties

Common properties on all interactions:

```yaml
# Example interaction configuration
MyInteraction:
  Type: PlaceBlock
  RunTime: 0.5               # Duration in seconds
  ViewDistance: 96.0          # Visibility distance
  HorizontalSpeedMultiplier: 1.0
  CancelOnItemChange: true
  Effects:
    WaitForAnimationToFinish: true
    ItemAnimationId: "swing"
  Rules:
    # Activation rules
```

### InteractionEffects

Visual and audio effects:

- `ItemAnimationId` - Animation to play
- `WaitForAnimationToFinish` - Wait for animation
- Sound effects
- Particle effects

### InteractionRules

Control when interactions can run:

- Game mode restrictions
- State requirements
- Cooldown checks

## Selectors

Selectors determine what entities or blocks are targeted:

| Selector | Description |
|----------|-------------|
| `RaycastSelector` | Cast ray from camera |
| `AOECircleSelector` | Area of effect circle |
| `AOECylinderSelector` | Area of effect cylinder |
| `StabSelector` | Close-range stab |
| `HorizontalSelector` | Horizontal sweep |

## Accessing Interactions

### From Items

Items define their interactions in asset files. At runtime:

```java
ItemStack item = player.getInventory().getActiveItem();
Item itemAsset = item.getItem();
// Item defines its primary/secondary interactions
```

### From Blocks

Blocks define use interactions:

```java
BlockType blockType = world.getBlockType(position);
// Block defines its use interaction
```

## Best Practices

{{< callout type="info" >}}
**Interaction Guidelines:**
- Interactions are primarily data-driven through assets
- Use existing interaction types when possible
- Chain interactions for complex behaviors
- Use selectors to target appropriately
- Consider game mode in rules
{{< /callout >}}

{{< callout type="warning" >}}
**Performance Note:** Complex interaction chains with many parallel operations can impact performance. Keep chains efficient.
{{< /callout >}}

## Further Reading

For detailed information on specific interaction types, see the subpages.