Skip to main content
Animation configuration files define how items behave visually in first-person and third-person perspectives. These JSON files control character animations, camera movements, and item wiggle physics.

​
File Location

Animation configs are stored in: 
Server/Item/Animations/
├── Blaster.json
├── Lightsaber.json
├── OrbisGalactic_Lightsaber_Animations.json
├── OrbisGalactic_Darksaber_Animations.json
└── ...

​
Core Structure

Animation configuration files contain three main sections:
  1. Animations - Animation definitions for various states
  2. WiggleWeights - Physics-based item movement
  3. Camera - Camera rotation constraints
  4. PullbackConfig - (Optional) Item positioning overrides

​
Animations Section

The Animations object maps animation names to their configuration.

​
Movement Animations

{
  "Animations": {
    "Idle": {
      "FirstPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Idle_FPS.blockyanim",
      "ThirdPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Idle.blockyanim",
      "Speed": 0.5,
      "Looping": true
    },
    "Walk": {
      "FirstPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Walk_FPS.blockyanim",
      "ThirdPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Walk.blockyanim",
      "Speed": 1.0,
      "Looping": true
    },
    "Run": {
      "FirstPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Run_FPS.blockyanim",
      "ThirdPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Run.blockyanim",
      "Speed": 0.9,
      "Looping": true
    }
  }
}

​
Custom Action Animations

{
  "Animations": {
    "OrbisGalactic_Lightsaber_Ignite": {
      "ThirdPerson": "Characters/Animations/Items/Dual_Handed/Longsword/Lightsaber_Ignite.blockyanim",
      "ThirdPersonMoving": "Characters/Animations/Items/Dual_Handed/Longsword/Lightsaber_Ignite.blockyanim",
      "ThirdPersonFace": "Characters/Animations/Expressions/Rage.blockyanim",
      "FirstPerson": "Characters/Animations/Items/Dual_Handed/Longsword/Lightsaber_Ignite.blockyanim",
      "Speed": 0.25,
      "KeepPreviousFirstPersonAnimation": false,
      "ClipsGeometry": false,
      "BlendingDuration": 0
    },
    "Shoot": {
      "ThirdPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Attacks/Shoot/Shoot.blockyanim",
      "ThirdPersonMoving": "Characters/Animations/Items/Dual_Handed/Rifle/Attacks/Shoot/Shoot_Moving.blockyanim",
      "FirstPerson": "Characters/Animations/Items/Dual_Handed/Rifle/Attacks/Shoot/Shoot_FPS.blockyanim",
      "ThirdPersonFace": "Characters/Animations/Expressions/Frown.blockyanim",
      "Speed": 1,
      "BlendingDuration": 0
    }
  }
}

​
Animation Properties

​
FirstPerson
string
Path to the .blockyanim file for first-person view.Example: "Characters/Animations/Items/Dual_Handed/Rifle/Idle_FPS.blockyanim"
​
ThirdPerson
string
Path to the .blockyanim file for third-person view when stationary.Example: "Characters/Animations/Items/Dual_Handed/Rifle/Idle.blockyanim"
​
ThirdPersonMoving
string
Path to the .blockyanim file for third-person view when moving.Used for action animations like shooting or special abilities.
​
ThirdPersonFace
string
Path to facial expression animation that plays during this action.Common expressions:
  • "Characters/Animations/Expressions/Rage.blockyanim"
  • "Characters/Animations/Expressions/Frown.blockyanim"
  • "Characters/Animations/Expressions/Smile.blockyanim"
​
Speed
number
Animation playback speed multiplier. Lower values slow the animation down.
  • 0.25 - Very slow (lightsaber ignition)
  • 0.5 - Half speed (idle)
  • 1.0 - Normal speed
  • 2.0 - Double speed (sprint)
​
Looping
boolean
default:false
Whether the animation should loop continuously.Set to true for idle, walk, run animations. Set to false for one-shot actions like attacks.
​
BlendingDuration
number
default:0
Time in seconds to blend from the previous animation to this one.
  • 0 - Instant transition (attacks)
  • 0.1 - Quick blend (crouch)
  • 0.4 - Smooth blend (falling)
​
KeepPreviousFirstPersonAnimation
boolean
default:false
If true, maintains the previous first-person animation while playing the third-person animation.Useful for jump/fall animations where first-person view shouldn’t change.
​
ClipsGeometry
boolean
default:false
Whether the animation allows the item to clip through geometry.
Set to true for retraction/sheathing animations to prevent visual glitches.

​
WiggleWeights

