Animation Asset Reference

Intermediate40-60 minutesWindowsNotepad++Unity Editor

Animation is the mechanism by which Unturned™ items transition from static geometry to interactive game objects. A gun without a fire animation still shoots projectiles, but the player sees no slide movement, no recoil, no bolt cycling. A melee weapon without a swing animation still deals damage, but the player sees no arm motion, no blade arc, no impact reaction. The animation data is the visual complement to every item's .dat configuration, and a modder who provides complete, correctly configured animation for every action the item supports produces a mod that feels professional; a modder who ships static items with no animation produces a mod that players will describe as "broken" even if every other system works correctly.

This article is the 57 Studios™ canonical reference for the animation asset layer in Unturned modding. It documents the animation types that Unturned item scripts expect, the Unity AnimationClip import and configuration workflow, the Animator state machine structure for weapons and melee items, the animation event hooks that trigger script callbacks, the export settings that transfer animation data from Blender to Unity, and the diagnostic procedures for animations that play in the Unity Editor but not in the compiled game. This article focuses on the animation data itself: the clip properties, the state machine structure, and the engine-side expectations that the clips must satisfy. The Blender-to-Unity export workflow is covered in detail in Animations Export Blender to Unity; this article references that workflow for the export mechanics and concentrates on the animation asset type as it exists inside Unity and as it is consumed by the engine.

Documentation source: This article references the official Smartly Dressed Games modding documentation for animation export settings and the character rig specification. Shipped Unturned game files under Bundles\Items\Guns\ and Bundles\Items\Melee\ have been inspected to confirm the animation types and event hooks that the engine expects.

Who this article is for

This article is written for Unturned™ mod authors who have a working Unity project with the Unturned modding package imported, a master bundle configured per Asset Bundles Reference, and at least one item prefab with a rigged mesh. The reader should be comfortable with the Unity Editor's Animator window and should have a basic understanding of keyframe animation concepts (poses, interpolation, curves). If you have not yet rigged a mesh or authored an animation, start with Animations Export Blender to Unity for the full Blender-to-Unity pipeline. If you have not yet built a master bundle, start with Asset Bundles Reference.

What you'll learn

• The animation types that Unturned item scripts expect for weapons and melee items
• How AnimationClip assets are imported, configured, and wired into Animator state machines
• The standard Animator Controller structure for Unturned firearms and melee weapons
• How animation events trigger script callbacks at specific frames
• How to configure an Animator state machine for a weapon with idle, fire, reload, and equip animations
• How to configure an Animator state machine for a melee weapon with idle, slash, stab, and inspect animations
• The animation-related fields that appear in item .dat files
• Diagnostic procedures for the most common animation failures
• Worked examples from the shipped Unturned gun and melee asset files

Background: how Unturned drives item animations

Unturned's item animation system is driven by Unity's Animator component, which runs on every item prefab that has animated components. The Animator holds an AnimatorController, a state machine asset that defines named animation states, the AnimationClip assets those states play, and the transitions between states. Unturned item scripts (UseableGun, UseableMelee) send trigger parameters to the Animator at runtime to transition between states.

The relationship between the .dat file fields and the Animator Controller is as follows:

1. The .dat file defines what actions an item supports. For a melee weapon, Action_Primary and Action_Secondary define the primary and secondary attack types (Slash, Stab, Punch, Stomp). For a gun, Action defines the fire mode (Trigger, Bolt, Pump, Break), and attachment slots define what attachments can be equipped.
2. The Animator Controller must have a state for every action the .dat file declares. If the .dat declares Action_Primary Slash, the Animator must have a state named (or configured to respond to the trigger for) Slash. If the state is missing, the item script still runs the game logic (damage, hit detection, durability decrement), but no animation plays.
3. The item script sends trigger parameters to the Animator at the appropriate moment. The trigger name is derived from the action: pressing the primary attack button sends a trigger whose name the item script determines, typically primary or the action type name.

The sequence diagram above models the animation drive chain for a melee weapon's primary attack. The chain involves four distinct assets: the .dat file (action declaration), the Animator Controller (state machine), the AnimationClip (animation data), and the item script (runtime driver). A failure at any link in the chain produces an observable symptom: a missing .dat field means the script does not know what action to trigger; a missing Animator state means the trigger has no state to transition to; a missing or misconfigured AnimationClip means the state plays no visible motion; a missing animation event means the hit detection fires at the wrong frame or not at all.

Animation types by item category

Unturned items fall into two broad animation categories: weapons (guns) and melee weapons. Each category has a distinct set of expected animation states.

Gun animation types

