ItemHatAsset — Hat Clothing Definition

Advanced15-20 minutesWindowsVisual Studio

Overview

ItemHatAsset defines a wearable hat item in Unturned. It inherits from ItemGearAsset (hair/beard override support), which inherits from ItemClothingAsset (armor, proof system, movement speed), which inherits from ItemAsset (slot, rarity, size, blueprints). The class loads a "Hat" GameObject prefab from the master bundle and provides it to the character rendering system through the ClothingPrefab virtual property.

Hats occupy the EItemType.HAT slot and are one of four slot types (along with shirts, pants, and vests) eligible for armor damage reduction. A hat can carry the full clothing feature set: armor values, explosion armor, proof flags, movement speed modifier, hair/beard visibility toggles, hair/beard material override, skin override, cosmetic preview model, wear audio, and cosmetic priority.

Source code location: Unturned/Bundles/ItemHatAsset.cs (32 lines), inheriting from ItemGearAsset.cs (88 lines), ItemClothingAsset.cs (304 lines), and ItemAsset.cs (base).

Inheritance Chain

ItemAsset
  └─ ItemClothingAsset (abstract) — armor, proof, movement speed, visuals
       └─ ItemGearAsset (abstract) — hair/beard override, legacy Hair/Beard flags
            └─ ItemHatAsset — hat prefab, layer/cloth validation

---

Class Definition

public class ItemHatAsset : ItemGearAsset
{
    protected GameObject _hat;
    public GameObject hat => _hat;

    public override void PopulateAsset(in PopulateAssetParameters p) { ... }

    internal override GameObject ClothingPrefab => hat;
}

The class is minimal — 32 lines including whitespace. The size of this article reflects the inherited behavior: most of what makes hats functional is defined in ItemClothingAsset and ItemGearAsset. This article documents the hat-specific prefab loading, validation, and how the inherited systems apply to hats specifically.

---

Hat Prefab Loading

Load Path

The PopulateAsset override loads the "Hat" GameObject from the bundle:

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

    if (!Dedicator.IsDedicatedServer)
    {
        _hat = loadRequiredAsset<GameObject>(p.bundle, "Hat");

        if (Assets.shouldValidateAssets)
        {
            AssetValidation.ValidateLayersEqual(this, _hat, LayerMasks.ENEMY);
            AssetValidation.ValidateClothComponents(this, _hat);
        }
    }
}

Key points:

Aspect	Detail
loadRequiredAsset<GameObject>	Fails with error if "Hat" GameObject is missing
Server skip	Dedicated server doesn't load the prefab — hats are cosmetic-only on server
shouldValidateAssets guard	Validation only runs when -ValidateAssets flag is enabled
ClothingPrefab override	Returns hat to the character rendering system

Why the Server Skips It

Hats are visual-only. The dedicated server does not need the 3D model — it only needs the .dat values (armor, proof flags, movement speed). Skipping the prefab load saves memory and startup time.

---

Asset Validation

When Assets.shouldValidateAssets is true, two validation checks run:

1. Layer Validation

AssetValidation.ValidateLayersEqual(this, _hat, LayerMasks.ENEMY);

Verifies that the hat prefab's root GameObject and all its children are on the ENEMY game layer. Clothing items on the wrong layer may not render correctly in the inventory preview, first-person view, or certain camera contexts.

The ENEMY layer is the standard rendering layer for character-attached equipment in Unturned. Items that need to render on different layers (rare) should handle this themselves, but the validation warns if the layer is wrong for standard hats.

2. Cloth Component Validation

AssetValidation.ValidateClothComponents(this, _hat);

Checks for Unity Cloth components on the prefab. Cloth components enable physics-simulated fabric movement (flags, loose straps, dangling elements). The validation warns if Cloth components are incorrectly configured:

• Missing required settings
• Performance concerns (excessive vertex count)
• Compatibility issues with the character skeleton

Validation Conditions

