Animation Events for Weapons

Intermediate40-60 minutesCross-platformUnturned Server

Animation events are the mechanism by which Unturned™ translates a playing animation clip into live gameplay actions — spawning a projectile, chambering a round, detaching a magazine model, toggling a laser. Every time a weapon fires, reloads, or transitions into an aim state, a chain of Unity Animator events coordinates the visual and the mechanical. Understanding exactly how that chain works — which event names Unturned recognizes, where in the clip each event must be placed, and how the UseableGun script responds — is the foundation for shipping a weapon mod that feels correct in play rather than merely functional in the Inspector.

This article documents the complete animation event system for Unturned™ weapons, as understood and validated by the 57 Studios™ cohort. It is directed at modders who have already built a working weapon prefab and Animator Controller (see the prerequisite Gun Mod Tutorial and Animations Export Blender to Unity). The focus here is the event layer: the named hooks that live inside animation clips, the frames at which they fire, and the UseableGun method each hook invokes.

Prerequisites

• Unity 2022.3 LTS with a working weapon prefab.
• A configured Animator Controller with at minimum Idle, Fire, and Reload states.
• Familiarity with the animation pipeline. See Animations Export Blender to Unity.
• Familiarity with the gun prefab structure. See Gun Mod Tutorial.
• Approximately 30–90 minutes per weapon for initial event placement and testing.

What you will learn

• How Unturned's UseableGun script listens for Unity Animator events.
• The complete list of reserved event names and what each one triggers in the game runtime.
• The correct frame-position for each event within each animation clip.
• How to place animation events in the Unity Animator window.
• How the fire sequence — input, event, projectile spawn — flows from player input to bullet in the world.
• The full reload sequence from Reload_Start through Reload_Loop to Reload_End.
• How aim and toggle events are consumed.
• A diagnostic procedure for events that fire at the wrong time or not at all.
• Animation clip authoring recommendations that make event placement consistent across weapons.
• Performance characteristics of event-driven particle and object spawning.
• Version compatibility notes for modders working with older content or updating older mods.

How this article fits in the modding pipeline

Animation events are one step in a broader weapon modding pipeline. The table below shows where event placement sits relative to the other major steps.

Step	What happens	Covered in
1. Model in Blender	Weapon mesh, UV, rig, animations authored	Animations Export Blender to Unity
2. Export FBX	Rigged animated weapon exported to FBX	Gun Mod Tutorial
3. Import to Unity	FBX imported, rig configured as Generic	Gun Mod Tutorial
4. Build Animator Controller	States, transitions, parameters configured	Gun Mod Tutorial
5. Extract clips to .anim files	Clips separated from FBX for stable editing	Animations Export Blender to Unity
6. Place animation events	Fire, Reload, Aim, Toggle events placed on clips	This article
7. Build prefab	Prefab assembled with hook points and colliders	Gun Mod Tutorial
8. Package master bundle	Prefab packaged into .unity3d	Master Bundle Export
9. Author .dat file	Parameter set authored in Notepad++	Gun Mod Tutorial
10. Test and publish	In-game testing, Workshop submission	Steam Workshop Submission

Step 6 — Place animation events — is what this article covers. Steps 1–5 are prerequisites; steps 7–10 follow after the events are correctly placed and verified.

Background: how Unturned hooks Unity Animator events

Unity's animation event system allows a float, integer, string, or Object parameter to be attached to a specific frame of an animation clip. When the Animator plays that frame, Unity calls the named method on every MonoBehaviour component attached to the same GameObject as the Animator.

In Unturned™ weapon prefabs, the UseableGun script is attached to the prefab root, which is the same GameObject that holds the Animator component. When a named event fires from within a clip, Unity resolves the method name against the UseableGun component. If the method exists and the name matches exactly — case-sensitive — the method runs. If it does not match, Unity logs a warning and the gameplay action is skipped.

This means animation event names in Unturned are a fixed vocabulary, not a configurable parameter. They are not listed in the .dat file; they are hardcoded method handlers inside UseableGun. The only configuration the modder controls is the frame position of each event within each clip.

Case-sensitive exact match

Event names are matched case-sensitively. fire does not invoke the same method as Fire. reload_start does not invoke the same method as Reload_Start. Use the exact casing shown in the Reserved Event Names section below, character for character. A single wrong-case character silently skips the gameplay action.

The event resolution chain

The sequence above is the complete fire event chain. The key insight is the asymmetry of timing: UseableGun sets the fire trigger on the Animator immediately when the player presses the fire input, but the projectile does not spawn until the Fire animation event fires at its placed frame inside the clip. The delay between trigger and projectile is entirely controlled by the frame position of the Fire event.

Why the delay matters

A Fire event placed at frame 0 spawns the projectile immediately, before the slide has moved or the muzzle has flashed visually. A Fire event placed at frame 4 of a 10-frame clip gives the visual time to catch up — the slide begins to move, the muzzle starts to flash, and then the projectile arrives in the world. The cohort's validated position is frame 2–3 of a 10-frame Fire clip. Placing the event earlier than frame 2 makes the projectile feel ahead of the animation; later than frame 4 makes it feel sluggish.

Reserved event names

The following table documents every Unturned™ animation event name recognized by UseableGun. No other event names trigger gameplay actions; non-recognized names generate a Unity console warning and are ignored.