State name	Trigger	Required?	Purpose
Idle	, (default state)	Yes	The weapon's at-rest pose. This is the state the Animator enters when the weapon is equipped and no other action is active.
Fire	fire (or primary)	Yes	The firing animation. Plays once per trigger pull. For automatic weapons, the Fire state loops or is retriggered on each round.
Reload	reload	Yes	The reload animation. The length of this clip determines how long the player is unable to fire during a reload.
Equip	equip	Recommended	The weapon-draw animation. Plays when the player switches to this weapon from another item. A short clip (0.3-0.5 seconds) is typical.
Aim	aim	Optional	The aim-down-sights transition. If provided, plays when the player presses the aim button.
Inspect	inspect	Optional	The weapon-inspect animation. Plays when the player presses the inspect key.
Bolt	bolt	Required for bolt-action guns	The bolt-cycling animation. Plays between shots for bolt-action rifles. For pump-action shotguns, a Pump state replaces Bolt.
Break	break	Required for break-action guns	The barrel-break animation for break-action shotguns.
Jam	jam	Optional	The weapon-jam animation. Plays when the gun's durability causes a misfire.

Melee animation types

State name	Trigger	Required?	Purpose
Idle	, (default state)	Yes	The weapon's at-rest pose.
Slash	primary or secondary	Required if Action_Primary or Action_Secondary is Slash	The horizontal swing animation.
Stab	primary or secondary	Required if Action_Primary or Action_Secondary is Stab	The forward thrust animation.
Punch	primary or secondary	Required if Action_Primary or Action_Secondary is Punch	The short blunt-strike animation.
Stomp	primary or secondary	Required if Action_Primary or Action_Secondary is Stomp	The downward stomp animation.
Inspect	inspect	Optional	The weapon-inspect animation.

The state name must match the value set in the item's .dat file action fields. If Action_Primary is set to Slash, the Animator Controller must have a state named Slash that can be reached by the primary trigger. If Action_Secondary is set to Stab, the Animator Controller must have a state named Stab reachable by the secondary trigger. The engine item script derives the trigger name from which button was pressed (primary for left mouse, secondary for right mouse) and expects the Animator to have a state corresponding to the action type configured in the .dat file for that button.

AnimationClip import and configuration

Each AnimationClip in Unity is an imported asset, typically originating from an FBX file exported from Blender or another 3D authoring tool. The clip carries the keyframe data for every animated bone across the clip's duration. When the clip is imported as part of an FBX file, Unity's import settings determine how the clip data is processed.

AnimationClip import settings

Setting	Recommended value	Purpose
Loop Time	Enabled for Idle; disabled for all others	Controls whether the clip loops. Only Idle should loop.
Loop Pose	Enabled for Idle	Ensures the start and end poses of the Idle clip match, producing a seamless loop.
Cycle Offset	0	Offset into the loop cycle. Not used for Unturned weapon animations.
Root Transform Rotation	Bake into Pose	Bakes the root bone's rotation into the clip data.
Root Transform Position (Y)	Bake into Pose	Bakes vertical root motion into the clip data.
Root Transform Position (XZ)	Bake into Pose	Bakes horizontal root motion into the clip data.
Mirror	Disabled	Mirrors the animation. Not used for Unturned weapon animations.
Body Mask	None	Animation layer masking. Not used for standard item animations.
Events	Populated with hit-frame event markers	Animation events that trigger script callbacks at specific frames.

The Loop Time and Loop Pose settings warrant particular attention. The Idle animation should loop seamlessly: the first and last frames should have the identical pose so that the transition from the clip's end back to its start is imperceptible. If Loop Pose is enabled and the loop is seamless, Unity blends the start and end frames automatically. If the loop is not seamless, the player sees a brief visual discontinuity on each loop cycle, which is especially noticeable during the idle state because the player spends the majority of time in idle.

Animation compression

Unity applies compression to imported AnimationClip data to reduce the clip's memory footprint. The default compression settings work acceptably for most weapon animations, but aggressive compression can introduce visible artefacts: jittery bone movement, lost keyframes on fast motions, or bones that drift away from their intended positions over the clip's duration.

Compression setting	Recommended value	Purpose
Anim. Compression	Optimal (default)	Uses keyframe reduction to compress clip data. For weapons with precise hit-frame timing, consider Off to preserve every keyframe.
Rotation Error	0.5	Maximum allowed rotation error in degrees. Lower values preserve more keyframes.
Position Error	0.5	Maximum allowed position error as a percentage of the bone's length. Lower values produce cleaner motion.
Scale Error	0.5	Maximum allowed scale error as a percentage.

For weapons that require precise timing (a fire animation where the hit frame must align with a specific moment in the animation curve), disable compression by setting Anim. Compression to Off. The file size increase is negligible for individual weapon animation clips (typically a few hundred kilobytes at most). For large character animation sets with dozens of clips, Optimal compression with conservative error thresholds (0.1 or 0.2 for rotation and position error) is the cohort recommendation.

The Animator Controller state machine

The Animator Controller is a Unity asset that defines the states, transitions, and parameters that make up the item's animation behaviour. Every item prefab that has an Animator component references an Animator Controller. The controller is authored in the Unity Editor's Animator window and saved as a .controller asset in the Unity project.

Melee weapon Animator Controller structure

A melee weapon's Animator Controller follows a simple pattern: a default Idle state, one state per action type configured in the .dat file, an optional Inspect state, and transitions from Idle to each action state triggered by parameter.

