256 lines
7.1 KiB
Markdown
256 lines
7.1 KiB
Markdown
---
|
|
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.
|