Condition	Check
!Dedicator.IsDedicatedServer	Validation only runs on clients (editor mode or client build)
Assets.shouldValidateAssets	Only when -ValidateAssets command-line flag is active
_hat successfully loaded	If loadRequiredAsset failed, validation is skipped (the asset already has an error)

---

Inherited Behavior: ItemClothingAsset

All behavior documented in this section is defined in ItemClothingAsset and inherited by ItemHatAsset. It is included here as it applies directly to hat items.

Armor System (Hats Are Eligible)

Hats are one of the four slot types that apply armor:

if (type == EItemType.HAT || type == EItemType.SHIRT || type == EItemType.PANTS || type == EItemType.VEST)
{
    if (_armor != 1.0f) { /* show armor description */ }
    if (_explosionArmor != 1.0f) { /* show explosion armor description */ }
}

.dat Key	Type	Default	Behavior
Armor	float	1.0	Multiplier to incoming damage. 0.8 = 20% reduction, 1.0 = no protection
Armor_Explosion	float	equals Armor	Multiplier to explosive damage specifically
Falling_Damage_Multiplier	float	1.0	Multiplier applied to falling damage
Prevents_Falling_Broken_Bones	bool	false	When true, falling never breaks bones

Armor from multiple slots multiplies: a hat with Armor 0.9 and a shirt with Armor 0.8 produce a combined 0.9 × 0.8 = 0.72 multiplier (28% damage reduction).

PRO items have all armor forced to 1.0 (no damage reduction) to prevent cosmetic-only items from providing gameplay advantage:

if (isPro)
{
    _armor = 1f;
    _explosionArmor = 1f;
    fallingDamageMultiplier = 1.0f;
}

Proof System

.dat Key	Behavior when present
Proof_Water	No drowning damage while wearing
Proof_Fire	Immune to burning/fire damage
Proof_Radiation	No radiation damage in deadzones

Proof flags are checked via ContainsKey — any non-empty value sets the flag. This is a binary system: there is no partial proof.

Movement Speed

.dat Key	Type	Default	Behavior
Movement_Speed_Multiplier	float	1.0	Walk/run speed scalar

Values below 1.0 slow the player (heavy helmet), values above 1.0 speed the player (light headgear). This compounds with equipableMovementSpeedMultiplier from ItemAsset.

Visual and Cosmetic Fields

.dat Key	Type	Default	Behavior
Hair_Visible	bool	true	Character hair visible through hat
Beard_Visible	bool	true	Character beard visible through hat
Visible_On_Ragdoll	bool	true	Hat visible on dead body/ragdoll
Mirror_Left_Handed_Model	bool	true	Mirror model for left-handed characters
Skin_Override	string	null	Child mesh name for skin material override
Destroy_Clothing_Colliders	bool	true	Remove colliders after equip
Priority_Over_Cosmetic	bool	false	Real hat takes priority over cosmetic hat

Wear Audio

Hats default to the sleeve rustle sound:

wearAudio = new AudioReference("core.masterbundle", "Sounds/Sleeve.mp3");

Override with WearAudio pointing to a custom audio clip in the item's master bundle.

Cosmetic Priority

The TakesPriorityOverCosmetic property resolves conflicts when a player wears both a real hat and a cosmetic hat. By default (GetDefaultTakesPriorityOverCosmetic returns false), the cosmetic item is shown. Override with Priority_Over_Cosmetic to force the real item to display.

Hat-specific note: Most hats do not override the cosmetic priority. The hat cosmetic system typically allows the cosmetic to take precedence because hats don't have gameplay-critical visuals. Contrast with ItemGlassesAsset which overrides priority when night vision or blindfold is active.

---

Inherited Behavior: ItemGearAsset

Hair and Beard Override

Hats can replace the character's hair material with a custom material:

.dat Key	Type	Purpose
Hair_Override	string	Child meshrenderer name to replace with hair material
Hair_Override_NonGoldColor	Color32?	Fallback color for non-Gold players
Beard_Override	string	Child meshrenderer name to replace with beard material
Beard_Override_NonGoldColor	Color32?	Fallback color for non-Gold players