Event name	Clip(s)	Purpose
Fire	Fire	Spawns the projectile at the MuzzleFlash GameObject position. Decrements magazine count. Applies recoil and shake. Plays gunshot audio.
Reload_Start	Reload	Marks the beginning of the reload sequence. UseableGun begins accepting reload-state input.
Reload_Loop	Reload	For pump-action and bolt-action weapons: marks one completed cycle of the reload loop. Used when the Reload clip loops for each round loaded individually. For standard magazine-fed weapons, Reload_Loop is not required.
Reload_End	Reload	Marks the completion of the reload. UseableGun finalizes the magazine state: the weapon is now loaded, round count is restored, the magazine model re-attaches.
Aim_Start	Aim	Marks the point at which the camera transitions to the aim-down-sights (ADS) position. UseableGun locks the player view to the Sight_Iron bone world position.
Aim_End	Aim out / Idle	Marks the point at which the camera returns from ADS to the hip position. UseableGun releases the ADS lock and restores hip spread.
Toggle_Light	(any)	Toggles the light attachment's illuminated state. Fires when the player presses the light-toggle key and the Animator reaches the event frame.
Toggle_Laser	(any)	Toggles the laser attachment's visible beam state. Same timing logic as Toggle_Light.
Eject_Shell	Fire	Spawns the shell ejection particle/object at the EjectionPort GameObject position. For semi-auto and auto weapons, placed 1–2 frames after the Fire event.

Eject_Shell is separate from Fire

The Eject_Shell event spawns the visual shell casing separately from the Fire event. This separation exists so the visual shell ejection can be timed to match the slide's open position, which is typically 1–3 frames after the projectile fires. For bolt-action rifles and pump shotguns that have a visible ejection animation, Eject_Shell is placed at the frame when the bolt is fully retracted.

Optional system-level events

Beyond the nine primary reserved event names, Unturned™ respects two additional optional event names for cosmetic behaviors that do not affect gameplay mechanics:

Event name	Clip	Purpose
Inspect	Inspect (optional)	Called when the inspect animation clip plays. Triggers a subtle sound cue if one is configured. Does not affect gameplay state.
Sprint_Stop	Sprint (optional)	Called when the sprint animation is about to return to idle. Signals UseableGun to finalize the sprint state transition. Only relevant if the weapon has a dedicated sprint animation.

These events are optional in the strictest sense — omitting them does not prevent the weapon from functioning. However, including Inspect on an inspect clip creates a more polished audio-visual experience for players who use the inspect key. The cohort recommendation for first-time weapon mods is to defer inspect and sprint animation authoring until after the core fire and reload pipeline is working cleanly.

Events that are not required

Not every event must be present in every weapon. The minimum required set for a functional weapon is:

Weapon type	Required events
Semi-auto pistol / rifle	Fire, Reload_Start, Reload_End
Full-auto rifle	Fire, Reload_Start, Reload_End
Bolt-action rifle	Fire, Eject_Shell, Reload_Start, Reload_Loop, Reload_End
Pump-action shotgun	Fire, Eject_Shell, Reload_Start, Reload_Loop, Reload_End
ADS weapon (scope / iron sight)	Fire, Reload_Start, Reload_End, Aim_Start, Aim_End
Weapon with light / laser attachment	All of the above plus Toggle_Light and/or Toggle_Laser

If the weapon uses Unturned's default hip-fire behavior and does not have a dedicated aim animation, Aim_Start and Aim_End do not need to be present. The ADS transition will use a default snap behavior. The cohort recommendation is to include Aim_Start and Aim_End for any weapon with a scope or iron-sight alignment bone.

Frame placement reference

The frame numbers below assume a 30 fps clip speed — the standard for Unturned™ weapon clips. If a clip was authored at a different frame rate, scale these positions proportionally.

Fire clip event placement

The table below maps the visual phases of a 10-frame semi-auto fire clip to the events that belong at each position. This is the cohort's reference structure for authoring fire clips that align visually with their events.

Frame range	Visual phase	Event at this frame
0–1	Trigger depresses; slide begins rearward travel	—
2	Slide at approximately 20% retraction; muzzle visually open	Fire
3–4	Slide approaching full retraction	Eject_Shell at frame 4
5	Slide at full retraction; ejection port fully open	—
6–10	Slide returns forward; trigger resets	—

Event	Recommended frame	Acceptable range	Notes
Fire	Frame 2	Frames 1–4	Before the visual slide reaches full retraction. Projectile exits muzzle as slide starts to move.
Eject_Shell	Frame 4	Frames 3–6	When the slide/bolt is near full retraction, shell exits the ejection port visually.

Do not place Fire at frame 0

Frame 0 is the first frame of the clip. If Fire is placed at frame 0, the projectile spawns before any visual change is visible — the gun appears to fire before it animates. The minimum recommended position is frame 1, and the cohort-validated position is frame 2.

Reload clip event placement

The reload clip is typically the longest clip in the set, often 60–90 frames for a standard magazine swap. The three events mark the beginning of the reload window, the middle loop point (for individual-round weapons), and the end of the reload. The frame breakdown below is for a 75-frame clip — the cohort's standard for a magazine-fed rifle.

Frame range	Visual phase	Event at this frame
0–4	Magazine begins to drop from the weapon	—
5	Magazine body separating visibly	Reload_Start
6–44	Magazine out; weapon empty; player reaching for new magazine	—
45–67	New magazine inserted, hand seats it	—
68	Magazine fully seated; chamber round animation complete	Reload_End
69–75	Settling animation; weapon returns to ready position	—