The state machine above shows the standard melee weapon animation structure. Every action state transitions back to Idle on completion. The Idle state is the hub: all actions start from Idle and return to Idle. There are no transitions between action states (you cannot transition from Slash directly to Stab; you must return to Idle first).

The transition from each action state back to Idle should have Has Exit Time enabled, with the exit time set to the end of the clip (1.0 normalized time). This ensures the action animation plays to completion before the weapon returns to the idle pose. If Has Exit Time is disabled and the transition is triggered immediately, the action animation is interrupted, which produces a visually jarring effect.

Gun Animator Controller structure

A gun's Animator Controller is more complex because guns have more animation states. The controller must handle fire, reload (full magazine), reload (single round for bolt/pump/break actions), equip, and optional aim and inspect states.

The state machine above shows the standard gun animation structure. The Fire state has a self-transition for automatic weapons: while the trigger is held and the gun has ammunition, the Fire trigger is repeatedly sent, and the Fire state retriggers. For semi-automatic weapons, the Fire state plays once and transitions back to Idle on completion. The Bolt state is present only for bolt-action rifles; pump-action shotguns use a Pump state instead, and break-action shotguns use a Break state.

Animator Controller parameters

The Animator Controller uses trigger parameters to transition between states. Trigger parameters are boolean-like: they are set to true momentarily and automatically reset to false after being consumed by a transition.

Parameter name	Type	Purpose
primary	Trigger	Sent when the player presses the primary attack button.
secondary	Trigger	Sent when the player presses the secondary attack button.
fire	Trigger	Sent when the player presses the fire button (guns).
reload	Trigger	Sent when the player presses the reload button.
equip	Trigger	Sent when the player equips the weapon.
bolt	Trigger	Sent after a bolt-action rifle fires a round.
pump	Trigger	Sent after a pump-action shotgun fires a round.
break	Trigger	Sent after a break-action shotgun fires.
aim	Trigger	Sent when the player toggles aim-down-sights.
inspect	Trigger	Sent when the player presses the inspect key.
jam	Trigger	Sent when the gun jams due to low durability.

The exact parameter names that the item scripts use are determined by the Unity scripts in the Unturned modding package. The parameter names in the Animator Controller must match the names the scripts send. If the script sends a trigger named fire and the Animator Controller has a parameter named Fire (case mismatch), the transition will never fire.

Parameter name case sensitivity

Unity's Animator parameter names are case-sensitive. A trigger named primary does not match a state transition that listens for Primary. The cohort recommendation is to use all-lowercase parameter names (matching the convention used by the Unturned item scripts) and to verify parameter names by inspecting the script source or by testing with a minimal Animator Controller that transitions correctly.

Animation events: hooking script callbacks

Animation events are markers placed at specific frames within an AnimationClip that trigger a callback function on any script attached to the same GameObject as the Animator. Unturned item scripts use animation events to trigger the mechanical effects of an animation at the correct visual moment: the hit-frame event on a melee swing triggers the hit detection logic, and the fire-frame event on a gun triggers the projectile spawn.

Standard animation events for weapons

Event function name	Clip	Typical frame	Purpose
OnHit	Slash, Stab, Punch, Stomp	30-40% through the clip	Triggers the hit detection sphere cast for melee weapons. This event must fire at the moment the weapon's blade visually intersects the target.
OnFire	Fire	20-30% through the clip	Triggers the projectile spawn and recoil for guns. This event must fire at the moment the muzzle flash would be visible.
OnEjectShell	Fire, Bolt	After OnFire, before clip end	Triggers the shell casing ejection. For bolt-action rifles, this event fires during the Bolt clip, not the Fire clip.
OnReloadComplete	Reload	90-100% through the clip	Marks the moment the magazine is seated and the weapon is ready to fire again.
OnBoltCycle	Bolt	40-60% through the clip	Triggers the bolt cycling logic for bolt-action rifles.

The frame at which an animation event is placed is critical. An OnHit event placed too early in the Slash clip triggers hit detection before the weapon's blade visually reaches the target, producing hits that register before the player sees the swing connect. An OnHit event placed too late triggers hit detection after the blade has passed through the target, producing hits that register on the backswing or not at all. The cohort practice is to place the hit-frame event at the frame where the weapon's blade visually reaches the midpoint of its arc, as viewed from the first-person camera.

Placing animation events in Unity

Animation events are placed in the Unity Editor's Animation window:

1. Open the Animation window (Window > Animation > Animation).
2. Select the .fbx asset or the AnimationClip asset in the Project window.
3. In the Animation window, the clip's timeline is displayed. Scrub the playhead to the desired frame.
4. Click the Add Event button (a small marker icon in the toolbar) at the desired frame position.
5. In the event dialog, enter the function name (e.g., OnHit) in the Function field.
6. If the function accepts parameters, enter them in the fields that appear below. Most Unturned item script callbacks do not require parameters; leave them empty.

Animation events are stored as part of the AnimationClip asset. They survive FBX re-imports if the clip's name and the event function names remain unchanged. However, if the FBX is re-exported from Blender with a different clip name or a different frame count, the events may be lost or misaligned. The cohort recommendation is to place animation events in Unity after the FBX import is finalized and the animation is confirmed to play correctly, and to re-check event placement after every FBX re-import.

