ItemGripAsset — Grip Attachments

Advanced15-20 minutesWindowsVisual Studio

Improving weapon handling through foregrips and bipods in Unturned begins with understanding how ItemGripAsset serves as the simplest attachment class, loading only a grip prefab while inheriting a full stat modifier suite from ItemCaliberAsset. ItemGripAsset extends ItemCaliberAsset and adds only a single field — the grip prefab reference. All stat modification behavior comes from the ItemCaliberAsset base class, which provides a comprehensive modifier system for recoil, spread, sway, shake, firerate, damage, bullet drop, and ADS characteristics.

Source code location: Unturned/Bundles/ItemGripAsset.cs

Inheritance Chain

ItemAsset
  → ItemCaliberAsset
    → ItemGripAsset

Class Definition

public class ItemGripAsset : ItemCaliberAsset
{
    protected GameObject _grip;
    public GameObject grip => _grip;

    [Obsolete]
    public bool isBipod => _isBipod;

    public override void PopulateAsset(in PopulateAssetParameters p)
    {
        base.PopulateAsset(in p);

        _grip = loadRequiredAsset<GameObject>(p.bundle, "Grip");
    }
}

The deprecated isBipod property (now ShouldOnlyAffectAimWhileProne on ItemCaliberAsset) returns _isBipod for backwards compatibility with older code that checked the grip class directly.

Core Fields

Field	Type	Bundle Asset	Description
_grip	GameObject	"Grip"	Grip attachment prefab

The only field on ItemGripAsset is the prefab, loaded from the bundle as "Grip". All stat behavior is inherited from ItemCaliberAsset.

PopulateAsset

public override void PopulateAsset(in PopulateAssetParameters p)
{
    base.PopulateAsset(in p);
    _grip = loadRequiredAsset<GameObject>(p.bundle, "Grip");
}

The grip asset requires the "Grip" prefab in the asset bundle. If the prefab is missing, loadRequiredAsset reports an error through the asset validation system.

Inherited Stat Modifiers (ItemCaliberAsset)

All grip assets inherit the full ItemCaliberAsset modifier system. The grip is the primary source of horizontal recoil reduction for most weapons:

Recoil

Field	.dat Key	Default	Description
recoil_x	Recoil_X	1.0	Horizontal recoil multiplier
recoil_y	Recoil_Y	1.0	Vertical recoil multiplier
aimingRecoilMultiplier	Aiming_Recoil_Multiplier	1.0	ADS recoil modifier

Grips typically set Recoil_X below 1.0 to reduce horizontal recoil. Vertical grips may also reduce Recoil_Y.

Spread

Field	.dat Key	Default	Description
spread	Spread	1.0	Spread angle multiplier
sway	Sway	1.0	Weapon sway multiplier
shake	Shake	1.0	Camera shake multiplier

Firerate

Field	.dat Key	Default	Description
FirerateOffset	Firerate	0	Firerate adjustment (positive = faster)

The FirerateOffset is subtracted from the gun's firerate byte. A positive offset decreases the time between shots (faster fire rate). A negative offset increases the time (slower).

ADS and Movement

Field	.dat Key	Default	Description
aimDurationMultiplier	Aim_Duration_Multiplier	1.0	ADS speed modifier
aimingMovementSpeedMultiplier	Aiming_Movement_Speed_Multiplier	1.0	ADS move speed modifier

Ballistic

Field	.dat Key	Default	Description
ballisticDamageMultiplier	Ballistic_Damage_Multiplier or Damage	1.0	Bullet damage multiplier
BallisticGravityMultiplier	Ballistic_Drop	1.0	Bullet drop multiplier

Special Flags

Field	.dat Key	Default	Description
calibers	Calibers / Caliber_N	—	Compatible caliber IDs
isPaintable	Paintable	false	Can receive cosmetic paint
ShouldOnlyAffectAimWhileProne	Bipod	false	Bipod: only affects ADS while prone
CanDamageInvulernableEntities	Invulnerable	false	Can damage invulnerable-tagged entities
shouldDestroyAttachmentColliders	Destroy_Attachment_Colliders	true	Remove colliders from attachment prefab
instantiatedAttachmentName	Instantiated_Attachment_Name_Override	GUID	Prefab name override for legacy animation

Caliber Compatibility

The CalibersContainId(ushort) and CalibersContainAnyOfIds(ushort[]) methods inherited from ItemCaliberAsset check whether the grip is compatible with the gun's attachmentCalibers.

Bipod Behavior

When ShouldOnlyAffectAimWhileProne (set via the Bipod key) is true, the grip's stat modifiers only take effect when the player is prone and aiming. This implements the bipod mechanic:

1. Standing/crouching ADS: No grip stat modifiers (values act as 1.0).
2. Prone ADS: Full grip stat modifiers are applied.

This allows bipod grips to provide substantial benefits (strong recoil reduction, high accuracy) but only when the player is set up in a prone position.