Event	Recommended frame	Notes
Reload_Start	Frame 4–6	Immediately after the magazine drop begins. The reload window is now open.
Reload_Loop	Per round	Bolt-action / pump only. Placed once per chambered round in the loop section of the clip.
Reload_End	Frame 65–70	After the new magazine is visually seated and the chamber round animation is complete.

Reload_End timing is critical

If Reload_End fires before the magazine insert animation completes visually, the gun will function correctly mechanically — the round count is restored — but the visual will show the reload finishing after the gun is already usable. This creates a perceived desync where the player can fire before the animation appears to finish. Place Reload_End 2–3 frames before the final visual pose, not at the frame the animation visually completes.

Aim clip event placement

The aim clip is the transition animation from hip to ADS. Aim_Start marks when the camera begins locking to the sight position. Aim_End marks when the camera releases (used in the aim-out clip, if one exists, or at the end of the reverse-played aim clip).

Event	Clip	Recommended frame	Notes
Aim_Start	Aim (in)	Frame 4–6	Partway through the transition, after the weapon has visibly moved toward the face. Not at frame 0, or the camera snaps before the weapon moves.
Aim_End	Aim (out)	Frame 4–6 of the out clip	Partway through the return transition. Camera releases before the weapon fully returns to hip.

How to place events in the Unity Animator window

Placing animation events in Unity requires using the Animation window (not the Animator window). The Animation window exposes the clip timeline where events can be dragged into position.

Step-by-step event placement

1. Open the Animation window. Window → Animation → Animation (Ctrl+6 shortcut).
2. Select the prefab in the Hierarchy. The Animation window must show the correct clip.
3. Select the clip to edit. Use the clip dropdown at the top of the Animation window to select the Fire clip, Reload clip, or whichever clip needs events.
4. Navigate to the target frame. Drag the playhead to the target frame, or type the frame number into the frame field.
5. Add the event. Click the Add Event button (the small diamond-with-plus icon in the timeline toolbar). An event marker appears at the current frame.
6. Set the function name. In the Inspector (the event properties panel that appears when the event marker is selected), enter the exact function name in the Function field. For the fire event, enter Fire. For reload start, enter Reload_Start.
7. Verify the frame number. Confirm the event marker is at the intended frame. The frame number is shown in the Inspector's Time field (in seconds) and in the timeline position.
8. Repeat for each event. Add Eject_Shell to the Fire clip, then add Reload_Start and Reload_End to the Reload clip.
9. Save. Ctrl+S saves the clip modifications. If the clip is part of an imported FBX, the event data is saved in a .meta file override.

Events on imported FBX clips vs. standalone clips

If the animation clips live inside an imported FBX asset, Unity stores event modifications in the FBX's .meta file, not in the clip itself. Re-importing the FBX without preserving the .meta file will destroy all event placements. The cohort recommendation is to extract animation clips from the FBX into standalone .anim files after import, then place events on the extracted clips. Events on standalone .anim files are persistent across FBX re-imports.

Extracting clips from FBX (recommended workflow)

1. Select the FBX in the Project window.
2. Inspector → Animation tab → locate the clip list.
3. For each clip, click the clip name and then Ctrl+D to duplicate it to a standalone .anim file.
4. Move the extracted .anim files into the weapon's folder.
5. Open the Animator Controller and replace the FBX clip references with the extracted .anim file references.
6. Place events on the extracted .anim files.

This workflow insulates the event placements from FBX re-imports and makes it possible to adjust events without touching the source mesh or rig.

The complete fire sequence

The fire sequence involves the largest number of interacting systems of any weapon event. The diagram below traces the full path from player input to bullet in the world.

Server-side validation

The projectile does not travel from the client directly to the target. After the Fire event fires on the client, UseableGun sends the origin position and direction vector to the Unturned™ server. The server performs the hit calculation and applies damage authoritatively. This means the visual muzzle flash and the actual hit detection are slightly decoupled on high-latency connections, which is normal Unturned behavior and not a modding concern.

The complete reload sequence

The reload sequence is more complex than the fire sequence because it spans a longer clip and has a defined window during which the reload can be interrupted.

Bolt-action and pump-action reload loops

Bolt-action rifles and pump-action shotguns load rounds individually rather than as a magazine swap. The Reload clip for these weapons loops for each round loaded, and Reload_Loop marks the end of one loading cycle.

Pump-action interrupt behavior

Unturned™ allows pump-action and bolt-action reloads to be interrupted by pressing the fire button. When the player fires mid-reload, the Animator transitions to the Fire state before Reload_End has fired. UseableGun saves the current mid-reload round count so that when the player presses reload again, the clip resumes from where the count left off. This behavior is built into UseableGun and does not require any event configuration from the modder.

The aim sequence

The aim sequence is simpler than fire or reload. Aim_Start and Aim_End are the only two events, and they control the camera-lock timing.

The aim state flow is: Hip → AimTransition (player holds aim key) → Aim_Start fires → ADS state active. On releasing aim: ADS → AimOutTransition → Aim_End fires → Hip restored. Firing while in ADS: the Animator plays the Fire clip and returns to ADS when the clip exits; the camera stays locked to the sight position throughout the Fire clip. Aim_Start and Aim_End do not interrupt fire.

