Adding Interactions

Concepts

Interactions define what happens when a player uses an item or ability. They form behavior trees:

RootInteraction (entry point, cooldowns)
    └── Interaction (Type: Chaining)
            ├── Interaction (Type: Simple - animation)
            │       └── Interaction (Type: Selector - hit detection)
            │               └── Interaction (Type: DamageEntity)
            ├── ... more attacks

Pack location:

Root interactions: Server/Item/RootInteractions/
Interactions: Server/Item/Interactions/

Base game reference:

Assets.zip/Server/Item/RootInteractions/
Assets.zip/Server/Item/Interactions/

Minimal Interaction

A simple attack that plays animation and deals damage.

Create Server/Item/Interactions/My_Attack.json in your pack:

{
  "Type": "Serial",
  "Interactions": [
    {
      "Type": "Simple",
      "RunTime": 0.3,
      "Effects": {
        "ItemAnimationId": "SwingLeft",
        "WorldSoundEventId": "SFX_Sword_Swing"
      }
    },
    {
      "Type": "Selector",
      "Selector": {
        "Id": "Horizontal",
        "StartDistance": 0.1,
        "EndDistance": 3.0,
        "Length": 90
      },
      "HitEntity": {
        "Interactions": [{
          "Type": "DamageEntity",
          "DamageCalculator": {
            "BaseDamage": { "Physical": 10 }
          }
        }]
      }
    }
  ]
}

Interaction Types

Flow Control

`Serial` - Run in sequence

{
  "Type": "Serial",
  "Interactions": ["Step1", "Step2", "Step3"]
}

Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.none.SerialInteraction

`Chaining` - Combo system (cycles through attacks)

{
  "Type": "Chaining",
  "ChainId": "MyCombo",
  "ChainingAllowance": 2.0,
  "Next": [
    { "Var": "Attack1", "DefaultValue": { "Interactions": ["Attack1"] } },
    { "Var": "Attack2", "DefaultValue": { "Interactions": ["Attack2"] } },
    { "Var": "Attack3", "DefaultValue": { "Interactions": ["Attack3"] } }
  ]
}

ChainingAllowance: Seconds before combo resets
ChainId: Shared counter ID (optional)

Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.client.ChainingInteraction

`Charging` - Hold to charge

{
  "Type": "Charging",
  "DisplayProgress": true,
  "Next": {
    "0": "QuickAttack",
    "0.5": "MediumAttack",
    "1.5": "FullChargeAttack"
  }
}

Keys are hold times in seconds.

Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.client.ChargingInteraction

`Condition` - Conditional branching

{
  "Type": "Condition",
  "RequiredGameMode": "Adventure",
  "Jumping": false,
  "Crouching": true,
  "Next": "CrouchAttack",
  "Failed": "NormalAttack"
}

`Simple` - Just effects, no logic

{
  "Type": "Simple",
  "RunTime": 0.5,
  "Effects": { ... }
}

Combat

`Selector` - Hit detection

{
  "Type": "Selector",
  "RunTime": 0.1,
  "Selector": {
    "Id": "Horizontal",
    "Direction": "ToLeft",
    "TestLineOfSight": true,
    "StartDistance": 0.1,
    "EndDistance": 3.0,
    "Length": 90,
    "ExtendTop": 0.5,
    "ExtendBottom": 0.5
  },
  "HitEntity": { "Interactions": [...] },
  "HitBlock": { "Interactions": [...] },
  "Next": { "Type": "Simple", "RunTime": 0.2 }
}

Selector types: Horizontal, Vertical, Sphere, Raycast

Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.client.SelectorInteraction