Animation-related .dat fields

Several .dat fields in item configuration files reference or control animation behaviour. These fields connect the .dat layer to the Animator Controller layer.

Melee item animation fields

Field	Type	Values	Purpose
Action_Primary	enum	Slash, Stab, Punch, Stomp	The animation type for the primary attack. Must have a matching state in the Animator Controller.
Action_Secondary	enum	Slash, Stab, Punch, Stomp	The animation type for the secondary attack.
Attack	enum	Melee, Axe, Hammer	The audio category for the swing sound. Does not affect animation, but the sound plays in sync with the animation.

Gun item animation fields

Field	Type	Values	Purpose
Action	enum	Trigger, Bolt, Pump, Break, String	The fire mechanism type. Determines which animation states the item script will trigger (Bolt state for bolt-action, Pump state for pump-action, etc.).
Firerate	integer	Frames per fire	The delay between shots for automatic weapons. Does not directly control animation, but the Fire animation clip's duration should be compatible with the firerate.
Has_Aim_Anim	flag	presence	If present, the item script will trigger the aim parameter when the player aims down sights.

The Action field on a gun .dat file is the field that determines which additional animation states the Animator Controller must provide beyond the basic Idle, Fire, Reload, and Equip states. A gun with Action Bolt requires a Bolt state in the Animator Controller. A gun with Action Pump requires a Pump state. A gun with Action Break requires a Break state. If the required state is missing, the weapon still fires and deals damage, but the bolt/pump/break visual cycle is absent.

Unturned's character rig and its implications for animation

The official Smartly Dressed Games documentation describes Unturned's character rig with the following statement: "Unturned's character rig is terrible." The documentation recommends using existing animations for sanity. This is not a dismissive comment; it is a practical warning about the rig's structural characteristics that make custom animation authoring challenging.

The character rig has several documented properties that affect animation authoring:

• The rig uses a non-standard bone hierarchy that does not map cleanly to Unity's Humanoid rig or to Blender's armature system defaults.
• The rig's bone axes are oriented in directions that differ from both Blender's and Unity's default orientations, requiring explicit axis configuration during FBX export.
• The rig's scale is non-uniform in some bones, producing scaling artefacts when animations created on a standard Blender rig are retargeted to the Unturned rig.
• The Item.prefab is attached to the left or right hand hook bone with a local rotation of (0, 0, 90), meaning items are rotated 90 degrees on the Z axis relative to the hand bone.

For these reasons, the cohort recommendation for most modders is to use existing Unturned animations as a base and to create custom animations only when an item genuinely requires unique motion that cannot be achieved by modifying an existing animation. The existing animations in the Unturned asset set cover the standard action types (Slash, Stab, Fire, Reload, Equip) for most weapon categories and can be adapted by adjusting timing, adding or removing keyframes, or blending between existing clips.

FBX export settings for the Unturned rig

The export settings documented in the official Smartly Dressed Games documentation for the Unturned character rig are as follows. These settings must be applied in Blender's FBX export dialog when exporting animations that use the Unturned character rig.

The scene unit system must be metric with unit scale set to 1.0 and length set to meters. The Skeleton node must be selected before export. The export settings that differ from default are:

Setting	Value	Purpose
Selected Objects	True	Export only the selected skeleton and its child meshes.
Apply Scale	FBX Units Scale	Bakes the scene unit scale into the exported file.
Add Leaf Bones	False	Prevents phantom leaf bones from being added to the exported skeleton.
Primary Bone Axis	+X	Sets the primary bone axis to match Unturned's rig orientation.
Secondary Bone Axis	-Y	Sets the secondary bone axis to match Unturned's rig orientation.

The Primary Bone Axis and Secondary Bone Axis settings are the most critical. The Unturned rig uses +X as the primary bone axis and -Y as the secondary bone axis. Blender's default bone axes are +Y primary and +X secondary. Exporting with Blender's default axes produces a rig where bones are rotated 90 degrees from their intended orientation, which manifests in Unity as bones that point in the wrong direction and animations that play sideways.

Worked example: configuring a gun Animator Controller

This worked example walks through the complete process of configuring an Animator Controller for a custom semi-automatic rifle. The rifle uses Action Trigger, has standard fire and reload mechanics, and includes an optional aim-down-sights animation.

Step 1: Identify required animation states

The rifle's .dat file declares Action Trigger. The required animation states are: Idle, Fire, Reload, and Equip. The optional states are Aim and Inspect. The Animator Controller must have at least the four required states.

Step 2: Import animation clips

Import the FBX file containing the rifle's animations into the Unity project. In the FBX import settings, on the Animation tab, confirm that each clip is listed with the correct name, start frame, and end frame. Configure each clip's loop settings:

• Idle: Loop Time enabled, Loop Pose enabled
• Fire: Loop Time disabled
• Reload: Loop Time disabled
• Equip: Loop Time disabled
• Aim: Loop Time disabled (single transition, not a loop)
• Inspect: Loop Time disabled

Step 3: Create the Animator Controller