The four states and their transitions:

From state	Input	Transition	To state	Event during transition
Hip	Hold aim key	Aim in	ADS	Aim_Start at frame 4–6
ADS	Release aim key	Aim out	Hip	Aim_End at frame 4–6
ADS	Press fire	Fire	ADS (returns)	Fire at frame 2–4
Hip	Press fire	Fire	Hip (returns)	Fire at frame 2–4

Common pitfalls and how to diagnose them

The table below lists the most frequently reported animation event problems, their root causes, and the resolution for each.

Symptom	Root cause	Resolution
Projectile fires but no muzzle flash	Fire event placed correctly, but MuzzleFlash GameObject missing from prefab	Add a MuzzleFlash empty GameObject as a child of the prefab root at the muzzle position
Shell casing spawns at the wrong position	Eject_Shell event placed on the wrong clip, or EjectionPort GameObject mispositioned	Confirm EjectionPort is a child of the prefab root; reposition to the ejection port of the weapon mesh
Weapon fires but no audio	Fire event invokes audio, but Shoot field in .dat is not a recognized category	Use a recognized Shoot category (Heavy_Rifle, Light_Rifle, Pistol, Shotgun) or see audio packaging docs
Reload animation plays but round count does not restore	Reload_End event missing or name typo	Open the Reload clip in the Animation window; confirm event at the correct frame with exact name Reload_End
Round count restores before reload animation finishes	Reload_End placed too early in the clip	Move Reload_End to frame 65–70 of a 75-frame clip; keep at least 5 frames after the event for settle animation
Magazine model stays attached during reload	Reload_Start missing or the magazine GameObject is not wired to the Animator	Confirm Reload_Start is placed; confirm the magazine sub-mesh is under the Animator's control in the prefab hierarchy
ADS camera snaps instantly rather than transitioning	Aim_Start placed at frame 0	Move Aim_Start to frame 4–6 so the weapon visually moves toward the face before the camera locks
ADS camera stays locked after releasing aim	Aim_End missing from the aim-out clip	Add Aim_End to the aim-out transition clip; if there is no dedicated aim-out clip, reverse-play the aim clip and place Aim_End at the equivalent position
Light attachment toggle does not respond	Toggle_Light event placed on a clip that does not play when the toggle key is pressed	Confirm the Animator has a state and transition for the light toggle; Toggle_Light must be on a clip that the Animator plays in response to the toggle trigger
Laser beam does not appear or disappear	Same as Toggle_Light root cause	Same resolution as above, for Toggle_Laser
Bolt-action loads only one round instead of N	Reload_Loop missing	Add Reload_Loop at the end of each single-round load cycle in the Reload clip
Unity console warns "No receiver for message Fire"	UseableGun script not attached to the same GameObject as the Animator	Confirm the prefab root (not a child object) holds both the Animator component and the UseableGun script
Event fires twice per shot	Clip transitions into itself (loop enabled on Fire clip)	Open the Fire clip import settings; confirm Loop Time is disabled
Event fires at the wrong game action (fire instead of reload)	Event placed on the wrong clip	Open each clip individually in the Animation window and verify which events are present on which clip

Unity console warnings indicate missing event receivers

If the Unity or Unturned™ console outputs a message like No receiver for message 'Fire' or Animation event 'Reload_Start' could not be dispatched, this indicates that the event name does not match any method on the UseableGun script. Check the spelling and casing of the event name precisely. This warning is the single most reliable diagnostic signal for event name errors.

Diagnostic procedure for events that do not fire

When an animation event appears correctly placed in the Animation window but does not produce the expected gameplay result, follow this diagnostic procedure in order.

Test with a simple scene first

Before diagnosing a complex weapon prefab, place a test cube in a new scene with a simple two-frame animation clip, an animation event at frame 1, and a test MonoBehaviour with a matching method name. Confirm that event dispatch works in a clean scene. If the event works in the clean scene, the problem is prefab-specific, not a Unity installation issue.

Working with multiple weapons in the same project

A weapon mod that ships one firearm can treat event placement as a one-time task. A weapon mod that ships five or more firearms — a common scope for a 57 Studios™ content pack — needs a consistent event placement workflow across all weapons to avoid divergence. When event positions vary by weapon without an intentional design reason, the play feel becomes inconsistent: one rifle fires on frame 2, another on frame 4, and players notice the difference even if they cannot articulate it.

Establishing a base event template

The cohort's recommendation for multi-weapon packs is to author one "template weapon" — typically the first rifle or pistol shipped — with fully verified event positions. Document those positions in a plain-text event log kept alongside the mod's .dat files. The format the cohort uses:

# Event log — [ModName] weapon pack
# Updated: [date]

## Template weapon: MK1 Rifle
Fire clip (10f): Fire @ f2, Eject_Shell @ f4
Reload clip (75f): Reload_Start @ f5, Reload_End @ f68
Aim clip (10f): Aim_Start @ f5
Aim-out clip (10f): Aim_End @ f5

## Variant: MK2 Pistol
Fire clip (8f): Fire @ f2, Eject_Shell @ f3
Reload clip (60f): Reload_Start @ f4, Reload_End @ f55
Aim clip (10f): Aim_Start @ f5
Aim-out clip (10f): Aim_End @ f5