`DamageEntity` - Apply damage {#damageentity}

Dispatches a Damage event through the full damage pipeline.

{
  "Type": "DamageEntity",
  "DamageCalculator": {
    "BaseDamage": { "Physical": 20, "Fire": 10 },
    "CriticalHitChance": 0.1,
    "CriticalHitMultiplier": 2.0,
    "RandomPercentageModifier": 0.1
  },
  "DamageEffects": {
    "Knockback": {
      "Type": "Force",
      "Force": 5.0,
      "Direction": { "X": 0, "Y": 1, "Z": -1 }
    },
    "WorldParticles": [{ "SystemId": "Impact_Sparks" }],
    "WorldSoundEventId": "SFX_Hit"
  },
  "Next": "OnHitSuccess",
  "Failed": "OnMiss",
  "Blocked": "OnBlocked"
}

Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.server.DamageEntityInteraction

`LaunchProjectile` - Fire projectile

{
  "Type": "LaunchProjectile",
  "ProjectileId": "My_Bullet",
  "RunTime": 0.1,
  "SpawnOffset": { "X": 0, "Y": 1.5, "Z": 0.5 },
  "Effects": {
    "ItemAnimationId": "Shoot",
    "WorldSoundEventId": "SFX_Gunshot"
  }
}

Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.server.LaunchProjectileInteraction

Effects

`ApplyEffect` - Apply status effect

{
  "Type": "ApplyEffect",
  "EffectId": "Poison",
  "Entity": "Target",
  "Duration": 5.0
}

Entity values: Self, Target, Owner

`ClearEntityEffect` - Remove status effect

{
  "Type": "ClearEntityEffect",
  "Entity": "Target",
  "EntityEffectId": "Poison"
}

`ChangeState` - Modify entity state

{
  "Type": "ChangeState",
  "StatId": "Health",
  "Amount": -10,
  "Entity": "Target"
}

Utility

`ModifyInventory` - Consume/add items

{
  "Type": "ModifyInventory",
  "ItemToRemove": { "Id": "Ammo_Arrow", "Quantity": 1 },
  "Next": "ShootArrow",
  "Failed": "OutOfAmmo"
}

`Replace` - Variable substitution

{
  "Type": "Replace",
  "Var": "DamageOverride",
  "DefaultOk": true,
  "DefaultValue": { "Interactions": ["DefaultDamage"] }
}

Used with InteractionVars on items for per-item customization.

Effects Block

All interactions can have an Effects block:

{
  "Effects": {
    "ItemAnimationId": "SwingLeft",
    "ItemPlayerAnimationsId": "Sword",
    "WorldSoundEventId": "SFX_Swing",
    "LocalSoundEventId": "SFX_Swing_Local",
    "CameraEffect": "ScreenShake_Light",
    "WaitForAnimationToFinish": true,
    "StartDelay": 0.1,

    "Particles": [
      {
        "SystemId": "Dust_Puff",
        "PositionOffset": { "X": 0, "Y": 0, "Z": 1 },
        "Bone": "RightHand"
      }
    ],

    "Trails": [
      {
        "TrailId": "Sword_Trail",
        "TargetNodeName": "Blade_Tip",
        "PositionOffset": { "X": 0, "Y": 0, "Z": 0 }
      }
    ]
  }
}

Root Interactions

Entry points with cooldown management.

Create Server/Item/RootInteractions/Root_My_Attack.json:

{
  "RequireNewClick": true,
  "ClickQueuingTimeout": 0.2,
  "Cooldown": {
    "Id": "MyAttack",
    "Cooldown": 0.5
  },
  "Interactions": ["My_Attack"]
}

Fields:

RequireNewClick: Must release and press again
ClickQueuingTimeout: Buffer window for next input
Cooldown.Cooldown: Seconds before can use again
Cooldown.Id: Shared cooldown group (optional)

Inheritance

Interactions support Parent inheritance:

{
  "Parent": "Weapon_Sword_Primary_Swing_Left_Damage",
  "DamageCalculator": {
    "BaseDamage": { "Physical": 50 }
  }
}

Only override what you need to change.

Complete Example: 3-Hit Combo

Root Interaction

Server/Item/RootInteractions/Root_Custom_Combo.json:

{
  "RequireNewClick": true,
  "Cooldown": { "Cooldown": 0.3 },
  "Interactions": ["Custom_Combo_Chain"]
}

Chain (cycles attacks)

Server/Item/Interactions/Custom_Combo_Chain.json:

{
  "Type": "Chaining",
  "ChainingAllowance": 1.5,
  "Next": [
    { "Var": "Hit1", "DefaultValue": { "Interactions": ["Custom_Hit1"] } },
    { "Var": "Hit2", "DefaultValue": { "Interactions": ["Custom_Hit2"] } },
    { "Var": "Hit3", "DefaultValue": { "Interactions": ["Custom_Hit3"] } }
  ]
}

Individual Attacks

Server/Item/Interactions/Custom_Hit1.json:

{
  "Type": "Serial",
  "Interactions": [
    {
      "Type": "Simple",
      "RunTime": 0.15,
      "Effects": {
        "ItemAnimationId": "SwingLeft",
        "WorldSoundEventId": "SFX_Sword_Swing"
      }
    },
    {
      "Type": "Selector",
      "RunTime": 0.1,
      "Selector": { "Id": "Horizontal", "EndDistance": 2.5, "Length": 90 },
      "HitEntity": {
        "Interactions": [{
          "Type": "DamageEntity",
          "DamageCalculator": { "BaseDamage": { "Physical": 10 } },
          "DamageEffects": { "Knockback": { "Force": 3.0 } }
        }]
      }
    },
    {
      "Type": "Simple",
      "RunTime": 0.15
    }
  ]
}

(Repeat for Hit2, Hit3 with different animations and damage)

Using in Item

{
  "Parent": "Template_Weapon_Sword",
  "Interactions": {
    "Primary": "Root_Custom_Combo"
  }
}

Complete Example: Charged Attack

Server/Item/Interactions/Custom_Charged_Attack.json:

{
  "Type": "Charging",
  "DisplayProgress": true,
  "Next": {
    "0": {
      "Type": "Serial",
      "Interactions": [
        {
          "Type": "Simple",
          "RunTime": 0.2,
          "Effects": { "ItemAnimationId": "SwingLeft" }
        },
        {
          "Type": "Selector",
          "Selector": { "EndDistance": 2.0, "Length": 60 },
          "HitEntity": {
            "Interactions": [{
              "Type": "DamageEntity",
              "DamageCalculator": { "BaseDamage": { "Physical": 5 } }
            }]
          }
        }
      ]
    },
    "1.0": {
      "Type": "Serial",
      "Interactions": [
        {
          "Type": "Simple",
          "RunTime": 0.3,
          "Effects": {
            "ItemAnimationId": "SwingDown",
            "CameraEffect": "ScreenShake_Medium"
          }
        },
        {
          "Type": "Selector",
          "Selector": { "EndDistance": 4.0, "Length": 120 },
          "HitEntity": {
            "Interactions": [{
              "Type": "DamageEntity",
              "DamageCalculator": { "BaseDamage": { "Physical": 30 } },
              "DamageEffects": {
                "Knockback": { "Force": 10.0 },
                "WorldParticles": [{ "SystemId": "Impact_Heavy" }]
              }
            }]
          }
        }
      ]
    }
  }
}

File Locations

What	Your Pack	Base Game Reference
Interactions	`Server/Item/Interactions/`	`Assets.zip/Server/Item/Interactions/`
Root Interactions	`Server/Item/RootInteractions/`	`Assets.zip/Server/Item/RootInteractions/`
Weapon interactions	-	`Assets.zip/Server/Item/Interactions/Weapons/`
NPC attacks	-	`Assets.zip/Server/Item/Interactions/NPCs/`
Effects	`Server/Entity/Effects/`	`Assets.zip/Server/Entity/Effects/`
Particles	`Server/Particles/`	`Assets.zip/Server/Particles/`
Camera effects	`Server/Camera/`	`Assets.zip/Server/Camera/`