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

title, type, weight

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

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

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:

# 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:

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

From Blocks

Blocks define use interactions:

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.