This log is low-maintenance and high-value. When a new weapon joins the pack, the modder copies the nearest existing entry, adjusts the frame counts to match the new clip length, and has a starting reference for event placement.

Animator Override Controllers for shared base clips

If multiple weapons in a pack share the same fire animation (e.g., all pistols in the pack use the same slide-retraction animation), Unity's Animator Override Controller allows those weapons to share the same Animator Controller while substituting their own clip references. Events placed on the base clips apply to all override controllers automatically. This means event placement for the base fire clip applies to every pistol in the pack without re-placing events weapon by weapon.

The workflow:

1. Author the base Animator Controller with events placed on the base fire and reload clips.
2. For each weapon variant, create an Animator Override Controller (right-click → Create → Animator Override Controller in the Project window).
3. Set the Controller field of the Override Controller to the base Animator Controller.
4. Override only the clips that differ for this weapon (e.g., a different idle animation or different reload clip).
5. Assign the Override Controller to the weapon's Animator component.

Weapons that share clip content through Override Controllers inherit the base controller's event placements. Only weapons that override a clip need to re-place events on their custom version of that clip.

When to deviate from the template positions

Deviating from the template event positions is appropriate when the weapon's animation is authored with a meaningfully different visual timing. A bolt-action rifle with a slower bolt cycle needs Eject_Shell at a later frame than a semi-auto pistol. A full-auto SMG with a 4-frame fire clip needs Fire at frame 1. The template is a starting point, not a constraint. Document the deviation and the reason in the event log so future sessions do not re-investigate the intentional difference.

Cross-references

• Gun Mod Tutorial — the end-to-end weapon prefab and .dat workflow; the prerequisite for this article.
• Animations Export Blender to Unity — the animation clip pipeline from Blender to Unity; covers how to extract animation clips from FBX and how to configure loop settings.
• Custom NPCs, Dialogues, and Quests — the previous article in the server-config section.
• Smartly Dressed Games Modding Documentation — the official Unturned modding reference; check the latest version for any changes to UseableGun event names or behavior.
• Unturned on Steam — the game's Steam page; version notes sometimes document behavioral changes to the weapon system.

Frequently asked questions

What happens if I do not place any animation events on my weapon?

If no animation events are placed, the weapon will fire visually (the Animator plays the Fire clip) but no projectile spawns, no round count decrements, and no audio plays. The weapon will appear to animate but will have no gameplay effect. Reload_Start and Reload_End are similarly required for the reload action to change the round count. A weapon with no events is not playable.

Can I place more than one Fire event in a single Fire clip?

Yes, but doing so causes multiple projectiles to spawn per animation play. This is the intended behavior for burst-fire or multi-pellet weapons where the Reload clip loops. For standard semi-auto or full-auto weapons, only one Fire event per Fire clip play is correct.

Does Unturned support custom event names beyond the reserved list?

No. The UseableGun script only responds to the reserved event names listed in this article. Custom event names — names not in the reserved list — are dispatched by Unity but produce a "No receiver" console warning and have no gameplay effect. Custom event handling would require modifying UseableGun source code, which is outside the scope of standard Unturned™ modding.

My weapon is a semi-auto pistol. Do I need Aim_Start and Aim_End?

Only if the weapon has a dedicated aim transition animation. If there is no Aim clip in the Animator Controller, Aim_Start and Aim_End are not needed. Unturned™ will use a default snap-to-ADS behavior. The cohort recommendation is to include aim events any time there is an aim transition animation, because the default snap behavior feels abrupt compared to a smoothly timed Aim_Start.

Where exactly is the MuzzleFlash position read from?

The Fire event spawns the muzzle flash particle at the world position of the MuzzleFlash empty GameObject in the prefab hierarchy at the moment the event fires. The GameObject's local position (relative to the prefab root) determines where the flash appears. If the prefab is moving (as it does when the weapon model sways during idle), the muzzle flash position moves with the prefab. The cohort recommendation is to keep MuzzleFlash as a direct child of the prefab root and to position it at the muzzle exit of the weapon model.

My animation events are placed but they only fire sometimes. What causes intermittent event dispatch?

Intermittent dispatch is almost always caused by Animator transitions with exit time set too short. If the Fire clip exits before the Fire event frame is reached, the event is never dispatched. Open the Animator Controller, select the transition from the Fire state to its exit state, and confirm that Exit Time is either disabled or set to a value (normalized time) that is after the event frame. For a 10-frame clip with a Fire event at frame 2, the exit time normalized value should be at least 0.20 (frame 2 / 10 frames).

How do I test animation events without entering a full Unturned game session?

The Unity Editor's Animation window includes a preview mode that plays the selected clip. However, animation events only dispatch to live MonoBehaviour instances, which means they only fire in Play mode. To test events quickly, use Unity's Play mode with the prefab placed in a test scene. Add a simple MonoBehaviour to the prefab with public methods matching the event names, each printing a Debug.Log message. Confirm the log prints at the expected frame during play. This is faster than testing in-game for each placement iteration.

Does the Reload_Loop event affect the round count once per firing or once per event dispatch?

Once per event dispatch. Each dispatch of Reload_Loop increments the round count by one. For a bolt-action rifle with a 5-round internal magazine, the Reload clip should have the load-one-round animation looping with Reload_Loop at the end of each loop, and the Animator should loop the clip state until the round count reaches the maximum or the player interrupts. UseableGun tracks the target count and stops accepting Reload_Loop events when the maximum is reached.