In the Unity Project window, right-click and select Create > Animator Controller. Name it CustomRifleAnimator. Double-click to open the Animator window.

Step 4: Create states

Drag each AnimationClip from the Project window into the Animator window. Unity creates a state for each clip. Name the states to match the clip names: Idle, Fire, Reload, Equip, Aim, Inspect.

Step 5: Set the default state

Right-click the Idle state and select Set as Layer Default State. The Idle state turns orange, indicating it is the entry state.

Step 6: Create trigger parameters

In the Animator window's Parameters panel, add the following trigger parameters: fire, reload, equip, aim, inspect.

Step 7: Create transitions

Create transitions from each state:

• Right-click Idle, select Make Transition, click Fire. Select the transition arrow. In the Inspector, under Conditions, add a condition: fire (the trigger parameter). Disable Has Exit Time.
• Repeat for: Idle to Reload (condition: reload), Idle to Equip (condition: equip), Idle to Aim (condition: aim), Idle to Inspect (condition: inspect).
• From Fire, Reload, Equip, and Inspect, create transitions back to Idle with Has Exit Time enabled and Exit Time set to 1.0.
• From Aim, create a transition back to Idle with condition aim (toggle) and Has Exit Time disabled.

Step 8: Place animation events

Open the Animation window. Select the Fire clip. Scrub to the frame where the muzzle flash would be visible. Add an animation event with function name OnFire. Select the Reload clip. Scrub to the frame where the magazine seats. Add an animation event with function name OnReloadComplete.

Step 9: Assign the Animator Controller to the prefab

Select the rifle prefab in the Project window. In the Inspector, confirm that an Animator component is present. Assign the CustomRifleAnimator controller to the Controller field.

Step 10: Build the master bundle and test

Build the master bundle, copy it to the mod's test folder, launch Unturned in single-player, spawn the rifle, and test each animation state: equip, fire, reload, aim, inspect. Confirm that every animation plays correctly and that animation events fire at the expected moments.

Worked example: configuring a melee Animator Controller

This worked example walks through the complete process of configuring an Animator Controller for a custom two-handed axe. The axe uses Action_Primary Slash and Action_Secondary Stab, is flagged as TwoHanded, and includes an inspect animation.

Step 1: Identify required animation states

The axe's .dat file declares Action_Primary Slash and Action_Secondary Stab. The required animation states are: Idle, Slash, and Stab. The optional state is Inspect.

Step 2: Import animation clips

Import the FBX file. Configure each clip:

• Idle: Loop Time enabled, Loop Pose enabled
• Slash: Loop Time disabled
• Stab: Loop Time disabled
• Inspect: Loop Time disabled

Step 3: Create the Animator Controller

Right-click in the Project window, select Create > Animator Controller. Name it CustomAxeAnimator.

Step 4: Create states and set default

Drag the clips into the Animator window to create states. Set Idle as the default state.

Step 5: Create trigger parameters

Add trigger parameters: primary, secondary, inspect.

Step 6: Create transitions

• Idle to Slash with condition primary, Has Exit Time disabled.
• Idle to Stab with condition secondary, Has Exit Time disabled.
• Idle to Inspect with condition inspect, Has Exit Time disabled.
• Slash to Idle with Has Exit Time enabled, Exit Time 1.0.
• Stab to Idle with Has Exit Time enabled, Exit Time 1.0.
• Inspect to Idle with Has Exit Time enabled, Exit Time 1.0.

Step 7: Place hit-frame animation events

Open the Animation window. Select the Slash clip. Scrub to the frame where the axe blade is at the midpoint of its horizontal arc. Add an animation event with function name OnHit. Select the Stab clip. Scrub to the frame where the axe blade is fully extended forward. Add an animation event with function name OnHit.

Step 8: Assign the controller and test

Assign CustomAxeAnimator to the axe prefab's Animator component. Build the bundle, copy to the test folder, test in single-player. Confirm that primary attack triggers the Slash animation, secondary attack triggers the Stab animation, and hit detection registers at the correct frames.

Diagnostic table

Symptom	Most likely cause	Resolution
Animation does not play when action is triggered	Animator Controller missing the required state	Add the state matching the .dat file's action type to the Animator Controller
Animation plays but item is static (no visible motion)	AnimationClip has no keyframe data or was exported with the wrong bone axes	Re-export the FBX with the correct Primary and Secondary Bone Axis settings
Hit detection fires at the wrong moment	Animation event placed at an incorrect frame	Adjust the OnHit event position in the Animation window to the correct frame
Animation plays sideways or with bones pointing in wrong directions	Incorrect Primary or Secondary Bone Axis on FBX export	Re-export with Primary Bone Axis +X and Secondary Bone Axis -Y
Idle animation has a visible stutter at the loop point	Loop Pose not enabled or first and last frames do not match	Enable Loop Pose in the clip import settings; if the loop still stutters, adjust the first or last keyframe in Blender to create a seamless loop
Fire animation retriggers too fast (visual stutter)	Clip duration is longer than the weapon's firerate interval	Shorten the Fire clip or increase the firerate value in the .dat file
Reload animation plays but the weapon can fire before the clip ends	OnReloadComplete event placed too early in the clip	Move the OnReloadComplete event later in the clip (80-90% of duration)
Inspect animation does not play	Animator Controller is missing an Inspect state or the state does not have a transition from Idle	Add the Inspect state and a transition from Idle with the inspect trigger condition
Animation events disappear after FBX re-import	The clip name changed or the clip was replaced in the re-import	Re-add animation events in the Animation window; consider using a separate AnimationClip override in Unity that is not part of the FBX import
Animation plays but the weapon does not deal damage	The .dat file has Damage_* fields set to 0, not an animation issue	Check the .dat file's damage fields; confirm the hit-frame event fires and the weapon's range is sufficient
Pink material on weapon model during animation	Shader compilation failure unrelated to animation	Rebuild the master bundle with the correct Unity version and shader settings