Description UI

ItemGripAsset does not override BuildDescription — it relies entirely on ItemCaliberAsset.BuildDescription. The calendar base renders each non-default stat modifier with color coding:

• Positive effects (lower recoil, tighter spread, faster ADS) appear in green.
• Negative effects (higher recoil, wider spread, slower ADS) appear in red.
• Unchanged stats (value = 1.0) are omitted from the display.
• Bipod grips display their conditional nature through the stat text.

Cargo Data Export

ItemGripAsset does not override BuildCargoData — all data is written by the ItemCaliberAsset base class to the Caliber table (which covers all attachment subtypes). The caliber table includes all stat modifiers, caliber IDs, and flag values.

Attachment Integration

When a grip is attached to a gun, UseableGun:

1. Instantiates the _grip prefab at the weapon's Hook_Grip transform.
2. Applies all ItemCaliberAsset modifiers multiplicatively to the gun's base stats.
3. If ShouldOnlyAffectAimWhileProne is true, modifiers are conditional on prone ADS.
4. Removes colliders from the grip prefab if shouldDestroyAttachmentColliders is true.

The grip's quality is tracked at byte offset 15 of the weapon's 18-byte state array. A zero-quality grip provides no stat benefits.

Common Issues

1. Empty grip as bipod only — A grip with only Bipod set and all other stat modifiers at 1.0 provides no benefit when standing. The modder must set non-1.0 values (like Recoil_X=0.5) for the bipod to have an effect.
2. Firerate offset direction — The FirerateOffset is subtracted from the gun's firerate. A positive Firerate value makes the gun fire faster. This is counterintuitive — "positive = faster" is the opposite of what an additive offset would suggest.
3. Damage key priority — The Damage key serves as a fallback for Ballistic_Damage_Multiplier. If both are set, Ballistic_Damage_Multiplier takes priority. The Damage key was originally barrel-only and was accidentally retained as a global fallback.
4. isBipod depreciation — The old isBipod property is marked [Obsolete] and redirects to ItemCaliberAsset._isBipod. Code references to ItemGripAsset.isBipod still work but emit deprecation warnings.

Worked Code Example: Grip Stat Analyzer

using SDG.Unturned;

public static class GripStatAnalyzer
{
    /// <summary>
    /// Compares two grip attachments and returns the net stat delta,
    /// useful for player-facing upgrade comparisons.
    /// </summary>
    public static void CompareGripStats(ItemGripAsset gripA, ItemGripAsset gripB)
    {
        float recoilDeltaX = gripB.recoil_x - gripA.recoil_x;
        float spreadDelta = gripB.spread - gripA.spread;

        string verdict = "";
        if (recoilDeltaX < 0) verdict += "Better recoil control. ";
        if (spreadDelta < 0) verdict += "Tighter spread. ";
        if (string.IsNullOrEmpty(verdict)) verdict = "No improvement.";
    }
}

Mermaid Diagram: Grip Attachment Flow

Comparison: Grip vs. Other Weapon Attachments

Feature	ItemGripAsset	ItemBarrelAsset	ItemSightAsset
Prefab slot	Hook_Grip	Hook_Barrel	Hook_Sight
Audio	None	Shoot AudioClip	None
Silencer support	No	Yes	No
Visual only	Prefab only	Prefab + audio	Prefab + scope overlay
Durability	No	Yes	No
Style variants	Single prefab per asset	Single prefab per asset	Multiple holographic modes

How This Differs from SDG Docs

• SDG docs list grip as "optional accessory." In the SDK, grips are a standard weapon attachment slot inheriting from ItemCaliberAsset — they are a core attachment type, not optional. Every gun has a Hook_Grip transform.
• SDG docs claim bipod activation is "automatic." The community says bipods activate automatically when prone. In the SDK, ShouldOnlyAffectAimWhileProne checks if both prone AND ADS — standing prone without aiming does not activate bipod benefits.

Performance Considerations

Grip prefab instantiation is a single GameObject.Instantiate call per attachment. Collider destruction applies to any child colliders of the prefab. Both are one-time operations at equip time, not per-frame.

Deeper FAQ

Q: Can a grip have negative stat values (worse than no grip)?

Yes. Setting stat multipliers above 1.0 (e.g., Recoil_X=1.5) makes the weapon worse. This is sometimes used for cursed/troll items or to simulate damaged attachments.

Q: Can weapons have multiple grip attachment points?

No. There is exactly one Hook_Grip per weapon. Grip, bipod, and angled grip are mutually exclusive — they occupy the same attachment slot.

Cross-References

• ItemCaliberAsset — Weapon Mod Base Class — The parent class containing all stat modifier fields and bipod logic.
• ItemBarrelAsset — Barrel Attachments — Barrel-slot attachment comparison.
• ItemGunAsset — Gun Weapon System — How grip modifiers apply to the gun's base stats.

Document history