What is the correct Animator parameter type for the fire and reload triggers?

Both fire and reload should be Trigger type parameters in the Animator Controller, not Bool. Triggers self-reset after the transition they caused completes. If they were Bool, the Animator would require the modder to manually reset the Bool after each transition, which creates edge cases when the animation is interrupted. The aim parameter is a Bool because it represents a sustained state (the player holds the aim button), not a momentary event.

My weapon's Fire event fires correctly in single-player but not on a dedicated server. Why?

Animation events run on the local client only. The Fire event's effect (projectile spawn) is propagated to the server via network messages that UseableGun sends when the event fires. If the event fires on the client but the server does not register the shot, the problem is a network replication issue, not an event placement issue. Confirm the server is running the same mod version as the client, and that the mod's bundle is correctly loaded on the server.

Can Aim_Start and Aim_End appear on the same clip?

Yes, if the weapon uses a single looping aim clip rather than a separate aim-in and aim-out clip. Place Aim_Start at the frame where the weapon reaches the ADS position (near the beginning of the loop) and Aim_End at the frame where the weapon begins returning to hip (near the end of the loop or in a second clip). The cohort's recommended approach is to have a dedicated aim-in clip (containing Aim_Start) and a dedicated aim-out clip (containing Aim_End) to give finer control over the transition timing.

How do I verify which events are on which clip without opening each clip individually?

Unity does not provide a cross-clip event summary in the default UI. The fastest approach is to use a simple Editor script that iterates over all AnimationClip assets in a folder and prints each clip's event names and frame positions to the Unity console. The 57 Studios™ cohort maintains a utility script for this purpose — see the cohort tool repository. For a manual verification pass without scripting: open the Animation window, select the prefab, then use the clip dropdown to cycle through each clip in turn and scan the timeline for event markers (the small diamond icons above the timeline ruler).

Appendix A — Reserved event name quick reference

Event name	Clip	Required for	Frame guidance
Fire	Fire	All weapons	Frame 2–4 of a 10-frame clip
Eject_Shell	Fire	Weapons with visible ejection	Frame 4–6, after Fire
Reload_Start	Reload	All weapons	Frame 4–6, early in clip
Reload_Loop	Reload	Bolt-action, pump-action	End of each single-round load cycle
Reload_End	Reload	All weapons	Frame 65–70 of a 75-frame clip
Aim_Start	Aim (in)	Weapons with ADS animation	Frame 4–6 of aim-in clip
Aim_End	Aim (out)	Weapons with ADS animation	Frame 4–6 of aim-out clip
Toggle_Light	Light toggle	Weapons with light attachment	Frame 2–4 of toggle clip
Toggle_Laser	Laser toggle	Weapons with laser attachment	Frame 2–4 of toggle clip

Appendix B — Animator Controller parameter reference

The Animator Controller for a standard Unturned™ weapon uses the following parameters. These are set by UseableGun at runtime and must match these exact names and types; incorrect names or types cause silent behavior failures.

Parameter name	Type	Set by	Purpose
fire	Trigger	UseableGun on fire input	Transitions Idle / Aim → Fire state
reload	Trigger	UseableGun on reload input	Transitions Idle / Aim → Reload state
aim	Bool	UseableGun on aim input hold/release	Transitions between Hip and ADS states
inspect	Trigger	UseableGun on inspect input	Transitions Idle → Inspect state (optional)
sprint	Bool	UseableGun when player sprints	Transitions Idle → Sprint state (optional)

Parameter names are also case-sensitive

Fire (capital F) as a parameter name is not the same as fire (lowercase f). The Animator Controller parameters that UseableGun sets are lowercase: fire, reload, aim. The animation event function names are PascalCase: Fire, Reload_Start, Reload_End. Do not confuse the two; they operate at different levels of the system.

Appendix C — Event placement checklist

Use this checklist before testing a weapon in-game. A weapon that passes all checks is expected to dispatch events correctly.

Fire clip

• [ ] Fire event is present on the Fire clip (not the Reload or Idle clip).
• [ ] Fire event name is spelled exactly Fire — capital F, no trailing space, no underscore.
• [ ] Fire event is at frame 2–4 (not frame 0).
• [ ] Eject_Shell event is present if the weapon has a visible ejection port.
• [ ] Eject_Shell is 1–3 frames after Fire.
• [ ] Loop Time is disabled on the Fire clip.
• [ ] The Animator transition from Fire to Idle has an Exit Time that is after the Fire event frame.

Reload clip

• [ ] Reload_Start event is present on the Reload clip.
• [ ] Reload_Start is at frame 4–6.
• [ ] Reload_End event is present on the Reload clip.
• [ ] Reload_End is at frame 65–70 of a 75-frame clip (or the equivalent position for different-length clips).
• [ ] Reload_Loop is present if the weapon is bolt-action or pump-action.
• [ ] Loop Time is disabled on the Reload clip (unless it is a single-round loop weapon, in which case the loop section of the clip loops, not the full clip).

Aim clips

• [ ] Aim_Start is present on the aim-in clip at frame 4–6.
• [ ] Aim_End is present on the aim-out clip at frame 4–6.
• [ ] aim parameter in the Animator Controller is type Bool, not Trigger.

Toggle clips (if applicable)