When Hair_Override is set to a child transform name, the clothing system finds that MeshRenderer on the hat prefab and replaces its material with the character's hair material (dynamically matching the player's chosen hair color). This allows hats to include hair geometry — for example, a baseball cap that shows the wearer's hair color peeking through.

The NonGoldColor variants provide a fallback for players without the Gold Upgrade (which unlocks full RGB hair color control). The non-Gold color defaults are the standard hair color options available to free players.

Legacy Hair/Beard Visibility

ItemGearAsset checks for the legacy Hair and Beard keys (without the _Visible suffix):

hairVisible = p.data.ContainsKey("Hair");
beardVisible = p.data.ContainsKey("Beard");

This overrides the Hair_Visible/Beard_Visible values set by ItemClothingAsset. The legacy keys use ContainsKey logic — the presence of Hair means hairVisible = true. For backward compatibility with older mods, both naming conventions are supported.

Practical effect for hats: A hat that uses Hair in the .dat file will override the hairVisible field to true, showing the character's hair through the hat model. A hat that uses Hair_Visible false instead will hide the character's hair.

---

ClothingPrefab and Character Rendering

The ClothingPrefab virtual property connects the asset to the character rendering system:

internal override GameObject ClothingPrefab => hat;

When a player equips a hat, the character rendering system:

1. Calls the ClothingPrefab getter to obtain the hat GameObject
2. Instantiates the prefab on the player's head bone transform
3. Applies the skinOverride if set (replaces child mesh material with skin material)
4. Applies the hairOverride if set (replaces child mesh material with hair material)
5. Destroys colliders if shouldDestroyClothingColliders is true
6. Mirrors the model if shouldMirrorLeftHandedModel is true and character is left-handed

The prefab must contain a SkinnedMeshRenderer component attached to the root or children. The mesh will deform with the character's head animations.

---

BuildDescription — Inventory Tooltip

The hat's inventory tooltip shows entries from the clothing base class. The BuildDescription chain is:

ItemAsset.BuildDescription          → Size, rarity, slot, PRO status
ItemClothingAsset.BuildDescription  → Armor, explosion armor, movement speed, falling damage, proof flags
                                        (only shown for HAT, SHIRT, PANTS, VEST slot types)
ItemGearAsset.BuildDescription      → (no additions — gear-specific description handled by subclasses)
ItemHatAsset.BuildDescription       → (no additions — hats have no slot-specific tooltip entries)

The description for a hat with Armor 0.85 and Proof_Fire would display:

• Armor: 0.85 (85% — lower is better)
• Fireproof (green text, beneficial stat)

Items without non-default armor values show no armor line.

---

BuildCargoData — Wiki Export

Hats contribute to two Cargo database tables:

Clothing table (from ItemClothingAsset)

Column	Source
GUID	Asset GUID (PK, FK to Asset)
Armor	_armor
Armor_Explosion	_explosionArmor
Falling_Damage_Multiplier	fallingDamageMultiplier
Proof_Water	_proofWater
Proof_Fire	_proofFire
Proof_Radiation	_proofRadiation
Prevents_Falling_Broken_Bones	preventsFallingBrokenBones
Movement_Speed_Multiplier	movementSpeedMultiplier
Mirror_Left_Handed_Model	shouldMirrorLeftHandedModel
Priority_Over_Cosmetic	hasPriorityOverCosmeticOverride

Gear table (from ItemGearAsset)

Column	Source
GUID	Asset GUID (PK, FK to Clothing)
Hair	hairVisible
Beard	beardVisible

Hats inherit the Gear table from ItemGearAsset but do not add a dedicated Hat Cargo table — there is no hat-specific exporter beyond the Clothing and Gear tables.

---

Inventory Audio

The default inventory audio for hats follows the clothing scale convention from ItemClothingAsset:

protected override AudioReference GetDefaultInventoryAudio()
{
    if (size_x <= 1 || size_y <= 1)
        return new AudioReference("core.masterbundle", "Sounds/Inventory/LightCloth.asset");

    if (rarity == EItemRarity.COMMON || rarity == EItemRarity.UNCOMMON)
        return new AudioReference("core.masterbundle", "Sounds/Inventory/LightClothEquipment.asset");
    else
        return new AudioReference("core.masterbundle", "Sounds/Inventory/MediumClothEquipment.asset");
}

The audio scales with grid size and rarity:

• 1×1 or smaller: Light cloth sound (small items)
• Common/Uncommon: Light cloth equipment sound
• Rare/Epic/Legendary/Mythic: Medium cloth equipment sound

---

PopulateAsset Call Chain

The complete deserialization order for a hat asset:

ItemAsset.PopulateAsset               — GUID, Type, Slot, Size_X/Y/Z, Rarity, IsPro, blueprints, animations, etc.
  └─ ItemClothingAsset.PopulateAsset  — Armor, Armor_Explosion, Falling_Damage_Multiplier, Proof flags,
                                         Movement_Speed_Multiplier, Visible_On_Ragdoll, Hair_Visible/Beard_Visible,
                                         Mirror_Left_Handed_Model, WearAudio, Destroy_Clothing_Colliders,
                                         Priority_Over_Cosmetic, Skin_Override, cosmeticPreviewModelOverride
       └─ ItemGearAsset.PopulateAsset — Hair/Beard legacy keys, Hair_Override/Beard_Override, NonGoldColor variants
            └─ ItemHatAsset.PopulateAsset — load "Hat" prefab, layer/cloth validation

---

PRO vs Non-PRO Behavior

Feature	Non-PRO Hat	PRO Hat (Cosmetic)
Armor values	Parsed from .dat	Forced to 1.0 (no protection)
Explosion armor	Parsed from .dat	Forced to 1.0
Falling damage multiplier	Parsed from .dat	Forced to 1.0
Prefab loading	Normal	Normal + CosmeticPreviewOverride
Cosmetic priority	Normal	Override available
Hair/beard override	Normal	Normal
Skin override	Normal	Normal

PRO hats are cosmetics-only: they render on the character but provide no gameplay stats. The CosmeticPreviewOverride GameObject (loaded from the bundle) is used in the cosmetic selection UI menus.

---

.dat File Reference — Hat-Specific

.dat Key	Type	Default	Category
Armor	float	1.0	Damage mitigation (applied for HAT slot)
Armor_Explosion	float	equals Armor	Explosion-specific armor
Falling_Damage_Multiplier	float	1.0	Fall damage scalar
Proof_Water	flag	—	Water breathing
Proof_Fire	flag	—	Fire immunity
Proof_Radiation	flag	—	Radiation immunity
Prevents_Falling_Broken_Bones	bool	false	No fall bone breaks
Movement_Speed_Multiplier	float	1.0	Movement speed modifier
Visible_On_Ragdoll	bool	true	Visible on death
Hair_Visible	bool	true	Show character hair
Beard_Visible	bool	true	Show character beard
Mirror_Left_Handed_Model	bool	true	Mirror for left-handed
WearAudio	AudioReference	Sounds/Sleeve.mp3	Equip sound
Destroy_Clothing_Colliders	bool	true	Remove colliders after equip
Priority_Over_Cosmetic	bool	false	Priority over cosmetic
Skin_Override	string	—	Child mesh name for skin
Hair	flag	—	Legacy hair visibility (from ItemGearAsset)
Beard	flag	—	Legacy beard visibility (from ItemGearAsset)
Hair_Override	string	—	Child mesh name for hair material
Hair_Override_NonGoldColor	Color32	—	Non-Gold hair fallback color
Beard_Override	string	—	Child mesh name for beard material
Beard_Override_NonGoldColor	Color32	—	Non-Gold beard fallback color

All standard ItemAsset fields (GUID, Type, Slot, Rarity, Size_X, Size_Y, Size_Z, Pro, Exchange_Master_Bundle_GUID, Exchange_Item_GUID, blueprint fields, animation fields, etc.) are also available.

---

Master Bundle Prefab Requirements