Controls physics-based item movement in first-person view, adding realistic sway and bob. 
{
  "WiggleWeights": {
    "Pitch": 2.5,
    "PitchDeceleration": 0.1,
    "Roll": 0.1,
    "RollDeceleration": 0.1,
    "X": 2.5,
    "XDeceleration": 0.1,
    "Y": 0.1,
    "YDeceleration": 0.1,
    "Z": 0.1,
    "ZDeceleration": 0.1
  }
}
​
Pitch
number
Rotation around the X-axis (up/down tilt). Higher values increase sway.
​
PitchDeceleration
number
How quickly pitch movement dampens. Lower = slower return to neutral.
​
Roll
number
Rotation around the Z-axis (side-to-side tilt).
​
RollDeceleration
number
How quickly roll movement dampens.
​
X
number
Linear movement along the X-axis (left/right).
​
XDeceleration
number
How quickly X movement dampens.
​
Y
number
Linear movement along the Y-axis (up/down).
​
YDeceleration
number
How quickly Y movement dampens.
​
Z
number
Linear movement along the Z-axis (forward/backward).
​
ZDeceleration
number
How quickly Z movement dampens.
For lightsabers, use higher Pitch and X values (2.5) to create dramatic swaying. For precise weapons like blasters, use lower values (1.0).

​
Camera Configuration

Defines camera rotation constraints and target skeleton nodes. 
{
  "Camera": {
    "Pitch": {
      "AngleRange": {
        "Max": 60,
        "Min": -30
      },
      "TargetNodes": [
        "Head",
        "LShoulder",
        "RShoulder"
      ]
    },
    "Yaw": {
      "AngleRange": {
        "Max": 45,
        "Min": -45
      },
      "TargetNodes": [
        "Belly"
      ]
    }
  }
}
​
Pitch.AngleRange
object
Vertical camera rotation limits in degrees.
  • Max: Maximum upward angle (60 = look up significantly)
  • Min: Maximum downward angle (-30 = look down moderately)
​
Pitch.TargetNodes
array
Skeleton nodes that rotate with vertical camera movement.Common nodes: "Head", "LShoulder", "RShoulder"
​
Yaw.AngleRange
object
Horizontal camera rotation limits in degrees.
  • Max: Maximum rightward angle
  • Min: Maximum leftward angle
​
Yaw.TargetNodes
array
Skeleton nodes that rotate with horizontal camera movement.Common nodes: "Belly", "Torso"
Camera configuration is optional. Omitting the AngleRange object removes rotation limits.

​
PullbackConfig (Optional)

Overrides item positioning and rotation offsets for left and right hands. 
{
  "PullbackConfig": {
    "LeftOffsetOverride": [0, 0, -1.6],
    "LeftRotationOverride": [0, 0, 0],
    "RightOffsetOverride": [0, 0, -1.6],
    "RightRotationOverride": [0, 0, 0]
  }
}
​
LeftOffsetOverride
array
[X, Y, Z] position offset for the left hand in Hytale units.
​
LeftRotationOverride
array
[X, Y, Z] rotation in degrees for the left hand.
​
RightOffsetOverride
array
[X, Y, Z] position offset for the right hand in Hytale units.
​
RightRotationOverride
array
[X, Y, Z] rotation in degrees for the right hand.

​
Common Animation States

Here’s a reference of standard animation states you may want to implement:

​
Movement States

  • Idle - Standing still
  • Walk / WalkBackward - Walking
  • Run / RunBackward - Running
  • Sprint - Sprinting
  • Crouch / CrouchWalk - Crouching
  • Jump / JumpWalk / JumpRun - Jumping variations
  • Fall / FallFar - Falling

​
Swimming States

  • SwimIdle - Floating on surface
  • Swim / SwimBackward / SwimFast - Surface swimming
  • SwimDive / SwimDiveBackward / SwimDiveFast - Underwater swimming
  • SwimFloat / SwimSink - Vertical movement in water
  • SwimJump - Jumping out of water

​
Flight States

  • FlyIdle - Hovering
  • Fly / FlyBackward / FlyFast - Flying movement

​
Climbing States

  • ClimbIdle - Hanging on wall
  • ClimbUp / ClimbDown - Vertical climbing
  • ClimbLeft / ClimbRight - Horizontal climbing

​
Action States

  • Interact - Using/interacting with objects
  • Shoot - Ranged attack
  • GuardBash - Melee attack
  • Custom actions (e.g., OrbisGalactic_Lightsaber_Ignite)
Not all states need to be defined. Hytale will use default animations for undefined states.

​
Best Practices

​
Animation Speed

  • Use slower speeds (0.2-0.3) for dramatic actions like lightsaber ignition
  • Use normal speed (1.0) for most combat actions
  • Use faster speeds (1.5-2.0) only for sprint animations

​
Blending

  • Use BlendingDuration: 0 for instant actions (attacks, shooting)
  • Use BlendingDuration: 0.1 for quick transitions (crouch, interact)
  • Use BlendingDuration: 0.4 for smooth transitions (falling)

​
Facial Expressions

Add personality to actions with ThirdPersonFace:
  • Rage - Intense actions (charged attacks, force powers)
  • Frown - Concentrated actions (shooting, precise movements)
  • Smile - Satisfying actions (retract lightsaber, successful hit)
Test animations in all movement states (standing, walking, running) to ensure smooth transitions.

Build docs developers (and LLMs) love

Get started for freeTalk to us