• [ ] Toggle_Light is present on the light-toggle clip if the weapon supports a light attachment.
• [ ] Toggle_Laser is present on the laser-toggle clip if the weapon supports a laser attachment.

Prefab structure

• [ ] UseableGun script is attached to the prefab root GameObject — the same GameObject that holds the Animator component.
• [ ] MuzzleFlash empty GameObject is a child of the prefab root and is positioned at the barrel exit.
• [ ] EjectionPort empty GameObject is a child of the prefab root and is positioned at the ejection port.

Run the checklist on every weapon, including experienced modders

The cohort's instrumentation shows that animation event errors are the second most common cause of weapon mod test failures, after caliber mismatches. Experienced modders skip the checklist less often because they have seen how subtle event errors can be — an event at frame 0 instead of frame 2 is invisible in the Inspector but obvious when the weapon fires before it animates in-game.

Animation clip authoring recommendations for event compatibility

Animation events do not exist in a vacuum — they are tightly coupled to the visual timing of the animation clip they live in. A Fire event placed at frame 2 of a 10-frame clip assumes that the clip's visual content is authored so that the muzzle flash, slide start, and trigger break are all visible at or before frame 2. If the animator authored the fire clip with the muzzle flash beginning at frame 5, placing Fire at frame 2 will still spawn the projectile, but it will appear before the visual muzzle flash — a noticeable desync that breaks immersion.

This section documents the cohort's animation authoring recommendations, developed specifically to make event placement natural and correct.

Fire clip authoring

The cohort's validated structure for a 10-frame semi-auto fire clip is:

Frame range	Visual content	Event present?
0–1	Trigger depresses, slide begins rearward travel	None
2	Slide reaches approximately 20% of travel; muzzle flash particle position reached	Fire, Eject_Shell offset starts
3–5	Slide at full retraction; ejection port open	Eject_Shell at frame 4
6–9	Slide returns forward; trigger returns to rest	None
10	Clip end, return to idle	None

The key authoring principle is that the Fire event at frame 2 must coincide with the frame at which the muzzle is visually "open" — the slide has begun moving and the visual expectation of a shot is already established, but the animation has not completed the full retraction. This creates a tight perceptual coupling between the visual and the mechanical.

Author the animation to fit the event, not the event to fit the animation

When authoring a fire clip from scratch, plan the frame ranges for each visual phase before animating. If the event is supposed to fire at frame 2, make sure the muzzle-flash visual phase starts at frame 1 and the projectile spawn at frame 2 is visually coherent. Changing event positions after the fact is possible, but it is faster to author the clip to support the target event frames from the beginning.

For full-auto weapons, the Fire clip is often shorter — typically 6–8 frames — because the Animator must loop back quickly to support the weapon's fire rate. For a weapon with Firerate 10 (10 rounds per second), the Fire clip must complete in approximately 3 frames at 30 fps. In this case, place Fire at frame 1 and omit Eject_Shell or place it at frame 2.

Fire rate (rounds/sec)	Clip length (frames at 30 fps)	Fire event frame
4 (semi-auto pistol)	10–12	Frame 2–3
6 (semi-auto rifle)	8–10	Frame 2
8 (assault rifle)	6–8	Frame 1–2
10 (SMG)	4–6	Frame 1
12 (LMG)	3–5	Frame 1

Short clips require early event placement

For high fire-rate weapons, the Fire event often must be at frame 1 because the clip does not have enough frames to place it later. At frame 1, there is no visual ramp-up. The cohort recommendation for high-rate weapons is to compensate by adding a subtle muzzle flash that begins at frame 0 as part of the idle/loop animation, giving the visual sense of preparation even at the earliest event position.

Reload clip authoring

The reload clip should be authored so that the three event positions correspond to visually coherent moments:

• Reload_Start should align with the frame where the magazine body begins to visibly separate from the weapon. The gameplay consequence — the weapon entering a reload state — matches the player's visual cue that a reload has started.
• Reload_End should align with the frame where the new magazine is visually seated and the charging handle or chamber round animation is complete. If Reload_End fires 5 frames before the magazine fully clicks into place visually, the player can fire before the reload looks finished.
• For bolt-action and pump-action weapons, each Reload_Loop frame should align with the visual completion of one round being chambered — the bolt closing, the pump returning to battery, the round visually entering the chamber.

Aim clip authoring

The aim clip should be authored so that the weapon travels from the hip position to the sight position in a visually smooth arc. The Aim_Start event at frame 4–6 should coincide with the moment when the weapon has traveled approximately 60% of the way to the face — the player can see the weapon is heading toward ADS, and the camera locking to the sight position at this point feels natural rather than premature.

If the aim clip is too short (under 6 frames), the transition feels like a snap rather than a smooth blend. The cohort's minimum recommended aim clip length is 8 frames. The cohort's target is 10–12 frames.

Performance considerations for animation events

Animation events are lightweight — they are simple method calls dispatched during the Animator update, with no heap allocation per dispatch. The performance concern with animation events is not the events themselves but the work done in response to them.

Muzzle flash particle systems

The Fire event spawns a muzzle flash particle system. Particle systems have a per-spawn cost and a per-update cost. For a full-auto weapon firing at 10 rounds per second, 10 particle systems are spawned per second. The cohort's recommendation is to use Unturned's built-in muzzle flash particle (pooled by the engine) rather than authoring a custom particle system. Custom particle systems are not pooled and create additional garbage collection pressure at high fire rates.