Best practices

• Author one Animator Controller per weapon family, not per weapon. A rifle family (standard, DMR, carbine variants) can share one Animator Controller if the animation clips are shared.
• Place the OnHit animation event at the frame where the weapon visually intersects the target. Test by recording the animation playback in the Unity Editor and scrubbing frame by frame.
• Enable Loop Pose for Idle clips and verify the loop is seamless in the Unity Editor preview before building the bundle.
• Disable Add Leaf Bones in the Blender FBX export settings. Leaf bones produce phantom joints in Unity that interfere with animation playback.
• Set Primary Bone Axis to +X and Secondary Bone Axis to -Y for animations intended for the Unturned character rig.
• Use a separate AnimationClip asset (created in Unity, not imported from FBX) for animation event configuration if the FBX is frequently re-exported. This preserves the event placement across re-imports.
• Test every animation state in a local single-player session before uploading to the Workshop. A missing state or misconfigured trigger is much easier to fix during development than after publication.
• Keep animation clips short. A fire animation longer than 0.5 seconds feels sluggish; a reload animation longer than 3 seconds frustrates players in combat.
• Match the Fire clip duration to the weapon's firerate. If the firerate is 600 rounds per minute (10 rounds per second, 0.1 seconds per round), the Fire clip must complete within 0.1 seconds or the animation will lag behind the actual firing rate.
• Document the animation states and trigger parameters in the mod's project notes. A new collaborator should be able to read one document and understand which states exist and which triggers drive them.

Frequently asked questions

What is the difference between Action (gun .dat) and Action_Primary (melee .dat)?

Action on a gun defines the firing mechanism type (Trigger, Bolt, Pump, Break, String). It controls which additional animation states the gun requires (Bolt state for bolt-action, Pump state for pump-action). Action_Primary on a melee weapon defines the swing animation type for the primary attack button (Slash, Stab, Punch, Stomp). The naming convention reflects the different roles: guns have one Action (the firing mechanism) that applies to every shot; melee weapons have two independent action types (Action_Primary and Action_Secondary) that can be different.

Can I reuse the same AnimationClip for multiple weapons?

Yes. Multiple weapon prefabs can reference the same AnimationClip assets and the same Animator Controller. This is the standard pattern for a weapon family: a rifle, a carbine variant, and a DMR variant that share the same fire and reload animations. The clips and controller are authored once and assigned to multiple prefabs. The only constraint is that the bone hierarchy of each prefab must match the bone hierarchy the clips were authored for; if the bone names or structure differ, the clips will not animate the prefab correctly.

How do I make an animation loop seamlessly?

Three conditions must be satisfied for a seamless loop. First, the first and last frames of the AnimationClip must have the identical pose for every animated bone. Second, the Loop Pose setting must be enabled on the clip's import settings. Third, the Loop Time setting must be enabled. If all three conditions are met, Unity interpolates between the last frame and the first frame using the identical poses to produce a seamless transition. If the first and last frames are not identical, Unity blends between them, which produces a visible stutter at the loop point.

What frame rate should I use for weapon animations?

The cohort recommendation is 30 frames per second for weapon animations. This frame rate is high enough to produce smooth motion for the fast movements typical in weapon handling (slide cycling, bolt operation) and low enough to keep clip file sizes small. For animations with very fast movements (a full-auto fire cycle at high firerate), 60 frames per second provides smoother motion at the cost of larger file size.

Why does my animation play correctly in the Unity Editor but not in the compiled game?

The most common cause is that the AnimationClip was not included in the master bundle during export. Verify by checking the bundle's manifest file for the clip's asset path. If the clip is listed in the manifest but still does not play, the issue may be that the Animator Controller is not referencing the correct clip (the clip was renamed after the controller was authored). Re-assign the clip in the Animator Controller, rebuild the bundle, and re-test.

Do I need to include an Idle animation?

Yes. The Idle state is the default state of the Animator Controller and is the state the Animator enters when the weapon is equipped and no action is active. If the Idle state has no AnimationClip assigned (an empty state), the weapon will appear frozen in its bind pose when equipped. The Idle clip is typically a single-frame pose (for static idle) or a short looping clip (for animated idle with breathing motion or weapon sway).