Bundle Key	Type	Required	Purpose
"Hat"	GameObject	Required	3D hat prefab with SkinnedMeshRenderer
"CosmeticPreviewOverride"	GameObject	Optional	PRO-only preview model for cosmetic menu
"Hair_Override" child mesh	MeshRenderer	Optional	Child mesh for dynamic hair color
"Beard_Override" child mesh	MeshRenderer	Optional	Child mesh for dynamic beard color
"Skin_Override" child mesh	MeshRenderer	Optional	Child mesh for skin material

---

Modding Example — Basic Hat .dat

GUID a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Type Hat
Rarity Common
Size_X 2
Size_Y 2
Armor 0.95
Movement_Speed_Multiplier 1.0
Hair_Visible false

This creates a common-rarity hat that:

• Occupies a 2×2 inventory cell
• Provides 5% damage reduction (0.95 multiplier)
• Does not modify movement speed
• Hides the character's hair (hat covers the head completely)

---

Modding Example — Heavy Helmet .dat

GUID f1e2d3c4b5a69788796a5b4c3d2e1f0a
Type Hat
Rarity Rare
Size_X 2
Size_Y 3
Armor 0.80
Armor_Explosion 0.70
Falling_Damage_Multiplier 0.50
Prevents_Falling_Broken_Bones true
Movement_Speed_Multiplier 0.95
Proof_Fire
Mirror_Left_Handed_Model true
Hair_Visible false
Beard_Visible true

This creates a heavy military helmet that:

• Provides 20% general damage reduction and 30% explosion reduction
• Halves falling damage and prevents bone breaks on fall
• Slightly slows the player (5% speed reduction)
• Grants fire immunity
• Hides hair but shows the beard

---

Modding Example — Hat with Hair Override .dat

GUID c9d8e7f6a5b4c3d29180796a5b4c3d2
Type Hat
Rarity Uncommon
Size_X 2
Size_Y 2
Armor 1.0
Hair
Hair_Override "Hat_Hair"

This creates a hat that:

• Provides no armor (purely cosmetic for non-PRO)
• Uses the legacy Hair flag to show hair
• Has a child mesh named "Hat_Hair" whose material will be replaced with the character's dynamic hair color

---

Common Issues

1. Hat not rendering: Verify the "Hat" key exactly matches the asset name in the Unity bundle. The key is case-sensitive: "Hat", not "hat" or "HAT".

2. Wrong render layer: If the hat appears black or invisible in the inventory preview, the prefab is likely on the wrong layer. Run with -ValidateAssets to check layer assignments.

3. Cloth physics not working: Ensure the Cloth component is correctly configured. The ValidateClothComponents check warns about common misconfigurations.

4. Armor not applying: Verify the item type is EItemType.HAT (set via Type Hat or class association). Armor only applies to HAT, SHIRT, PANTS, and VEST slot types.

5. Hair visible through hat: Set Hair_Visible false to hide hair. The legacy Hair key (without _Visible) has the opposite effect — its presence sets hairVisible = true via the ItemGearAsset override.

6. PRO hat with armor: PRO items force armor to 1.0 regardless of .dat settings. If you need armor on a cosmetic item, use a non-PRO hat.

7. Left-handed model backwards: If the hat appears mirrored on left-handed characters, set Mirror_Left_Handed_Model false (though most hats should leave this at true).

8. Collider interference: By default, hat colliders are destroyed after equip (Destroy_Clothing_Colliders true). If you need the collider to remain (e.g., for hitbox modification), set this to false.

9. Hair override mesh not found: The Hair_Override value must match the exact name of a child MeshRenderer on the hat prefab. Case-sensitive, must be a direct or indirect child of the root GameObject.

10. Skin override silent failure: If Skin_Override is set but no child mesh with that name exists, the override is silently ignored with no error — verify the child name matches exactly.

Document history

Version	Date	Author	Notes
1.0	2026-07-28	57 Studios	Initial publication. Full hat asset documentation including ItemClothingAsset and ItemGearAsset inheritance, validation, .dat reference, and modding examples.