Shell ejection objects

The Eject_Shell event spawns a shell casing object. Shell casings are pooled by Unturned's runtime, so the per-spawn cost is low. However, shells persist in the world for a configurable duration and are rendered as small meshes. For full-auto weapons in a server environment with multiple players firing simultaneously, shell count can accumulate. The server's shell persistence settings govern cleanup; this is a server configuration concern, not a modding concern.

Event dispatch on clients vs. servers

Animation events fire on the client that owns the weapon. They do not fire on remote clients observing the weapon or on the dedicated server. The visual effects (muzzle flash, shell ejection) are local to the owning client. The gameplay effects (projectile spawn, round count decrement) are sent to the server via network messages triggered by the event. This is intentional design: event dispatch is part of the client's animation pipeline, and the server receives the gameplay consequences through a separate authority channel.

No server-side animation events

Dedicated servers do not run animation clips. The Animator is a client-side visual system. This means Reload_End does not fire on the server — the server receives a "reload complete" network message that UseableGun sends when Reload_End fires on the client. If the client's Reload_End event fires at the wrong frame, the server receives the reload completion at the wrong game time. This is why precise Reload_End placement matters even for single-player testing: the timing carries through to the server-side state machine in multiplayer.

Version compatibility notes

The animation event system has been stable across Unturned™ versions since the modding API stabilized. However, the following version-specific behaviors are documented here for modders working with older content:

Unturned version	Known event behavior change
Pre-3.20	Reload_Loop was not supported for pump-action weapons. Individual-round loading required a single long Reload clip with Reload_Start and Reload_End only.
3.20+	Reload_Loop introduced for individual-round loading weapons. Pump-action and bolt-action now support per-round reload loop.
3.22+	Toggle_Light and Toggle_Laser events introduced. Prior versions used a different internal toggle mechanism not accessible to modders.
Current	All nine reserved event names are supported as documented in this article.

The Smartly Dressed Games modding documentation at docs.smartlydressedgames.com is the authoritative source for changes to UseableGun behavior across game versions. Review the changelog when a major Unturned update ships to identify any changes to the animation event system.

Best practices

• Place Fire at frame 2–4 of the Fire clip, not frame 0. The visual ramp-up before the event makes the shot feel physically grounded.
• Extract animation clips from FBX assets to standalone .anim files before placing events. Events on standalone clips persist across FBX re-imports.
• Confirm UseableGun is on the prefab root, not a child object. Event dispatch requires the script to be on the same GameObject as the Animator.
• Disable Loop Time on Fire and Reload clips. Looped fire/reload clips cause repeated event dispatch.
• Use the Animator parameter types exactly as documented: fire and reload as Trigger, aim as Bool.
• Test event placement in Unity Play mode with Debug.Log callbacks before testing in-game. Faster iteration than launching Unturned for each adjustment.
• Keep a copy of the event placement checklist (Appendix C) open while working in the Animation window.
• Coordinate animation clip length with the weapon's intended fire rate. Full-auto weapons need short Fire clips; single-shot weapons have more flexibility.
• Place Reload_End 2–3 frames before the visual completion of the reload, not at the final frame. This ensures the round count restores slightly before the animation fully settles.
• Document the frame positions of all events in the weapon's internal notes or version history. Event positions are not visible in the Unity Project window and are easily lost when a weapon is revisited months later.
• When porting an older weapon mod to a new Unturned™ version, re-verify all event names against the current reserved list. Event names have been stable, but confirming takes 5 minutes and avoids silent failures after an update.
• Do not place events on the Idle clip. The Idle clip loops continuously; any event on it would fire on every loop iteration regardless of player input, causing unintended gameplay actions.
• Author the aim-in and aim-out as separate clips rather than reverse-playing a single clip. Separate clips give independent control over Aim_Start and Aim_End timing, and separate clips are easier to replace if the aim feel needs adjustment after testing.
• For shotguns with multiple pellets, the Fire event fires once per trigger pull, not once per pellet. The pellet count is determined by the magazine's Pellets field, not by the number of Fire events. One event, one trigger pull, N pellets.
• Keep event placement notes in a comment at the top of the weapon's .dat file (as a // comment line). Notepad++ displays comments, making it fast to cross-reference event frames and .dat fields in the same editing session.

Document history

Version	Date	Author	Notes
1.0	2025-05-18	57 Studios	Initial publication. Complete reserved event name reference, frame placement guide, sequence diagrams, diagnostic procedure, clip authoring recommendations, version compatibility notes, and checklist appendix.

Closing note

Animation events are the connective tissue between Unturned's visual layer and its gameplay layer. A weapon mod with misplaced or missing events will animate correctly but behave incorrectly — or animate incorrectly while behaving correctly — and in either case, the disconnect breaks the player's experience. The reserved event names are a small vocabulary, the frame positions are learnable in an afternoon, and the diagnostic procedure covers every failure mode the cohort has encountered. A modder who internalizes the system in this article will never ship a weapon with a silent event error again.

The cohort's ongoing reference is the Gun Mod Tutorial for the full weapon pipeline, Animations Export Blender to Unity for the clip extraction and rig workflow, and the Smartly Dressed Games Modding Documentation for authoritative version-specific behavior. Cross-reference all three when working with a weapon that exhibits unexpected event behavior.