Can I skip the Equip animation?

Yes, but it is not recommended. If no Equip state exists in the Animator Controller, the weapon appears instantly in the player's hands with no transition, which feels abrupt. A short Equip animation (0.3-0.5 seconds) provides a visual transition that makes weapon switching feel responsive and polished. The cohort recommendation is to include an Equip animation for every weapon, even if it is a minimal clip of 5-10 frames showing the weapon moving from off-screen into the ready position.

How do I test whether an animation event is firing?

The fastest way to test an animation event in development is to place a temporary Debug.Log call in the callback function on the item script. In the Unity Editor, open the script that contains the OnHit or OnFire function, add a Debug.Log("Hit event fired at frame: " + Time.frameCount); line at the top of the function, save the script, and play the animation in the Unity Editor. The Console window will show the log message at the frame when the event fires. Remove the debug log before building the final bundle for distribution.

Can I use Unity's Animator Override Controller for weapon variants?

Yes. Unity's Animator Override Controller allows a modder to create a variant of an Animator Controller where specific AnimationClip assignments are overridden. This is the recommended pattern for weapon variants that share the same state machine structure but use different animation clips. The base Animator Controller defines the states and transitions; the Override Controller points to different clips for some or all states. This reduces asset duplication and ensures that changes to the state machine structure propagate to all variants automatically.

How does the engine's item script know which trigger parameter to send?

The Unturned item scripts (UseableGun, UseableMelee) are C# scripts that ship as part of the Unturned Unity package. The scripts contain hardcoded trigger parameter names that they send to the Animator at runtime. The modder cannot change the parameter names without modifying the script source (which is not distributed in editable form). The modder must configure the Animator Controller to use the parameter names the scripts expect. The expected parameter names are documented in the parameter table in this article.

What happens if the animation clip is longer than the weapon's action duration?

Two scenarios. For melee weapons, the animation clip controls the visual duration of the swing, and the engine does not impose a maximum duration. A 3-second Slash clip will play for 3 seconds, during which the player cannot take another action. For guns, the Fire clip's duration interacts with the firerate. If the Fire clip is longer than the interval between shots (1 / firerate), the animation will not complete before the next shot fires, producing visual stutter. The fix is to shorten the Fire clip or to adjust the firerate to a value compatible with the clip duration.

How do I configure animation for a weapon that uses Action Bolt?

A weapon with Action Bolt requires the following Animator states: Idle, Fire, Bolt, Reload, Equip. The item script triggers Fire to fire a round, then Bolt to cycle the bolt, then returns to Idle. The Fire clip should be short (the hammer drop and recoil impulse). The Bolt clip should cover the bolt-handle operation: unlock, pull back, push forward, lock. The OnFire event is on the Fire clip. The OnEjectShell event is on the Bolt clip. The total cycle time (Fire duration plus Bolt duration) determines the effective firerate of the weapon.

Advanced considerations

Animation blending for aim-down-sights

The Aim animation can be implemented as a blending target rather than a discrete state transition. In this approach, a float parameter (AimWeight) is driven by the game code from 0.0 to 1.0 as the player aims down sights. The Animator Controller uses a Blend Tree instead of a discrete Aim state. The Blend Tree blends between the idle pose (weight 0.0) and the aim pose (weight 1.0) based on the AimWeight parameter. This produces a smooth transition rather than an abrupt state change. Blend Trees require Unity Animator expertise beyond the scope of a basic weapon Animator Controller but produce a more visually polished result.

Animation layers for additive effects

Unity's Animator supports animation layers that play simultaneously with different weights. A weapon could use a base layer for the primary animation states (Idle, Fire, Reload) and an additive layer for secondary motion (weapon sway while moving, breathing motion during idle, recoil recovery). Additive layers are an advanced technique that requires careful configuration to avoid conflicts with the base layer. The cohort recommendation for modders new to Unity animation is to implement all weapon motion on a single layer and to explore additive layers only after the basic state machine is working correctly.

Retargeting animations between rigs

Unity's Humanoid animation system supports retargeting: an animation authored on one Humanoid rig can be applied to a different Humanoid rig, and Unity remaps the bone names automatically. However, the Unturned character rig is not a standard Humanoid rig, and retargeting animations from a standard Humanoid rig to the Unturned rig may produce incorrect results. The cohort recommendation for mods that need animations not present in the existing Unturned animation set is to author custom animations directly on the Unturned rig (import the rig FBX into Blender, author the animation, export with the correct bone axis settings) rather than attempting to retarget from a different rig.

Animation performance on low-end hardware

Weapon animation clips are small assets that have minimal performance impact, even on low-end hardware. A typical weapon animation clip is under 100 KB of compressed keyframe data. The Animator component on the weapon prefab runs on the GPU for skinned mesh rendering (if the weapon has an animated mesh) and on the CPU for bone transform calculation. The CPU cost of a weapon Animator is negligible relative to the rest of Unturned's game loop. Animation performance is not a bottleneck for weapon and melee mods, regardless of the target hardware.

Authoring reload animations for different magazine types

A weapon that supports multiple magazine types (standard box, extended, drum) may need distinct reload animations for each type. The standard box magazine reload shows a compact magazine being inserted; the drum magazine reload shows a larger, bulkier magazine requiring a different hand position. The engine does not natively support per-magazine-type animation selection; the modder must implement magazine-dependent animation switching through a custom script or by providing a single reload animation that is visually compatible with all magazine types. The cohort recommendation is to author the reload animation with the largest magazine type in mind (the drum) and to accept that smaller magazine types will appear to use the same motion, which is a minor visual concession.

Appendix A: Animation state quick reference for gun items

State	Trigger parameter	Clip loops?	Required?	Event functions
Idle	, (default)	Yes	Yes	,
Fire	fire	No	Yes	OnFire, OnEjectShell
Reload	reload	No	Yes	OnReloadComplete
Equip	equip	No	Recommended	,
Bolt	bolt	No	If Action Bolt	OnBoltCycle
Pump	pump	No	If Action Pump	,
Break	break	No	If Action Break	,
Aim	aim	No	Optional	,
Inspect	inspect	No	Optional	,
Jam	jam	No	Optional	,

Appendix B: Animation state quick reference for melee items

State	Trigger parameter	Clip loops?	Required?	Event functions
Idle	, (default)	Yes	Yes	,
Slash	primary or secondary	No	If Action_Primary Slash or Action_Secondary Slash	OnHit
Stab	primary or secondary	No	If Action_Primary Stab or Action_Secondary Stab	OnHit
Punch	primary or secondary	No	If Action_Primary Punch or Action_Secondary Punch	OnHit
Stomp	primary or secondary	No	If Action_Primary Stomp or Action_Secondary Stomp	OnHit
Inspect	inspect	No	Optional	,

Appendix C: Animation clip import settings quick reference

Setting	Idle clip	All other clips
Loop Time	Enabled	Disabled
Loop Pose	Enabled	Disabled
Cycle Offset	0	0
Root Transform Rotation	Bake into Pose	Bake into Pose
Root Transform Position (Y)	Bake into Pose	Bake into Pose
Root Transform Position (XZ)	Bake into Pose	Bake into Pose
Mirror	Disabled	Disabled
Anim. Compression	Optimal	Optimal (Off for precise timing)

Appendix D: FBX export settings for Unturned rig animations

Setting	Value
Scene unit system	Metric
Unit scale	1.0
Length	Meters
Selected Objects	True
Apply Scale	FBX Units Scale
Add Leaf Bones	False
Primary Bone Axis	+X
Secondary Bone Axis	-Y
Forward	-Z Forward
Up	Y Up

Appendix E: External references

• Smartly Dressed Games modding documentation, the official field reference and animation export settings for Unturned.
• Unturned on Steam, the Unturned™ store page and community hub.
• Animations Export Blender to Unity, the companion article covering the complete Blender-to-Unity animation pipeline: bone naming, armature setup, FBX export, Unity rig configuration, Animator Controller creation, and animation event placement.
• Asset Bundles Reference, the article covering the master bundle system into which animated prefabs are packaged.
• Master Bundle Export, the Unity bundling workflow for exporting animated prefabs.
• Melee Asset, the melee weapon .dat field reference; documents Action_Primary and Action_Secondary.
• Gun Mod Tutorial, the gun .dat field reference; documents the Action field and fire mechanics.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete animation asset reference: animation types by item category, AnimationClip import and configuration, Animator Controller state machines, animation events, .dat field cross-reference, FBX export settings, worked examples, diagnostic tables, retargeting and performance considerations.

Authoring checklist

Before publishing a mod that includes custom animations, confirm the following:

• [ ] The Animator Controller has a state for every action type declared in the item's .dat file
• [ ] The Idle state is set as the default state
• [ ] Loop Time and Loop Pose are enabled on the Idle clip and disabled on all other clips
• [ ] Animation events are placed at the correct frames on the Fire, Slash, Stab, and other hit-frame clips
• [ ] Trigger parameter names in the Animator Controller match the names the item scripts send (all lowercase convention)
• [ ] The FBX export used Primary Bone Axis +X and Secondary Bone Axis -Y for Unturned rig animations
• [ ] Add Leaf Bones was disabled in the Blender FBX export settings
• [ ] The Animator component on the prefab references the correct Animator Controller
• [ ] All animation clips are included in the master bundle (verify in the bundle manifest)
• [ ] Every animation state has been tested in a local single-player session before Workshop submission

Cross-references

• Asset Bundle Custom Data, the previous article in this section; covers bundle-level custom metadata.
• Animations Export Blender to Unity, the complete Blender-to-Unity animation pipeline.
• Melee Asset, the melee weapon .dat field reference with Action_Primary, Action_Secondary, and prefab animation configuration.
• Asset Bundles Reference, the master bundle system into which animations are packaged.
• Master Bundle Export, the Unity bundling workflow for exporting animations.
• Project Folder Structure and GUIDs, GUID conventions for the Unity project containing animation assets.
• Smartly Dressed Games modding documentation, official reference for animation export settings.
• Unturned on Steam, game page and community.