SkinManager.cs

using System.Globalization;
using CounterStrikeSharp.API;
using CounterStrikeSharp.API.Core;
using CounterStrikeSharp.API.Modules.Entities.Constants;
using CounterStrikeSharp.API.Modules.Admin;
using CounterStrikeSharp.API.Modules.Extensions;
using CounterStrikeSharp.API.Modules.Utils;
using Microsoft.Extensions.Logging;
using AstraSkins.Models;

namespace AstraSkins;

public sealed class SkinManager : IDisposable
{
    public const string KnifeTarget = "knife";
    public const string GloveTarget = "glove";

    // Stored in the cosmetic_id column of a "stattrak" row to record an explicit
    // off under EnableStatTrakByDefault. Not a number, so older builds skip the
    // row instead of reading it as a count.
    public const string StatTrakDisabledValue = "off";

    // Sticker slots a gun exposes in the game (0 to 4).
    public const int StickerSlots = 5;

    private const ulong MinimumCustomItemId = 65578;

    private readonly ISkinStorage _storage;
    private readonly ILogger _logger;
    private readonly EconAttributeApplicator _econAttributes;
    private readonly bool _statTrakByDefault;
    private readonly ModuleSwitches _modules;
    // Kit 0 entries handed to guns that carry stickers or a charm without a
    // skin: the client renders the stock finish with the attachments on.
    private readonly Dictionary<string, CosmeticEntry> _vanillaEntries = new(StringComparer.OrdinalIgnoreCase);
    private readonly Dictionary<ulong, PlayerSkinProfile> _profiles = new();
    // _profiles can hold a placeholder while a read is in flight, so loaded
    // completion is tracked separately; without this a failed read leaves the
    // placeholder blocking every retry until the player reconnects.
    private readonly HashSet<ulong> _loadedProfiles = new();
    private readonly HashSet<ulong> _loadingProfiles = new();
    private readonly HashSet<ulong> _applyAfterLoadRequests = new();
    private readonly HashSet<ulong> _activeSteamIds = new();
    private readonly Dictionary<ulong, ulong> _profileEpochs = new();
    // Kit ids this plugin wrote per player, so a clear only touches players
    // we painted and everyone else keeps the value Valve put there.
    private readonly Dictionary<ulong, int> _appliedMusicKits = new();
    private readonly object _storageQueueLock = new();
    private Task _storageQueue = Task.CompletedTask;
    private ulong _nextItemId = MinimumCustomItemId;
    private bool _disposed;

    private static readonly Dictionary<int, string> WeaponEntityByDefinitionIndex = new()
    {
        [1] = "weapon_deagle",
        [2] = "weapon_elite",
        [3] = "weapon_fiveseven",
        [4] = "weapon_glock",
        [7] = "weapon_ak47",
        [8] = "weapon_aug",
        [9] = "weapon_awp",
        [10] = "weapon_famas",
        [11] = "weapon_g3sg1",
        [13] = "weapon_galilar",
        [14] = "weapon_m249",
        [16] = "weapon_m4a1",
        [17] = "weapon_mac10",
        [19] = "weapon_p90",
        [23] = "weapon_mp5sd",
        [24] = "weapon_ump45",
        [25] = "weapon_xm1014",
        [26] = "weapon_bizon",
        [27] = "weapon_mag7",
        [28] = "weapon_negev",
        [29] = "weapon_sawedoff",
        [30] = "weapon_tec9",
        [31] = "weapon_taser",
        [32] = "weapon_hkp2000",
        [33] = "weapon_mp7",
        [34] = "weapon_mp9",
        [35] = "weapon_nova",
        [36] = "weapon_p250",
        [38] = "weapon_scar20",
        [39] = "weapon_sg556",
        [40] = "weapon_ssg08",
        [42] = "weapon_knife",
        [59] = "weapon_knife_t",
        [60] = "weapon_m4a1_silencer",
        [61] = "weapon_usp_silencer",
        [63] = "weapon_cz75a",
        [64] = "weapon_revolver",
        [500] = "weapon_bayonet",
        [503] = "weapon_knife_css",
        [505] = "weapon_knife_flip",
        [506] = "weapon_knife_gut",
        [507] = "weapon_knife_karambit",
        [508] = "weapon_knife_m9_bayonet",
        [509] = "weapon_knife_tactical",
        [512] = "weapon_knife_falchion",
        [514] = "weapon_knife_survival_bowie",
        [515] = "weapon_knife_butterfly",
        [516] = "weapon_knife_push",
        [517] = "weapon_knife_cord",
        [518] = "weapon_knife_canis",
        [519] = "weapon_knife_ursus",
        [520] = "weapon_knife_gypsy_jackknife",
        [521] = "weapon_knife_outdoor",
        [522] = "weapon_knife_stiletto",
        [523] = "weapon_knife_widowmaker",
        [525] = "weapon_knife_skeleton",
        [526] = "weapon_knife_kukri"
    };

    private static readonly string[] TeamPreviewDesignerNames =
    {
        "team_intro_counterterrorist",
        "team_intro_terrorist",
        "team_select_counterterrorist",
        "team_select_terrorist",
        "wingman_intro_counterterrorist",
        "wingman_intro_terrorist"
    };

    public DefinitionCatalog Catalog { get; private set; }

    public SkinManager(
        ISkinStorage storage,
        DefinitionCatalog catalog,
        ILogger logger,
        Action<float, Action>? scheduleDelayed = null,
        bool statTrakByDefault = false,
        Func<string, bool>? isModelPrecached = null,
        ModuleSwitches? modules = null)
    {
        _storage = storage;
        Catalog = catalog;
        _logger = logger;
        _scheduleDelayed = scheduleDelayed;
        _statTrakByDefault = statTrakByDefault;
        _isModelPrecached = isModelPrecached;
        _modules = modules ?? new ModuleSwitches();
        _econAttributes = new EconAttributeApplicator(logger);
    }

    private const int ProfileRetrySeconds = 10;
    private readonly Action<float, Action>? _scheduleDelayed;
    // Answers whether a model was precached for the current map; a model
    // added by a reload mid-map must not be set on a pawn.
    private readonly Func<string, bool>? _isModelPrecached;
    private readonly HashSet<string> _unprecachedModelsWarned = new(StringComparer.OrdinalIgnoreCase);
    // A failed profile read is not retried before this time, otherwise the
    // per-tick music reconcile would hammer a database that is down.
    private readonly Dictionary<ulong, DateTime> _profileRetryAfterUtc = new();

    public void ReplaceCatalog(DefinitionCatalog catalog)
    {
        Catalog = catalog;
        RemoveInvalidCachedSelections();
    }

    public void Dispose()
    {
        _disposed = true;
        _activeSteamIds.Clear();
        _loadedProfiles.Clear();
        _loadingProfiles.Clear();
        _applyAfterLoadRequests.Clear();
        _profiles.Clear();
        _profileEpochs.Clear();
        _appliedMusicKits.Clear();
        _profileRetryAfterUtc.Clear();

        Task pendingStorageWork;
        lock (_storageQueueLock)
        {
            pendingStorageWork = _storageQueue;
        }

        if (pendingStorageWork.IsCompleted)
        {
            return;
        }

        try
        {
            // Unload only happens on an explicit plugin unload/reload, not on
            // map change, so blocking briefly here is cheap. Dropping writes
            // silently is not, hence the warning.
            if (!pendingStorageWork.Wait(TimeSpan.FromSeconds(3)))
            {
                _logger.LogWarning(
                    "Astra Skins unloaded while database writes were still pending; the most recent selections may not have been saved.");
            }
        }
        catch
        {
            // Queued operations log their own failures.
        }
    }

    public PlayerSkinProfile GetProfile(CCSPlayerController player)
    {
        var steamId = GetSteamId64(player);
        _activeSteamIds.Add(steamId);
        if (_profiles.TryGetValue(steamId, out var profile))
        {
            return profile;
        }

        // Start the load before caching the placeholder so the already-cached
        // guard in LoadProfileInBackground does not skip it.
        LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures: false);
        profile = new PlayerSkinProfile { SteamId64 = steamId };
        _profiles[steamId] = profile;
        return profile;
    }

    public void Forget(CCSPlayerController player)
    {
        if (TryGetSteamId64(player, out var steamId))
        {
            Forget(steamId);
        }
    }

    public void Forget(ulong steamId64)
    {
        _profiles.Remove(steamId64);
        _loadedProfiles.Remove(steamId64);
        _applyAfterLoadRequests.Remove(steamId64);
        _activeSteamIds.Remove(steamId64);
        _appliedMusicKits.Remove(steamId64);
        _profileRetryAfterUtc.Remove(steamId64);

        // A read still in flight must come back stale: bump the epoch instead
        // of deleting it so the callback can tell this lifecycle ended.
        if (_loadingProfiles.Contains(steamId64))
        {
            BumpProfileEpoch(steamId64);
        }
        else
        {
            _profileEpochs.Remove(steamId64);
        }
    }

    public void ApplyToPlayerWhenProfileReady(CCSPlayerController player, bool logFailures = false)
    {
        if (_disposed)
        {
            return;
        }

        if (!TryGetSteamId64(player, out var steamId))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply cosmetics: player SteamID64 is invalid.");
            }

            return;
        }

        if (_loadedProfiles.Contains(steamId))
        {
            ApplyToPlayer(player, logFailures);
            return;
        }

        _activeSteamIds.Add(steamId);
        LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures);
    }

    public void ApplyMusicKitWhenProfileReady(CCSPlayerController player, bool logFailures = false)
    {
        if (_disposed)
        {
            return;
        }

        if (!TryGetSteamId64(player, out var steamId))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply music kit: player SteamID64 is invalid.");
            }

            return;
        }

        if (_loadedProfiles.Contains(steamId))
        {
            ApplyMusicKitToPlayer(player, logFailures);
            return;
        }

        _activeSteamIds.Add(steamId);
        LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures);
    }

    public void EnsureMusicKitWhenProfileReady(CCSPlayerController player, bool logFailures = false)
    {
        if (_disposed || !TryGetSteamId64(player, out var steamId))
        {
            return;
        }

        if (!_profiles.TryGetValue(steamId, out var profile))
        {
            _activeSteamIds.Add(steamId);
            LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures);
            return;
        }

        // Runs every tick. The write side compares before sending, so this is
        // a handful of field reads per player unless Valve reset something.
        var (kitId, mvpCount) = ResolveMusicKitState(player, profile);
        ApplyMusicKitState(player, kitId, mvpCount, logFailures);
    }

    // While possessing a bot the controller's PlayerPawn still points at the
    // player's own (dead) pawn; the possessed body is in Pawn instead.
    public void ApplyToPossessedPawnWhenProfileReady(CCSPlayerController player, bool logFailures = false)
    {
        if (_disposed || !TryGetSteamId64(player, out var steamId))
        {
            return;
        }

        if (!_loadedProfiles.Contains(steamId))
        {
            _activeSteamIds.Add(steamId);
            LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures);
            return;
        }

        var possessed = player.Pawn.Value;
        if (possessed is null || !possessed.IsValid)
        {
            return;
        }

        var pawn = new CCSPlayerPawn(possessed.Handle);
        var profile = GetProfile(player);
        ApplyWeapons(player, pawn, profile, logFailures);
        ApplyGloves(player, pawn, profile, logFailures);
        ApplyAgent(player, pawn, profile, logFailures);
        ApplyMusicKitToPlayer(player, logFailures);
    }

    public void PreloadProfile(CCSPlayerController player)
    {
        if (_disposed || !TryGetSteamId64(player, out var steamId) || _profiles.ContainsKey(steamId))
        {
            return;
        }

        _activeSteamIds.Add(steamId);
        LoadProfileInBackground(steamId, applyAfterLoad: false, logFailures: false);
    }

    public void PreloadProfile(ulong steamId64)
    {
        if (_disposed || steamId64 == 0 || _profiles.ContainsKey(steamId64))
        {
            return;
        }

        _activeSteamIds.Add(steamId64);
        LoadProfileInBackground(steamId64, applyAfterLoad: false, logFailures: false);
    }

    public bool SetWeaponSkin(CCSPlayerController player, string weaponEntity, string cosmeticId)
    {
        if (!CanUseWeapons(player) || !Catalog.WeaponSkinsById.TryGetValue(cosmeticId, out var skin) || !CanUse(player, skin))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        profile.WeaponSkins[weaponEntity] = cosmeticId;
        QueueStorageWrite($"weapon skin {cosmeticId} ({weaponEntity}) for {steamId}", () => _storage.SaveWeaponSkin(steamId, weaponEntity, cosmeticId));
        ApplyWeaponSelection(player, weaponEntity, skin, logFailures: true);
        return true;
    }

    public bool SetKnifeSkin(CCSPlayerController player, string cosmeticId)
    {
        if (!CanUseKnives(player) || !Catalog.KnifeSkinsById.TryGetValue(cosmeticId, out var skin) || !CanUse(player, skin))
        {
            return false;
        }

        var knife = Catalog.Knives.FirstOrDefault(k => k.ItemDefinitionIndex == skin.ItemDefinitionIndex);
        if (knife is not null && !CanUse(player, knife))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        profile.KnifeSkinId = cosmeticId;
        QueueStorageWrite($"knife skin {cosmeticId} for {steamId}", () => _storage.SaveKnifeSkin(steamId, cosmeticId));
        if (knife is not null)
        {
            profile.KnifeId = knife.Id;
            var knifeId = knife.Id;
            QueueStorageWrite($"knife type {knifeId} for {steamId}", () => _storage.SaveKnifeType(steamId, knifeId));
        }

        ApplyKnifeSelection(player, skin, logFailures: true);
        return true;
    }

    public bool SetKnifeType(CCSPlayerController player, string knifeId)
    {
        var knife = Catalog.Knives.FirstOrDefault(k => k.Id.Equals(knifeId, StringComparison.OrdinalIgnoreCase));
        if (!CanUseKnives(player) || knife is null || !CanUse(player, knife))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        profile.KnifeId = knife.Id;
        var selectedKnifeId = knife.Id;
        QueueStorageWrite($"knife type {selectedKnifeId} for {steamId}", () => _storage.SaveKnifeType(steamId, selectedKnifeId));
        ApplyKnifeTypeSelection(player, knife, logFailures: true);
        return true;
    }

    public bool SetGloveSkin(CCSPlayerController player, string cosmeticId)
    {
        if (!CanUseGloves(player) || !Catalog.GloveSkinsById.TryGetValue(cosmeticId, out var glove) || !CanUse(player, glove))
        {
            return false;
        }

        var gloveType = FindGloveType(glove);
        if (gloveType is not null && !CanUse(player, gloveType))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        profile.GloveSkinId = cosmeticId;
        QueueStorageWrite($"glove skin {cosmeticId} for {steamId}", () => _storage.SaveGloveSkin(steamId, cosmeticId));
        ApplyGloveSelection(player, glove, logFailures: true);
        return true;
    }

    public bool SetAgent(CCSPlayerController player, string team, string agentId)
    {
        var normalizedTeam = NormalizeAgentTeam(team);
        if (!CanUseAgents(player) ||
            normalizedTeam is not "t" and not "ct" ||
            !Catalog.AgentsById.TryGetValue(agentId, out var agent) ||
            !agent.Team.Equals(normalizedTeam, StringComparison.OrdinalIgnoreCase) ||
            !CanUse(player, agent))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        profile.AgentIdsByTeam[normalizedTeam] = agent.Id;
        var agentIdToSave = agent.Id;
        QueueStorageWrite($"agent {agentIdToSave} ({normalizedTeam}) for {steamId}", () => _storage.SaveAgent(steamId, normalizedTeam, agentIdToSave));
        ApplyAgentSelection(player, agent, logFailures: true);
        return true;
    }

    // The "Default" rows of the menu. Each drops the saved selection and puts
    // the stock item back right away; stickers, charms, name tags and counters
    // saved for the item stay and are painted on the stock finish. Clearing
    // never needs the module flag: a player who lost it can still clean up.
    // Before the profile has loaded there is nothing to clear yet, and a
    // merge landing afterwards would bring the stored value back, so the rows
    // do nothing until then.
    public bool ClearWeaponSkin(CCSPlayerController player, string weaponEntity)
    {
        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!_loadedProfiles.Contains(steamId))
        {
            return false;
        }

        // The stored row goes even when memory already had nothing: a
        // selection pruned because its entry left the catalog would otherwise
        // come back with the entry.
        QueueStorageWrite($"weapon skin reset ({weaponEntity}) for {steamId}", () => _storage.ClearSelection(steamId, "weapon", weaponEntity));
        if (!profile.WeaponSkins.Remove(weaponEntity))
        {
            return false;
        }

        ReapplyTarget(player, profile, weaponEntity, clearWhenBare: true);
        return true;
    }

    // Both the knife type and its skin: back to the knife the game hands out.
    public bool ClearKnife(CCSPlayerController player)
    {
        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!_loadedProfiles.Contains(steamId))
        {
            return false;
        }

        QueueStorageWrite($"knife reset for {steamId}", () =>
        {
            _storage.ClearSelection(steamId, "knife_type", KnifeTarget);
            _storage.ClearSelection(steamId, "knife", KnifeTarget);
        });
        if (profile.KnifeId is null && profile.KnifeSkinId is null)
        {
            return false;
        }

        profile.KnifeId = null;
        profile.KnifeSkinId = null;
        ReapplyTarget(player, profile, KnifeTarget, clearWhenBare: true);
        return true;
    }

    // Only the finish: the selected knife type stays, on its stock look.
    public bool ClearKnifeSkin(CCSPlayerController player)
    {
        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!_loadedProfiles.Contains(steamId))
        {
            return false;
        }

        QueueStorageWrite($"knife skin reset for {steamId}", () => _storage.ClearSelection(steamId, "knife", KnifeTarget));
        if (profile.KnifeSkinId is null)
        {
            return false;
        }

        // Rows from before the type was stored alongside the skin only carry
        // the skin; keep the knife it implies, as the menu showed it.
        if (profile.KnifeId is null &&
            Catalog.KnifeSkinsById.TryGetValue(profile.KnifeSkinId, out var oldSkin) &&
            Catalog.Knives.FirstOrDefault(k => k.ItemDefinitionIndex == oldSkin.ItemDefinitionIndex) is { } impliedKnife)
        {
            profile.KnifeId = impliedKnife.Id;
            var knifeId = impliedKnife.Id;
            QueueStorageWrite($"knife type {knifeId} for {steamId}", () => _storage.SaveKnifeType(steamId, knifeId));
        }

        profile.KnifeSkinId = null;
        ReapplyTarget(player, profile, KnifeTarget, clearWhenBare: true);
        return true;
    }

    public bool ClearGloveSkin(CCSPlayerController player)
    {
        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!_loadedProfiles.Contains(steamId))
        {
            return false;
        }

        QueueStorageWrite($"glove skin reset for {steamId}", () => _storage.ClearSelection(steamId, "glove", GloveTarget));
        if (profile.GloveSkinId is null)
        {
            return false;
        }

        profile.GloveSkinId = null;
        if (TryGetPawn(player, out var pawn, logFailures: true))
        {
            ClearGloveCosmetic(player, pawn!);
        }

        return true;
    }

    // The default agent model comes back on the next spawn, like a reset.
    public bool ClearAgent(CCSPlayerController player, string team)
    {
        var normalizedTeam = NormalizeAgentTeam(team);
        if (normalizedTeam is not "t" and not "ct")
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!_loadedProfiles.Contains(steamId))
        {
            return false;
        }

        QueueStorageWrite($"agent reset ({normalizedTeam}) for {steamId}", () => _storage.ClearSelection(steamId, "agent", normalizedTeam));
        return profile.AgentIdsByTeam.Remove(normalizedTeam);
    }

    public static string StickerTarget(string weaponEntity, int slot)
    {
        return $"{weaponEntity}:{slot.ToString(CultureInfo.InvariantCulture)}";
    }

    public bool SetSticker(CCSPlayerController player, string weaponEntity, int slot, string stickerId)
    {
        if (slot is < 0 or >= StickerSlots ||
            !Catalog.WeaponsByEntity.ContainsKey(weaponEntity) ||
            !Catalog.StickersById.TryGetValue(stickerId, out var sticker) ||
            !CanUseStickers(player) ||
            !CanUse(player, sticker))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!profile.Stickers.TryGetValue(weaponEntity, out var slots))
        {
            slots = new Dictionary<int, string>();
            profile.Stickers[weaponEntity] = slots;
        }

        slots[slot] = stickerId;
        var target = StickerTarget(weaponEntity, slot);
        QueueStorageWrite($"sticker {stickerId} ({target}) for {steamId}", () => _storage.SaveCustomization(steamId, "sticker", target, stickerId));
        BumpStickerWear(steamId, profile, weaponEntity);
        ReapplyTarget(player, profile, weaponEntity);
        return true;
    }

    // Removing never needs the flag: a player who lost it can still clean up.
    public bool ClearSticker(CCSPlayerController player, string weaponEntity, int slot)
    {
        var profile = GetProfile(player);
        if (!profile.Stickers.TryGetValue(weaponEntity, out var slots) || !slots.Remove(slot))
        {
            return false;
        }

        if (slots.Count == 0)
        {
            profile.Stickers.Remove(weaponEntity);
        }

        var steamId = GetSteamId64(player);
        var target = StickerTarget(weaponEntity, slot);
        QueueStorageWrite($"sticker reset ({target}) for {steamId}", () => _storage.ClearCustomization(steamId, "sticker", target));
        BumpStickerWear(steamId, profile, weaponEntity);
        ReapplyTarget(player, profile, weaponEntity, clearWhenBare: true);
        return true;
    }

    public bool SetKeychain(CCSPlayerController player, string weaponEntity, string keychainId)
    {
        if (!Catalog.WeaponsByEntity.ContainsKey(weaponEntity) ||
            !Catalog.KeychainsById.TryGetValue(keychainId, out var keychain) ||
            !CanUseKeychains(player) ||
            !CanUse(player, keychain))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        profile.Keychains[weaponEntity] = keychainId;
        QueueStorageWrite($"keychain {keychainId} ({weaponEntity}) for {steamId}", () => _storage.SaveCustomization(steamId, "keychain", weaponEntity, keychainId));
        ReapplyTarget(player, profile, weaponEntity);
        return true;
    }

    public bool ClearKeychain(CCSPlayerController player, string weaponEntity)
    {
        var profile = GetProfile(player);
        if (!profile.Keychains.Remove(weaponEntity))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        QueueStorageWrite($"keychain reset ({weaponEntity}) for {steamId}", () => _storage.ClearCustomization(steamId, "keychain", weaponEntity));
        ReapplyTarget(player, profile, weaponEntity, clearWhenBare: true);
        return true;
    }

    public bool SetMusicKit(CCSPlayerController player, string cosmeticId)
    {
        if (!CanUseMusicKits(player) || !Catalog.MusicKitsById.TryGetValue(cosmeticId, out var kit) || !CanUse(player, kit))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        profile.MusicKitId = kit.Id;
        QueueStorageWrite($"music kit {kit.Id} for {steamId}", () => _storage.SaveCustomization(steamId, "music_kit", "music", kit.Id));
        ApplyMusicKitToPlayer(player, logFailures: true);
        return true;
    }

    public bool ClearMusicKit(CCSPlayerController player)
    {
        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!string.IsNullOrWhiteSpace(profile.MusicKitId))
        {
            profile.MusicKitId = null;
            QueueStorageWrite($"music kit reset for {steamId}", () => _storage.ClearCustomization(steamId, "music_kit", "music"));
        }

        ApplyMusicKitToPlayer(player, logFailures: true);
        return true;
    }

    public void ApplyMusicKitToPlayer(CCSPlayerController player, bool logFailures = false)
    {
        try
        {
            var profile = GetProfile(player);
            var (kitId, mvpCount) = ResolveMusicKitState(player, profile);
            ApplyMusicKitState(player, kitId, mvpCount, logFailures);
        }
        catch (Exception ex)
        {
            if (logFailures)
            {
                _logger.LogWarning(ex, "Astra Skins failed to resolve music kit for {SteamId}.", TryGetSteamId64(player, out var steamId) ? steamId : 0);
            }
        }
    }

    // A kit whose flag the player lost resolves to 0: it stops applying on the
    // next reconcile while the selection stays saved for when the flag returns.
    private (int KitId, int MvpCount) ResolveMusicKitState(CCSPlayerController player, PlayerSkinProfile profile)
    {
        var kitId = 0;
        if (CanUseMusicKits(player) && !string.IsNullOrWhiteSpace(profile.MusicKitId))
        {
            if (Catalog.MusicKitsById.TryGetValue(profile.MusicKitId!, out var kit))
            {
                kitId = CanUse(player, kit) ? kit.MusicKit : 0;
            }
            else if (int.TryParse(profile.MusicKitId, out var parsed))
            {
                // Tolerate raw numeric ids stored outside of the catalog.
                kitId = parsed;
            }
        }

        var mvpCount = 0;
        if (kitId > 0 && profile.MusicKitMvpCounts.TryGetValue(kitId, out var storedCount))
        {
            mvpCount = Math.Max(0, storedCount);
        }

        return (kitId, mvpCount);
    }

    // Valve's own value for a player without a kit is 1, the stock kit. A kit
    // of 0 means "nothing selected" for us: players we painted go back to the
    // stock kit, everyone else is left alone so a real kit is never overwritten.
    private const int DefaultMusicKitId = 1;

    private void ApplyMusicKitState(CCSPlayerController player, int kitId, int mvpCount, bool logFailures)
    {
        if (!TryGetSteamId64(player, out var steamId))
        {
            return;
        }

        if (kitId <= 0)
        {
            if (_appliedMusicKits.Remove(steamId))
            {
                WriteMusicKitState(player, DefaultMusicKitId, 0, logFailures);
            }

            return;
        }

        WriteMusicKitState(player, kitId, mvpCount, logFailures);
        _appliedMusicKits[steamId] = kitId;
    }

    // The client plays wait/intro from m_pInventoryServices.m_unMusicID.
    // Flag that pointer or the value stays server-side. Only dirty fields
    // that actually changed so the per-tick reconcile does not resend.
    private void WriteMusicKitState(CCSPlayerController player, int kitId, int mvpCount, bool logFailures)
    {
        try
        {
            var inventory = player.InventoryServices;
            var inventoryKitId = checked((ushort)Math.Clamp(kitId, 0, ushort.MaxValue));
            if (inventory is not null && inventory.MusicID != inventoryKitId)
            {
                inventory.MusicID = inventoryKitId;
                Utilities.SetStateChanged(player, "CCSPlayerController", "m_pInventoryServices");
            }

            if (player.MusicKitID != kitId)
            {
                player.MusicKitID = kitId;
                Utilities.SetStateChanged(player, "CCSPlayerController", "m_iMusicKitID");
            }

            var clampedMvpCount = Math.Max(0, mvpCount);
            if (player.MusicKitMVPs != clampedMvpCount)
            {
                player.MusicKitMVPs = clampedMvpCount;
                Utilities.SetStateChanged(player, "CCSPlayerController", "m_iMusicKitMVPs");
            }

            if (player.MvpNoMusic)
            {
                player.MvpNoMusic = false;
                Utilities.SetStateChanged(player, "CCSPlayerController", "m_bMvpNoMusic");
            }
        }
        catch (Exception ex)
        {
            if (logFailures)
            {
                _logger.LogWarning(ex, "Astra Skins failed to apply music kit for {SteamId}.", TryGetSteamId64(player, out var steamId) ? steamId : 0);
            }
        }
    }

    public bool TryGetSelectedMusicKitId(CCSPlayerController player, out int musicKitId)
    {
        (musicKitId, _) = ResolveMusicKitState(player, GetProfile(player));
        return musicKitId > 0;
    }

    public int RecordMusicKitMvp(CCSPlayerController player, int musicKitId)
    {
        if (!TryGetSteamId64(player, out var steamId))
        {
            return 0;
        }

        // The controller is authoritative after the selected kit has been applied;
        // the event value can refer to the kit used before a selection changed.
        if (player.MusicKitID > 0)
        {
            musicKitId = player.MusicKitID;
        }

        if (musicKitId <= 0)
        {
            return 0;
        }

        var profile = GetProfile(player);
        var currentCount = profile.MusicKitMvpCounts.TryGetValue(musicKitId, out var storedCount)
            ? Math.Max(0, storedCount)
            : 0;
        var nextCount = currentCount == int.MaxValue ? int.MaxValue : currentCount + 1;
        profile.MusicKitMvpCounts[musicKitId] = nextCount;
        // Only touch the controller for the kit this plugin applies. A kit
        // Valve put there stays Valve's; the count is just remembered in case
        // the player selects that kit here later.
        if (ResolveMusicKitState(player, profile).KitId == musicKitId)
        {
            ApplyMusicKitState(player, musicKitId, nextCount, logFailures: true);
        }

        QueueStorageWrite($"music kit MVP {musicKitId} for {steamId}", () => _storage.IncrementMusicKitMvp(steamId, musicKitId));
        return nextCount;
    }

    public void Reset(CCSPlayerController player)
    {
        var steamId = GetSteamId64(player);
        BumpProfileEpoch(steamId);
        QueueStorageWrite($"profile reset for {steamId}", () => _storage.ResetProfile(steamId));
        var stockPaintedWeapons = _profiles.TryGetValue(steamId, out var profile) ? StockPaintedWeapons(player, profile) : null;
        if (profile is not null)
        {
            // Queued after the row wipe, so the steps come back bumped and
            // the next skin on these guns is not built from a stale finish.
            BumpStickerWearForRenderedStickers(player, steamId, profile);
        }

        _profiles.Remove(steamId);
        _loadedProfiles.Remove(steamId);
        _applyAfterLoadRequests.Remove(steamId);
        ClearPlayerCosmetics(player, logFailures: true, stockPaintedWeapons);
        ApplyMusicKitState(player, 0, 0, logFailures: true);
    }

    // Guns painted on the stock finish: stickers or a charm that actually
    // reached the weapon (feature on, flags held, ids known), a name tag or a
    // counter. Their paint kit is 0, so a reset has to be told to re-create
    // them too. A stored attachment that never applied leaves the gun alone.
    private HashSet<string> StockPaintedWeapons(CCSPlayerController player, PlayerSkinProfile profile)
    {
        var weapons = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        foreach (var weaponEntity in profile.Stickers.Keys.Concat(profile.Keychains.Keys))
        {
            if (HasUsableAttachments(player, profile, weaponEntity))
            {
                weapons.Add(weaponEntity);
            }
        }

        foreach (var target in profile.Customizations.Keys)
        {
            if (target is not KnifeTarget and not GloveTarget && HasVisibleCustomization(profile, target))
            {
                weapons.Add(target);
            }
        }

        return weapons;
    }

    // Admin reset for a player who is not connected: drop storage and cache so
    // the next read starts clean. Connected players go through the pawn-aware
    // Reset/ResetCategory instead.
    public bool ResetStored(ulong steamId64, string category)
    {
        if (_disposed || steamId64 == 0)
        {
            return false;
        }

        var all = category is "all" or "*";
        var normalized = all ? null : NormalizeResetCategory(category);
        if (!all && normalized is null)
        {
            return false;
        }

        BumpProfileEpoch(steamId64);
        _profiles.Remove(steamId64);
        _loadedProfiles.Remove(steamId64);
        _applyAfterLoadRequests.Remove(steamId64);
        if (all)
        {
            QueueStorageWrite($"admin profile reset for {steamId64}", () => _storage.ResetProfile(steamId64));
        }
        else
        {
            QueueStorageWrite($"admin category reset ({normalized}) for {steamId64}", () => _storage.ResetCategory(steamId64, normalized!));
        }

        return true;
    }

    public bool ResetCategory(CCSPlayerController player, string category)
    {
        var normalized = NormalizeResetCategory(category);
        if (normalized is null)
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        BumpProfileEpoch(steamId);
        QueueStorageWrite($"category reset ({normalized}) for {steamId}", () => _storage.ResetCategory(steamId, normalized));

        var profile = GetProfile(player);
        switch (normalized)
        {
            case "weapons":
                var stockPaintedWeapons = StockPaintedWeapons(player, profile);
                BumpStickerWearForRenderedStickers(player, steamId, profile);
                profile.WeaponSkins.Clear();
                profile.Stickers.Clear();
                profile.Keychains.Clear();
                foreach (var customizationTarget in profile.Customizations.Keys.ToArray())
                {
                    if (customizationTarget is not KnifeTarget and not GloveTarget)
                    {
                        profile.Customizations.Remove(customizationTarget);
                    }
                }
                ClearWeaponCosmetics(player, includeKnives: false, logFailures: true, alsoReplace: stockPaintedWeapons);
                break;
            case "stickers":
                var stickerWeapons = profile.Stickers.Keys
                    .Where(weaponEntity => ResolveUsableStickers(player, profile, weaponEntity) is not null)
                    .ToArray();
                BumpStickerWearForRenderedStickers(player, steamId, profile);
                profile.Stickers.Clear();
                ReapplyWeapons(player, profile, stickerWeapons);
                break;
            case "keychains":
                var keychainWeapons = profile.Keychains.Keys
                    .Where(weaponEntity => ResolveUsableKeychain(player, profile, weaponEntity) is not null)
                    .ToArray();
                profile.Keychains.Clear();
                ReapplyWeapons(player, profile, keychainWeapons);
                break;
            case "knife":
                profile.KnifeId = null;
                profile.KnifeSkinId = null;
                profile.Customizations.Remove(KnifeTarget);
                ClearWeaponCosmetics(player, includeKnives: true, onlyKnives: true, logFailures: true);
                break;
            case "gloves":
                profile.GloveSkinId = null;
                profile.Customizations.Remove(GloveTarget);
                if (TryGetPawn(player, out var glovePawn, logFailures: true))
                {
                    ClearGloveCosmetic(player, glovePawn!);
                }
                break;
            case "agents":
                profile.AgentIdsByTeam.Clear();
                break;
            case "music":
                profile.MusicKitId = null;
                profile.MusicKitMvpCounts.Clear();
                ApplyMusicKitToPlayer(player, logFailures: true);
                break;
        }

        return true;
    }

    public void ApplyToPlayer(CCSPlayerController player, bool logFailures = false)
    {
        if (!IsUsablePlayer(player))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply cosmetics: player is invalid.");
            }

            return;
        }

        // Music kits are controller-level state and do not require a spawned
        // pawn. Apply them before the pawn guard so first team selection and
        // warmup profile loads cannot skip the music kit entirely.
        ApplyMusicKitToPlayer(player, logFailures);
        ApplyTeamPreviewCosmetics(player, logFailures);

        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return;
        }

        var profile = GetProfile(player);
        ApplyWeapons(player, pawn!, profile, logFailures);
        ApplyGloves(player, pawn!, profile, logFailures);
        ApplyAgent(player, pawn!, profile, logFailures);
    }

    // Preview slots keep their Xuid for a while (team select at connect, the
    // whole intro), so remember which owner each slot was painted for and only
    // write again when it changes. Keyed by entity index, cleared on map start.
    private readonly Dictionary<uint, ulong> _teamPreviewPaintedFor = new();
    // The preview slots are map entities, so keep their handles instead of
    // scanning the entity list every tick; rescan at most once a second when
    // the cache is empty or stale.
    private readonly List<CCSGO_TeamPreviewCharacterPosition> _teamPreviewEntities = new();
    private DateTime _nextTeamPreviewScanUtc = DateTime.MinValue;

    public void ResetTeamPreviewTracking()
    {
        _teamPreviewPaintedFor.Clear();
        _teamPreviewEntities.Clear();
        _nextTeamPreviewScanUtc = DateTime.MinValue;
    }

    // Runs every tick: the team select screen renders the preview the moment
    // it opens, so the write has to land on the same tick Valve assigns the
    // owner. Cheap because it only reads one field per cached entity.
    public void ReconcileTeamPreview()
    {
        if (_disposed)
        {
            return;
        }

        try
        {
            if (_teamPreviewEntities.Count == 0 || _teamPreviewEntities.Any(p => !p.IsValid))
            {
                var now = DateTime.UtcNow;
                if (now < _nextTeamPreviewScanUtc)
                {
                    return;
                }

                _nextTeamPreviewScanUtc = now.AddSeconds(1);
                _teamPreviewEntities.Clear();
                _teamPreviewEntities.AddRange(EnumerateTeamPreviewPositions());
                if (_teamPreviewEntities.Count == 0)
                {
                    return;
                }
            }

            foreach (var preview in _teamPreviewEntities)
            {
                var xuid = preview.Xuid;
                if (xuid == 0)
                {
                    _teamPreviewPaintedFor.Remove(preview.Index);
                    continue;
                }

                if (_teamPreviewPaintedFor.TryGetValue(preview.Index, out var paintedFor) && paintedFor == xuid)
                {
                    continue;
                }

                ApplyTeamPreviewToPosition(preview, null, logFailures: false);
            }
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to reconcile team preview entities.");
        }
    }

    // Team intro / team select read CCSGO_TeamPreviewCharacterPosition, not the
    // live pawn. Only write slots whose Xuid matches a human we own.
    public void ApplyTeamPreviewCosmetics(CCSPlayerController? player = null, bool logFailures = false)
    {
        if (_disposed)
        {
            return;
        }

        if (player is not null && !IsUsablePlayer(player))
        {
            return;
        }

        try
        {
            foreach (var preview in EnumerateTeamPreviewPositions())
            {
                ApplyTeamPreviewToPosition(preview, player, logFailures);
            }
        }
        catch (Exception ex)
        {
            if (logFailures)
            {
                _logger.LogWarning(ex, "Astra Skins failed to enumerate team preview entities.");
            }
        }
    }

    public void ApplyAgentToPlayer(CCSPlayerController player, bool logFailures = false, bool loadIfMissing = true)
    {
        if (!IsUsablePlayer(player) || !TryGetPawn(player, out var pawn, logFailures))
        {
            return;
        }

        if (!TryGetSteamId64(player, out var steamId))
        {
            return;
        }

        if (!_profiles.TryGetValue(steamId, out var profile))
        {
            if (loadIfMissing)
            {
                // Apply once the profile lands so the player does not stay on
                // defaults for the round the read raced against.
                _activeSteamIds.Add(steamId);
                LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures);
            }

            return;
        }

        ApplyAgent(player, pawn!, profile, logFailures);
    }

    public bool ApplyToWeapon(CCSPlayerController player, CBasePlayerWeapon weapon, bool logFailures = false)
    {
        if (_disposed)
        {
            return false;
        }

        if (!IsUsablePlayer(player))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply weapon cosmetic: player is invalid.");
            }

            return false;
        }

        if (weapon is null || !weapon.IsValid)
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply weapon cosmetic for player {SteamId}: weapon is invalid.", player.SteamID);
            }

            return false;
        }

        if (!TryGetSteamId64(player, out var steamId) || !_profiles.ContainsKey(steamId))
        {
            if (TryGetSteamId64(player, out steamId))
            {
                _activeSteamIds.Add(steamId);
                LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures);
            }

            return false;
        }

        return ApplyMatchingWeapon(player, weapon, GetProfile(player), logFailures);
    }

    // Apply side of the permission rule. Menu, search and selection already
    // filter on CanUse; a saved selection whose flag the player lost has to
    // stop applying too. The selection itself stays stored and comes back as
    // soon as the flag does. A flag on a knife or glove type covers its skins.
    private CosmeticEntry? ResolveUsableWeaponSkin(CCSPlayerController player, PlayerSkinProfile profile, string weaponEntity)
    {
        if (!CanUseWeapons(player) ||
            !profile.WeaponSkins.TryGetValue(weaponEntity, out var cosmeticId) ||
            !Catalog.WeaponSkinsById.TryGetValue(cosmeticId, out var skin))
        {
            return null;
        }

        return CanUse(player, skin) ? skin : null;
    }

    private CosmeticEntry? ResolveUsableKnifeSkin(CCSPlayerController player, PlayerSkinProfile profile)
    {
        if (!CanUseKnives(player) ||
            profile.KnifeSkinId is null ||
            !Catalog.KnifeSkinsById.TryGetValue(profile.KnifeSkinId, out var skin) ||
            !KnifeSkinMatchesSelectedKnife(profile, skin) ||
            !CanUse(player, skin))
        {
            return null;
        }

        var knife = Catalog.Knives.FirstOrDefault(k => k.ItemDefinitionIndex == skin.ItemDefinitionIndex);
        return knife is null || CanUse(player, knife) ? skin : null;
    }

    private KnifeDefinition? ResolveUsableKnifeType(CCSPlayerController player, PlayerSkinProfile profile)
    {
        if (!CanUseKnives(player) || profile.KnifeId is null)
        {
            return null;
        }

        var knife = Catalog.Knives.FirstOrDefault(k => k.Id.Equals(profile.KnifeId, StringComparison.OrdinalIgnoreCase));
        return knife is not null && CanUse(player, knife) ? knife : null;
    }

    private CosmeticEntry? ResolveUsableGloveSkin(CCSPlayerController player, PlayerSkinProfile profile, bool logFailures)
    {
        if (!CanUseGloves(player) || profile.GloveSkinId is null)
        {
            return null;
        }

        if (!Catalog.GloveSkinsById.TryGetValue(profile.GloveSkinId, out var glove))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins glove selection {CosmeticId} is not present in loaded definitions for player {SteamId}.", profile.GloveSkinId, player.SteamID);
            }

            return null;
        }

        if (!CanUse(player, glove))
        {
            return null;
        }

        var gloveType = FindGloveType(glove);
        return gloveType is null || CanUse(player, gloveType) ? glove : null;
    }

    private AgentDefinition? ResolveUsableAgent(CCSPlayerController player, PlayerSkinProfile profile, string? team, bool logFailures)
    {
        if (!CanUseAgents(player) || string.IsNullOrWhiteSpace(team) || !profile.AgentIdsByTeam.TryGetValue(team, out var agentId))
        {
            return null;
        }

        if (!Catalog.AgentsById.TryGetValue(agentId, out var agent))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins agent selection {AgentId} is not present in loaded definitions for player {SteamId}.", agentId, player.SteamID);
            }

            return null;
        }

        if (!agent.Team.Equals(team, StringComparison.OrdinalIgnoreCase))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins agent {AgentId} does not match player team {Team} for player {SteamId}.", agent.Id, team, player.SteamID);
            }

            return null;
        }

        return CanUse(player, agent) ? agent : null;
    }

    // Apply side for attachments: the feature switch and its flag first, then
    // each entry's own flag; an entry missing from the catalog is skipped.
    private IReadOnlyList<StickerAttachment>? ResolveUsableStickers(CCSPlayerController player, PlayerSkinProfile profile, string weaponEntity)
    {
        if (!profile.Stickers.TryGetValue(weaponEntity, out var slots) || slots.Count == 0 || !CanUseStickers(player))
        {
            return null;
        }

        List<StickerAttachment>? result = null;
        foreach (var (slot, stickerId) in slots)
        {
            if (slot is < 0 or >= StickerSlots ||
                !Catalog.StickersById.TryGetValue(stickerId, out var sticker) ||
                !CanUse(player, sticker))
            {
                continue;
            }

            (result ??= new List<StickerAttachment>()).Add(new StickerAttachment(slot, sticker.StickerId));
        }

        return result;
    }

    private int? ResolveUsableKeychain(CCSPlayerController player, PlayerSkinProfile profile, string weaponEntity)
    {
        if (!profile.Keychains.TryGetValue(weaponEntity, out var keychainId) ||
            !CanUseKeychains(player) ||
            !Catalog.KeychainsById.TryGetValue(keychainId, out var keychain) ||
            !CanUse(player, keychain))
        {
            return null;
        }

        return keychain.KeychainId;
    }

    private bool HasUsableAttachments(CCSPlayerController player, PlayerSkinProfile profile, string weaponEntity)
    {
        return ResolveUsableStickers(player, profile, weaponEntity) is not null ||
               ResolveUsableKeychain(player, profile, weaponEntity) is not null;
    }

    // What to paint on a gun: the selected skin, or the stock finish when only
    // stickers, a charm, a name tag or a counter are on it. Null leaves the gun
    // alone.
    private CosmeticEntry? ResolveWeaponPaint(CCSPlayerController player, PlayerSkinProfile profile, string weaponEntity)
    {
        return ResolveUsableWeaponSkin(player, profile, weaponEntity)
               ?? (HasUsableAttachments(player, profile, weaponEntity) || HasVisibleCustomization(profile, weaponEntity)
                   ? VanillaEntry(weaponEntity)
                   : null);
    }

    // The client keeps one composited first-person finish per paint kit, seed
    // and wear (wear rounded to coarse steps) for the whole game session, and
    // that finish ignores later sticker changes: a gun whose finish was built
    // without a sticker keeps showing none in hand until the wear moves to a
    // value the client has not built yet (the dropped gun is built fresh and
    // does show them). So every sticker change on a gun steps its wear by
    // 0.006, cycling through ten steps (0.06 at most, invisible on the
    // finish). The step count lives in the profile so it survives reconnects
    // and restarts; a gun that never had stickers keeps its exact wear.
    private const float StickerWearStep = 0.006f;
    private const int StickerWearStepCount = 10;
    private const string StickerWearField = "sticker_wear";

    private void BumpStickerWear(ulong steamId, PlayerSkinProfile profile, string weaponEntity)
    {
        var steps = profile.StickerWearSteps.TryGetValue(weaponEntity, out var current)
            ? current % StickerWearStepCount + 1
            : 1;
        profile.StickerWearSteps[weaponEntity] = steps;
        var stored = steps.ToString(CultureInfo.InvariantCulture);
        QueueStorageWrite($"sticker wear step {stored} ({weaponEntity}) for {steamId}", () => _storage.SaveCustomization(steamId, StickerWearField, weaponEntity, stored));
    }

    private void BumpStickerWearForRenderedStickers(CCSPlayerController player, ulong steamId, PlayerSkinProfile profile)
    {
        foreach (var weaponEntity in profile.Stickers.Keys.ToArray())
        {
            if (ResolveUsableStickers(player, profile, weaponEntity) is not null)
            {
                BumpStickerWear(steamId, profile, weaponEntity);
            }
        }
    }

    private float AdjustWearForStickers(CCSPlayerController player, PlayerSkinProfile profile, string weaponEntity, float wear, bool hasStickers)
    {
        if (!profile.StickerWearSteps.TryGetValue(weaponEntity, out var steps))
        {
            if (!hasStickers)
            {
                return wear;
            }

            // Stickers saved before the step existed: start it now so the
            // finish is built with them.
            if (!TryGetSteamId64(player, out var steamId))
            {
                return wear;
            }

            BumpStickerWear(steamId, profile, weaponEntity);
            steps = profile.StickerWearSteps[weaponEntity];
        }

        var offset = steps * StickerWearStep;
        return wear + offset <= 1f ? wear + offset : Math.Max(0f, wear - offset);
    }

    private CosmeticEntry VanillaEntry(string weaponEntity)
    {
        if (!_vanillaEntries.TryGetValue(weaponEntity, out var entry))
        {
            entry = new CosmeticEntry { Id = $"{weaponEntity}:0", DisplayName = "Vanilla", PaintKit = 0, Seed = 0, Wear = 0f, LegacyModel = false };
            _vanillaEntries[weaponEntity] = entry;
        }

        return entry;
    }

    private GloveDefinition? FindGloveType(CosmeticEntry glove)
    {
        return glove.ItemDefinitionIndex.HasValue
            ? Catalog.Gloves.FirstOrDefault(g => g.ItemDefinitionIndex == glove.ItemDefinitionIndex.Value)
            : null;
    }

    public bool CanUse(CCSPlayerController player, CosmeticEntry entry)
    {
        return string.IsNullOrWhiteSpace(entry.Permission) || AdminManager.PlayerHasPermissions(player, entry.Permission);
    }

    public bool CanUse(CCSPlayerController player, KnifeDefinition entry)
    {
        return string.IsNullOrWhiteSpace(entry.Permission) || AdminManager.PlayerHasPermissions(player, entry.Permission);
    }

    public bool CanUse(CCSPlayerController player, GloveDefinition entry)
    {
        return string.IsNullOrWhiteSpace(entry.Permission) || AdminManager.PlayerHasPermissions(player, entry.Permission);
    }

    public bool CanUse(CCSPlayerController player, AgentDefinition entry)
    {
        return string.IsNullOrWhiteSpace(entry.Permission) || AdminManager.PlayerHasPermissions(player, entry.Permission);
    }

    public bool CanUse(CCSPlayerController player, MusicKitDefinition entry)
    {
        return string.IsNullOrWhiteSpace(entry.Permission) || AdminManager.PlayerHasPermissions(player, entry.Permission);
    }

    public bool CanUse(CCSPlayerController player, StickerDefinition entry)
    {
        return string.IsNullOrWhiteSpace(entry.Permission) || AdminManager.PlayerHasPermissions(player, entry.Permission);
    }

    public bool CanUse(CCSPlayerController player, KeychainDefinition entry)
    {
        return string.IsNullOrWhiteSpace(entry.Permission) || AdminManager.PlayerHasPermissions(player, entry.Permission);
    }

    // Feature switches: the section must be on and have data, and the section
    // flag (if any) is checked live like every other permission.
    // A module is available when its switch is on and its data file loaded
    // something; a player can use it when they also hold its flag (empty flag:
    // everyone). Menu, search, commands and the apply side all ask here.
    public bool WeaponsAvailable => _modules.Weapons.Enabled && Catalog.Weapons.Count > 0;

    public bool KnivesAvailable => _modules.Knives.Enabled && Catalog.Knives.Count > 0;

    public bool GlovesAvailable => _modules.Gloves.Enabled && Catalog.Gloves.Count > 0;

    public bool AgentsAvailable => _modules.Agents.Enabled && Catalog.Agents.Count > 0;

    public bool MusicKitsAvailable => _modules.MusicKits.Enabled && Catalog.MusicKits.Count > 0;

    public bool StickersAvailable => _modules.Stickers.Enabled && Catalog.Stickers.Count > 0;

    public bool KeychainsAvailable => _modules.Keychains.Enabled && Catalog.Keychains.Count > 0;

    public bool CanUseWeapons(CCSPlayerController player) => WeaponsAvailable && HoldsModuleFlag(player, _modules.Weapons);

    public bool CanUseKnives(CCSPlayerController player) => KnivesAvailable && HoldsModuleFlag(player, _modules.Knives);

    public bool CanUseGloves(CCSPlayerController player) => GlovesAvailable && HoldsModuleFlag(player, _modules.Gloves);

    public bool CanUseAgents(CCSPlayerController player) => AgentsAvailable && HoldsModuleFlag(player, _modules.Agents);

    public bool CanUseMusicKits(CCSPlayerController player) => MusicKitsAvailable && HoldsModuleFlag(player, _modules.MusicKits);

    public bool CanUseStickers(CCSPlayerController player) => StickersAvailable && HoldsModuleFlag(player, _modules.Stickers);

    public bool CanUseKeychains(CCSPlayerController player) => KeychainsAvailable && HoldsModuleFlag(player, _modules.Keychains);

    // Whether the menu has anything at all to show this player.
    public bool CanUseAnyModule(CCSPlayerController player)
    {
        return CanUseWeapons(player) || CanUseKnives(player) || CanUseGloves(player) || CanUseAgents(player) ||
               CanUseMusicKits(player) || CanUseStickers(player) || CanUseKeychains(player);
    }

    private static bool HoldsModuleFlag(CCSPlayerController player, ModuleConfig module)
    {
        return string.IsNullOrWhiteSpace(module.Permission) || AdminManager.PlayerHasPermissions(player, module.Permission);
    }

    // Names of the modules switched off in the config, for the load log.
    public IReadOnlyList<string> DisabledModules()
    {
        var names = new List<string>();
        if (!_modules.Weapons.Enabled) names.Add("weapons");
        if (!_modules.Knives.Enabled) names.Add("knives");
        if (!_modules.Gloves.Enabled) names.Add("gloves");
        if (!_modules.Agents.Enabled) names.Add("agents");
        if (!_modules.MusicKits.Enabled) names.Add("music kits");
        if (!_modules.Stickers.Enabled) names.Add("stickers");
        if (!_modules.Keychains.Enabled) names.Add("charms");
        return names;
    }

    public IReadOnlyList<WeaponDefinition> GetOwnedWeaponDefinitions(CCSPlayerController player)
    {
        if (!TryGetPawn(player, out var pawn, logFailures: false) || pawn?.WeaponServices is null)
        {
            return Array.Empty<WeaponDefinition>();
        }

        var owned = new Dictionary<string, WeaponDefinition>(StringComparer.OrdinalIgnoreCase);
        foreach (var weaponHandle in pawn.WeaponServices.MyWeapons)
        {
            var weapon = weaponHandle.Value;
            if (weapon is null || !weapon.IsValid)
            {
                continue;
            }

            var entityName = ResolveWeaponEntityName(weapon);
            if (IsKnife(entityName))
            {
                continue;
            }

            if (Catalog.WeaponsByEntity.TryGetValue(entityName, out var definition))
            {
                owned.TryAdd(definition.EntityName, definition);
            }
        }

        return owned.Values
            .OrderBy(w => IsPistol(w.EntityName) ? 1 : 0)
            .ThenBy(w => w.DisplayName)
            .ToList();
    }

    // Resolves the customization target of the held weapon: a weapon entity
    // name known to the catalog, "knife", or null when nothing usable is held.
    public string? GetHeldCustomizationTarget(CCSPlayerController player)
    {
        if (!TryGetPawn(player, out var pawn, logFailures: false))
        {
            return null;
        }

        var weapon = pawn!.WeaponServices?.ActiveWeapon.Value;
        if (weapon is null || !weapon.IsValid)
        {
            return null;
        }

        var entityName = ResolveWeaponEntityName(weapon);
        if (IsKnife(entityName))
        {
            return KnifeTarget;
        }

        return Catalog.WeaponsByEntity.ContainsKey(entityName) ? entityName : null;
    }

    // Attachment target of the held weapon: a catalog gun, or null. Knives
    // and everything else carry neither stickers nor charms.
    public string? GetHeldAttachmentTarget(CCSPlayerController player)
    {
        var target = GetHeldCustomizationTarget(player);
        return target is null || target.Equals(KnifeTarget, StringComparison.OrdinalIgnoreCase) ? null : target;
    }

    public bool SetStatTrak(CCSPlayerController player, string target, int? count)
    {
        // With the default on, "no row" already means "counting from 0", so an
        // explicit off has to be stored as its own value or the next apply
        // would bring the counter back.
        var storedValue = count?.ToString(CultureInfo.InvariantCulture)
            ?? (_statTrakByDefault ? StatTrakDisabledValue : null);

        return SetCustomization(player, target, "stattrak",
            storedValue,
            customization =>
            {
                customization.StatTrak = count;
                customization.StatTrakDisabled = count is null && _statTrakByDefault;
            },
            requiresPaintKit: false);
    }

    public int? GetStatTrak(CCSPlayerController player, string target)
    {
        var profile = GetProfile(player);
        profile.Customizations.TryGetValue(target, out var customization);
        return ResolveStatTrak(profile, target, customization);
    }

    // The one place that turns stored state plus the global default into the
    // count to render: an explicit count wins, an explicit off wins over the
    // default, and the default only hands a fresh 0 to items the player picked
    // a skin for. Gloves never get one, the game has no StatTrak gloves.
    public static int? ResolveStatTrakCount(bool statTrakByDefault, PlayerSkinProfile profile, string target, WeaponCustomization? customization)
    {
        if (customization?.StatTrak is int count)
        {
            return count;
        }

        if (!statTrakByDefault || customization?.StatTrakDisabled == true)
        {
            return null;
        }

        return target switch
        {
            KnifeTarget => profile.KnifeSkinId is not null || profile.KnifeId is not null ? 0 : null,
            GloveTarget => null,
            _ => profile.WeaponSkins.ContainsKey(target) ? 0 : null
        };
    }

    private int? ResolveStatTrak(PlayerSkinProfile profile, string target, WeaponCustomization? customization)
    {
        return ResolveStatTrakCount(_statTrakByDefault, profile, target, customization);
    }

    // The StatTrak default belongs to a selection that is being applied. On
    // the stock finish (no skin, or a saved skin the player cannot use right
    // now) only an explicit counter counts, or a switched-off module would
    // still hand out StatTrak guns.
    private int? ResolveStatTrakForPaint(PlayerSkinProfile profile, string target, WeaponCustomization? customization, CosmeticEntry cosmetic)
    {
        return IsVanillaEntry(target, cosmetic) ? StockFinishCounter(profile, target, customization) : ResolveStatTrak(profile, target, customization);
    }

    // The counter that shows on the stock finish. With the default on, a
    // counter on an item that has a saved selection was started by that
    // default while the selection applied (the first kill stores it as a
    // plain count), so it stays with the selection and is hidden with it.
    // Without the default every stored counter is the player's own choice.
    private int? StockFinishCounter(PlayerSkinProfile profile, string target, WeaponCustomization? customization)
    {
        if (customization?.StatTrak is not int count)
        {
            return null;
        }

        return _statTrakByDefault && HasSavedSelection(profile, target) ? null : count;
    }

    private static bool HasSavedSelection(PlayerSkinProfile profile, string target)
    {
        return target switch
        {
            KnifeTarget => profile.KnifeSkinId is not null || profile.KnifeId is not null,
            GloveTarget => profile.GloveSkinId is not null,
            _ => profile.WeaponSkins.ContainsKey(target)
        };
    }

    // Same rule for a kill: the default counter only exists on an item whose
    // selection is applied right now; on the stock finish an explicit counter
    // is the only one that counts up.
    private int? ResolveStatTrakForHeldItem(CCSPlayerController player, PlayerSkinProfile profile, string target, WeaponCustomization? customization)
    {
        if (target == KnifeTarget)
        {
            return ResolveUsableKnifeSkin(player, profile) is not null || ResolveUsableKnifeType(player, profile) is not null
                ? ResolveStatTrak(profile, target, customization)
                : StockFinishCounter(profile, target, customization);
        }

        var paint = ResolveWeaponPaint(player, profile, target);
        return paint is null ? null : ResolveStatTrakForPaint(profile, target, customization, paint);
    }

    private bool IsVanillaEntry(string target, CosmeticEntry cosmetic)
    {
        return _vanillaEntries.TryGetValue(target, out var vanilla) && ReferenceEquals(vanilla, cosmetic);
    }

    // Bumps the counter in place: no weapon refresh, since re-creating the
    // weapon on every kill would be disastrous.
    public void IncrementStatTrak(CCSPlayerController player, CBasePlayerWeapon weapon, string? killWeapon = null)
    {
        if (_disposed || !IsUsablePlayer(player) || weapon is null || !weapon.IsValid)
        {
            return;
        }

        if (!TryGetSteamId64(player, out var steamId) || !_profiles.TryGetValue(steamId, out var profile))
        {
            return;
        }

        // The stored counter is not known yet: counting now would write an
        // absolute value over it. A kill in that window is not credited.
        if (!_loadedProfiles.Contains(steamId))
        {
            return;
        }

        var weaponName = ResolveWeaponEntityName(weapon);
        if (string.IsNullOrWhiteSpace(weaponName))
        {
            return;
        }

        if (!string.IsNullOrWhiteSpace(killWeapon) && !KillWeaponMatches(weaponName, killWeapon))
        {
            return;
        }

        var target = IsKnife(weaponName) ? KnifeTarget : weaponName;
        profile.Customizations.TryGetValue(target, out var customization);
        if (ResolveStatTrakForHeldItem(player, profile, target, customization) is not int current)
        {
            return;
        }

        // Under the default there may be no row yet: the first kill creates it,
        // so nothing reaches storage until the counter is actually non-zero.
        if (customization is null)
        {
            customization = new WeaponCustomization();
            profile.Customizations[target] = customization;
        }

        var next = current + 1;
        customization.StatTrak = next;
        customization.StatTrakDisabled = false;
        QueueStorageWrite($"stattrak {next} ({target}) for {steamId}",
            () => _storage.SaveCustomization(steamId, "stattrak", target, next.ToString(CultureInfo.InvariantCulture)));

        try
        {
            weapon.FallbackStatTrak = next;
            TrySetStateChanged(weapon, "CEconEntity", "m_nFallbackStatTrak");

            var item = weapon.AttributeManager.Item;
            if (item.Handle != IntPtr.Zero)
            {
                _econAttributes.UpdateStatTrak(item, next);
            }
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to update the StatTrak counter on entity {EntityIndex}.", weapon.Index);
        }
    }

    public bool SetSeed(CCSPlayerController player, string target, int? seed)
    {
        return SetCustomization(player, target, "seed",
            seed?.ToString(CultureInfo.InvariantCulture),
            customization => customization.Seed = seed);
    }

    public bool SetWear(CCSPlayerController player, string target, float? wear)
    {
        return SetCustomization(player, target, "wear",
            wear?.ToString("0.######", CultureInfo.InvariantCulture),
            customization => customization.Wear = wear);
    }

    public bool SetNameTag(CCSPlayerController player, string target, string? nameTag)
    {
        return SetCustomization(player, target, "nametag", nameTag,
            customization => customization.NameTag = nameTag,
            requiresPaintKit: false);
    }

    private bool SetCustomization(CCSPlayerController player, string target, string field, string? storedValue, Action<WeaponCustomization> mutate, bool requiresPaintKit = true)
    {
        if (!HasCustomizableItem(player, target, requiresPaintKit))
        {
            return false;
        }

        var steamId = GetSteamId64(player);
        var profile = GetProfile(player);
        if (!profile.Customizations.TryGetValue(target, out var customization))
        {
            customization = new WeaponCustomization();
            profile.Customizations[target] = customization;
        }

        mutate(customization);
        if (customization.IsEmpty)
        {
            profile.Customizations.Remove(target);
        }

        if (storedValue is null)
        {
            QueueStorageWrite($"{field} reset ({target}) for {steamId}", () => _storage.ClearCustomization(steamId, field, target));
        }
        else
        {
            QueueStorageWrite($"{field} {storedValue} ({target}) for {steamId}", () => _storage.SaveCustomization(steamId, field, target, storedValue));
        }

        // Seed and wear only show on the skin: with the saved skin unusable
        // right now (module off, flag missing) the value is kept for when it
        // applies again, and the item in hand is left alone.
        if (requiresPaintKit && !HasUsableSkin(player, profile, target))
        {
            return true;
        }

        // A name tag or counter lives on the entity itself; removing the last
        // one from an item painted on the stock finish has to re-create it,
        // since a name cleared in place stays visible until then. With a
        // usable skin the normal reapply handles it and the flag is moot.
        ReapplyTarget(player, profile, target, clearWhenBare: !requiresPaintKit);
        return true;
    }

    private bool HasUsableSkin(CCSPlayerController player, PlayerSkinProfile profile, string target)
    {
        return target switch
        {
            KnifeTarget => ResolveUsableKnifeSkin(player, profile) is not null,
            GloveTarget => ResolveUsableGloveSkin(player, profile, logFailures: false) is not null,
            _ => ResolveUsableWeaponSkin(player, profile, target) is not null
        };
    }

    // Seed and wear only mean something on top of a paint kit, but StatTrak and
    // name tags work on the stock finish too, the same way vanilla StatTrak
    // knives exist in the game: any catalog gun or the knife will do.
    private bool HasCustomizableItem(CCSPlayerController player, string target, bool requiresPaintKit)
    {
        var profile = GetProfile(player);
        return target switch
        {
            KnifeTarget => !requiresPaintKit || profile.KnifeSkinId is not null,
            GloveTarget => profile.GloveSkinId is not null,
            _ => requiresPaintKit ? profile.WeaponSkins.ContainsKey(target) : Catalog.WeaponsByEntity.ContainsKey(target)
        };
    }

    // A name tag or a StatTrak counter renders on the stock finish, so a gun or
    // knife carrying either gets painted even without a skin.
    private bool HasVisibleCustomization(PlayerSkinProfile profile, string target)
    {
        profile.Customizations.TryGetValue(target, out var customization);
        return !string.IsNullOrWhiteSpace(customization?.NameTag) || StockFinishCounter(profile, target, customization) is not null;
    }

    // clearWhenBare: the caller just removed a sticker, a charm, a name tag or
    // a counter, or the skin itself, so an item left with nothing to paint
    // gets the stock entity back. Seed and wear never set it: they need a
    // paint kit, and a gun whose saved skin is unusable must stay as it is.
    private void ReapplyTarget(CCSPlayerController player, PlayerSkinProfile profile, string target, bool logFailures = true, bool clearWhenBare = false)
    {
        switch (target)
        {
            case KnifeTarget:
                // The stored skin can belong to a previously selected knife
                // (changing knife type does not clear it). Applying it blindly
                // would switch the player back to the old knife, so fall back to
                // the selected knife type, exactly like ApplyMatchingWeapon does.
                var knifeSkin = ResolveUsableKnifeSkin(player, profile);
                if (knifeSkin is not null)
                {
                    ApplyKnifeSelection(player, knifeSkin, logFailures);
                    break;
                }

                var selectedKnife = ResolveUsableKnifeType(player, profile);
                if (selectedKnife is not null)
                {
                    ApplyKnifeTypeSelection(player, selectedKnife, logFailures);
                }
                else if (HasVisibleCustomization(profile, KnifeTarget))
                {
                    RefreshStockKnife(player, logFailures);
                }
                else if (clearWhenBare)
                {
                    // Nothing left to show on the knife: a fresh stock one so
                    // a removed name tag or counter goes away now.
                    ClearWeaponCosmetics(player, includeKnives: true, onlyKnives: true, logFailures: logFailures);
                }
                break;
            case GloveTarget:
                var glove = ResolveUsableGloveSkin(player, profile, logFailures);
                if (glove is not null)
                {
                    ApplyGloveSelection(player, glove, logFailures);
                }
                break;
            default:
                var skin = ResolveWeaponPaint(player, profile, target);
                if (skin is not null)
                {
                    ApplyWeaponSelection(player, target, skin, logFailures);
                }
                else if (clearWhenBare)
                {
                    // The last sticker or charm left a gun without a skin:
                    // hand out the stock gun so the attachment goes away now.
                    ClearWeaponSelection(player, target);
                }
                break;
        }
    }

    private void ReapplyWeapons(CCSPlayerController player, PlayerSkinProfile profile, IEnumerable<string> weaponEntities)
    {
        foreach (var weaponEntity in weaponEntities)
        {
            ReapplyTarget(player, profile, weaponEntity, logFailures: false, clearWhenBare: true);
        }
    }

    private void ClearWeaponSelection(CCSPlayerController player, string weaponEntity)
    {
        if (!TryGetPawn(player, out var pawn, logFailures: false) || pawn!.WeaponServices is null)
        {
            return;
        }

        var weapons = pawn.WeaponServices.MyWeapons
            .Select(handle => handle.Value)
            .Where(weapon => weapon is { IsValid: true })
            .ToList();
        foreach (var weapon in weapons)
        {
            if (ResolveWeaponEntityName(weapon!).Equals(weaponEntity, StringComparison.OrdinalIgnoreCase))
            {
                ReplaceWeaponWithStock(player, weapon!, weaponEntity);
                return;
            }
        }
    }

    private WeaponCustomization? GetCustomization(CCSPlayerController player, string target)
    {
        return TryGetSteamId64(player, out var steamId) &&
               _profiles.TryGetValue(steamId, out var profile) &&
               profile.Customizations.TryGetValue(target, out var customization)
            ? customization
            : null;
    }

    public KnifeDefinition? GetCurrentKnifeDefinition(CCSPlayerController player)
    {
        var profile = GetProfile(player);
        if (profile.KnifeId is not null)
        {
            var selectedKnife = Catalog.Knives.FirstOrDefault(k => k.Id.Equals(profile.KnifeId, StringComparison.OrdinalIgnoreCase));
            if (selectedKnife is not null)
            {
                return selectedKnife;
            }
        }

        if (profile.KnifeSkinId is not null &&
            Catalog.KnifeSkinsById.TryGetValue(profile.KnifeSkinId, out var selectedKnifeSkin) &&
            selectedKnifeSkin.ItemDefinitionIndex.HasValue)
        {
            var selectedKnife = Catalog.Knives.FirstOrDefault(k => k.ItemDefinitionIndex == selectedKnifeSkin.ItemDefinitionIndex.Value);
            if (selectedKnife is not null)
            {
                return selectedKnife;
            }
        }

        if (!TryGetPawn(player, out var pawn, logFailures: false) || pawn?.WeaponServices is null)
        {
            return null;
        }

        foreach (var weaponHandle in pawn.WeaponServices.MyWeapons)
        {
            var weapon = weaponHandle.Value;
            if (weapon is null || !weapon.IsValid)
            {
                continue;
            }

            var entityName = ResolveWeaponEntityName(weapon);
            if (!IsKnife(entityName))
            {
                continue;
            }

            var itemDefinitionIndex = weapon.AttributeManager.Item.ItemDefinitionIndex;
            return Catalog.Knives.FirstOrDefault(k =>
                k.ItemDefinitionIndex == itemDefinitionIndex ||
                k.EntityName.Equals(entityName, StringComparison.OrdinalIgnoreCase));
        }

        return null;
    }

    private void ApplyWeapons(CCSPlayerController player, CCSPlayerPawn pawn, PlayerSkinProfile profile, bool logFailures)
    {
        var weaponServices = pawn.WeaponServices;
        if (weaponServices is null)
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply weapon cosmetics for player {SteamId}: weapon services are unavailable.", player.SteamID);
            }

            return;
        }

        var appliedWeaponEntities = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var appliedKnife = false;

        foreach (var weaponHandle in weaponServices.MyWeapons)
        {
            var weapon = weaponHandle.Value;
            if (weapon is null || !weapon.IsValid)
            {
                continue;
            }

            var applied = ApplyMatchingWeapon(player, weapon, profile, logFailures: false);
            if (!applied)
            {
                continue;
            }

            var weaponName = ResolveWeaponEntityName(weapon);
            if (IsKnife(weaponName))
            {
                appliedKnife = true;
            }
            else
            {
                appliedWeaponEntities.Add(weaponName);
            }
        }

        if (!logFailures)
        {
            return;
        }

        foreach (var weaponEntity in profile.WeaponSkins.Keys)
        {
            if (!appliedWeaponEntities.Contains(weaponEntity) && ResolveUsableWeaponSkin(player, profile, weaponEntity) is not null)
            {
                _logger.LogWarning("Astra Skins weapon not found for player {SteamId}: {WeaponEntity}. Selection remains saved.", player.SteamID, weaponEntity);
            }
        }

        if (!appliedKnife && ResolveUsableKnifeSkin(player, profile) is not null)
        {
            _logger.LogWarning("Astra Skins knife weapon not found for player {SteamId}. Selection remains saved.", player.SteamID);
        }
        else if (!appliedKnife && ResolveUsableKnifeType(player, profile) is not null)
        {
            _logger.LogWarning("Astra Skins knife weapon not found for player {SteamId}. Knife type selection remains saved.", player.SteamID);
        }
    }

    private bool ApplyMatchingWeapon(CCSPlayerController player, CBasePlayerWeapon weapon, PlayerSkinProfile profile, bool logFailures)
    {
        var weaponName = ResolveWeaponEntityName(weapon);
        if (string.IsNullOrWhiteSpace(weaponName))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply weapon cosmetic for player {SteamId}: weapon name is unavailable.", player.SteamID);
            }

            return false;
        }

        if (IsKnife(weaponName))
        {
            var knifeSkin = ResolveUsableKnifeSkin(player, profile);
            if (knifeSkin is not null)
            {
                return ApplyCosmeticToWeapon(player, weapon, knifeSkin, isKnife: true, logFailures);
            }

            var knife = ResolveUsableKnifeType(player, profile);
            if (knife is not null)
            {
                return ApplyKnifeTypeToWeapon(player, weapon, knife, logFailures);
            }

            return HasVisibleCustomization(profile, KnifeTarget) && ApplyStockKnifeCustomization(player, weapon, logFailures);
        }

        var skin = ResolveWeaponPaint(player, profile, weaponName);
        return skin is not null && ApplyCosmeticToWeapon(player, weapon, skin, isKnife: false, logFailures, weaponName);
    }

    private bool ApplyWeaponSelection(CCSPlayerController player, string weaponEntity, CosmeticEntry skin, bool logFailures)
    {
        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return false;
        }

        var weaponServices = pawn!.WeaponServices;
        if (weaponServices is null)
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply {CosmeticId}: weapon services are unavailable for player {SteamId}.", skin.Id, player.SteamID);
            }

            return false;
        }

        foreach (var weaponHandle in weaponServices.MyWeapons)
        {
            var weapon = weaponHandle.Value;
            if (weapon is null || !weapon.IsValid)
            {
                continue;
            }

            var weaponName = ResolveWeaponEntityName(weapon);
            if (!string.IsNullOrWhiteSpace(weaponName) &&
                weaponName.Equals(weaponEntity, StringComparison.OrdinalIgnoreCase))
            {
                return RefreshOwnedWeaponWithSelection(player, weapon, weaponEntity, skin, logFailures);
            }
        }

        if (logFailures)
        {
            _logger.LogWarning("Astra Skins weapon not found for player {SteamId}: {WeaponEntity}. Selection was saved and will apply when owned.", player.SteamID, weaponEntity);
        }

        return false;
    }

    private void LoadProfileInBackground(ulong steamId64, bool applyAfterLoad, bool logFailures)
    {
        if (_disposed)
        {
            return;
        }

        if (_loadedProfiles.Contains(steamId64))
        {
            return;
        }

        if (_profileRetryAfterUtc.TryGetValue(steamId64, out var retryAfter) && DateTime.UtcNow < retryAfter)
        {
            return;
        }

        // A read is already in flight: remember that someone wants cosmetics
        // applied when it lands instead of dropping the request.
        if (!_loadingProfiles.Add(steamId64))
        {
            if (applyAfterLoad)
            {
                _applyAfterLoadRequests.Add(steamId64);
            }

            return;
        }

        if (applyAfterLoad)
        {
            _applyAfterLoadRequests.Add(steamId64);
        }

        var epoch = GetProfileEpoch(steamId64);
        EnqueueStorageOperation(() =>
        {
            PlayerSkinProfile? loaded = null;
            Exception? failure = null;
            try
            {
                loaded = _storage.LoadProfile(steamId64);
            }
            catch (Exception ex)
            {
                failure = ex;
            }

            Server.NextFrame(() =>
            {
                if (_disposed)
                {
                    return;
                }

                _loadingProfiles.Remove(steamId64);
                var applyAfterLoadRequested = _applyAfterLoadRequests.Remove(steamId64);

                // The player left while this read was in flight.
                if (!_activeSteamIds.Contains(steamId64))
                {
                    _profileEpochs.Remove(steamId64);
                    return;
                }

                // The lifecycle changed (reset, or reconnect during the read):
                // this result is stale, so read again for the current one.
                if (GetProfileEpoch(steamId64) != epoch)
                {
                    LoadProfileInBackground(steamId64, applyAfterLoadRequested, logFailures);
                    return;
                }

                if (failure is not null)
                {
                    // Always logged: the reconcile paths pass logFailures false
                    // and a database outage must not stay invisible. The
                    // cooldown keeps it to one line per player per interval.
                    _profileRetryAfterUtc[steamId64] = DateTime.UtcNow.AddSeconds(ProfileRetrySeconds);
                    _logger.LogWarning(failure, "Astra Skins failed to load profile for player {SteamId}; retrying in {Seconds}s.", steamId64, ProfileRetrySeconds);
                    return;
                }

                if (loaded is null)
                {
                    _profileRetryAfterUtc[steamId64] = DateTime.UtcNow.AddSeconds(ProfileRetrySeconds);
                    _logger.LogWarning("Astra Skins storage returned no profile for player {SteamId}; retrying in {Seconds}s.", steamId64, ProfileRetrySeconds);
                    return;
                }

                _profileRetryAfterUtc.Remove(steamId64);

                if (_profiles.TryGetValue(steamId64, out var existing))
                {
                    MergeLoadedProfile(existing, loaded);
                }
                else
                {
                    _profiles[steamId64] = loaded;
                }

                PruneUnknownSelections(_profiles[steamId64]);
                _loadedProfiles.Add(steamId64);

                if (!applyAfterLoadRequested)
                {
                    return;
                }

                var player = Utilities.GetPlayers().FirstOrDefault(p => IsUsablePlayer(p) && p.SteamID == steamId64);
                if (player is not null)
                {
                    ApplyToPlayer(player, logFailures);
                }
            });
        });
    }

    private void QueueStorageWrite(string description, Action write)
    {
        EnqueueStorageOperation(() =>
        {
            try
            {
                write();
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "Astra Skins failed to persist {Description} in the background.", description);
            }
        });
    }

    // All storage work runs on one background chain so operations keep their
    // submission order (a reset queued before a save must hit the database
    // first) while the game thread never waits on the database.
    private void EnqueueStorageOperation(Action operation)
    {
        lock (_storageQueueLock)
        {
            _storageQueue = _storageQueue.ContinueWith(
                _ => operation(),
                CancellationToken.None,
                TaskContinuationOptions.None,
                TaskScheduler.Default);
        }
    }

    private ulong GetProfileEpoch(ulong steamId64)
    {
        return _profileEpochs.TryGetValue(steamId64, out var epoch) ? epoch : 0;
    }

    private void BumpProfileEpoch(ulong steamId64)
    {
        _profileEpochs[steamId64] = GetProfileEpoch(steamId64) + 1;
    }

    // Selections made in memory while the load was in flight win over the
    // loaded values; the queued writes persist them anyway.
    private static void MergeLoadedProfile(PlayerSkinProfile target, PlayerSkinProfile loaded)
    {
        foreach (var (weaponEntity, cosmeticId) in loaded.WeaponSkins)
        {
            target.WeaponSkins.TryAdd(weaponEntity, cosmeticId);
        }

        target.KnifeId ??= loaded.KnifeId;
        target.KnifeSkinId ??= loaded.KnifeSkinId;
        target.GloveSkinId ??= loaded.GloveSkinId;
        target.MusicKitId ??= loaded.MusicKitId;

        foreach (var (musicKitId, loadedCount) in loaded.MusicKitMvpCounts)
        {
            var normalizedLoadedCount = Math.Max(0, loadedCount);
            if (target.MusicKitMvpCounts.TryGetValue(musicKitId, out var localCount))
            {
                var mergedCount = (long)Math.Max(0, localCount) + normalizedLoadedCount;
                target.MusicKitMvpCounts[musicKitId] = mergedCount >= int.MaxValue ? int.MaxValue : (int)mergedCount;
            }
            else
            {
                target.MusicKitMvpCounts[musicKitId] = normalizedLoadedCount;
            }
        }

        foreach (var (team, agentId) in loaded.AgentIdsByTeam)
        {
            target.AgentIdsByTeam.TryAdd(team, agentId);
        }

        foreach (var (weaponEntity, loadedSlots) in loaded.Stickers)
        {
            if (!target.Stickers.TryGetValue(weaponEntity, out var slots))
            {
                target.Stickers[weaponEntity] = loadedSlots;
                continue;
            }

            foreach (var (slot, stickerId) in loadedSlots)
            {
                slots.TryAdd(slot, stickerId);
            }
        }

        foreach (var (weaponEntity, keychainId) in loaded.Keychains)
        {
            target.Keychains.TryAdd(weaponEntity, keychainId);
        }

        foreach (var (weaponEntity, steps) in loaded.StickerWearSteps)
        {
            target.StickerWearSteps.TryAdd(weaponEntity, steps);
        }

        foreach (var (customizationTarget, loadedCustomization) in loaded.Customizations)
        {
            if (target.Customizations.TryGetValue(customizationTarget, out var existing))
            {
                existing.Seed ??= loadedCustomization.Seed;
                existing.Wear ??= loadedCustomization.Wear;
                existing.NameTag ??= loadedCustomization.NameTag;
                if (existing.StatTrak is null && !existing.StatTrakDisabled)
                {
                    existing.StatTrak = loadedCustomization.StatTrak;
                    existing.StatTrakDisabled = loadedCustomization.StatTrakDisabled;
                }
            }
            else
            {
                target.Customizations[customizationTarget] = loadedCustomization;
            }
        }
    }

    private bool ApplyKnifeSelection(CCSPlayerController player, CosmeticEntry skin, bool logFailures)
    {
        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return false;
        }

        var weaponServices = pawn!.WeaponServices;
        if (weaponServices is null)
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply knife {CosmeticId}: weapon services are unavailable for player {SteamId}.", skin.Id, player.SteamID);
            }

            return false;
        }

        foreach (var weaponHandle in weaponServices.MyWeapons)
        {
            var weapon = weaponHandle.Value;
            var weaponName = weapon is null ? null : ResolveWeaponEntityName(weapon);
            if (weapon is null || !weapon.IsValid || string.IsNullOrWhiteSpace(weaponName) || !IsKnife(weaponName))
            {
                continue;
            }

            var knife = Catalog.Knives.FirstOrDefault(k => k.ItemDefinitionIndex == skin.ItemDefinitionIndex);
            if (knife is null)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins cannot apply knife skin {CosmeticId}: knife item definition index {ItemDefinitionIndex} is not loaded.", skin.Id, skin.ItemDefinitionIndex);
                }

                return false;
            }

            return RefreshOwnedKnifeWithSelection(player, weapon, knife, skin, logFailures);
        }

        if (logFailures)
        {
            _logger.LogWarning("Astra Skins knife weapon not found for player {SteamId}. Selection was saved and will apply when owned.", player.SteamID);
        }

        return false;
    }

    private bool ApplyKnifeTypeSelection(CCSPlayerController player, KnifeDefinition knife, bool logFailures)
    {
        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return false;
        }

        var weaponServices = pawn!.WeaponServices;
        if (weaponServices is null)
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply knife type {KnifeId}: weapon services are unavailable for player {SteamId}.", knife.Id, player.SteamID);
            }

            return false;
        }

        foreach (var weaponHandle in weaponServices.MyWeapons)
        {
            var weapon = weaponHandle.Value;
            var weaponName = weapon is null ? null : ResolveWeaponEntityName(weapon);
            if (weapon is null || !weapon.IsValid || string.IsNullOrWhiteSpace(weaponName) || !IsKnife(weaponName))
            {
                continue;
            }

            return RefreshOwnedKnifeWithSelection(player, weapon, knife, skin: null, logFailures);
        }

        if (logFailures)
        {
            _logger.LogWarning("Astra Skins knife weapon not found for player {SteamId}. Knife type selection was saved and will apply when owned.", player.SteamID);
        }

        return false;
    }

    // The default CT and T knives, weapon_knife and weapon_knife_t.
    private static bool IsStockKnifeDefinition(ushort itemDefinitionIndex)
    {
        return itemDefinitionIndex is 42 or 59;
    }

    // A name tag or counter on the default knife: re-create the knife the game
    // handed out so the client picks the new name up, then write it again.
    private bool RefreshStockKnife(CCSPlayerController player, bool logFailures)
    {
        if (!TryGetPawn(player, out var pawn, logFailures) || pawn!.WeaponServices is null)
        {
            return false;
        }

        foreach (var weaponHandle in pawn.WeaponServices.MyWeapons)
        {
            var weapon = weaponHandle.Value;
            if (weapon is null || !weapon.IsValid || !IsKnife(ResolveWeaponEntityName(weapon)))
            {
                continue;
            }

            return RefreshOwnedKnifeWithSelection(player, weapon, knife: null, skin: null, logFailures);
        }

        return false;
    }

    // Writes only what a stock knife can carry: the owner identity, the name
    // tag and the StatTrak counter. The knife itself, its subclass and its
    // finish stay as the engine made them.
    private bool ApplyStockKnifeCustomization(CCSPlayerController player, CBasePlayerWeapon weapon, bool logFailures)
    {
        try
        {
            if (weapon.AttributeManager.Handle == IntPtr.Zero)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins econ attribute manager invalid while customizing the stock knife on weapon entity {EntityIndex}.", weapon.Index);
                }

                return false;
            }

            var item = weapon.AttributeManager.Item;
            if (item.Handle == IntPtr.Zero)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins econ item invalid while customizing the stock knife on weapon entity {EntityIndex}.", weapon.Index);
                }

                return false;
            }

            // Only the knife the game hands out. A catalog knife in hand with
            // no selection here belongs to another plugin; leave it alone.
            if (!IsStockKnifeDefinition(item.ItemDefinitionIndex))
            {
                return false;
            }

            var customization = GetCustomization(player, KnifeTarget);
            var statTrak = StockFinishCounter(GetProfile(player), KnifeTarget, customization);

            weapon.FallbackPaintKit = 0;
            weapon.FallbackSeed = 0;
            weapon.FallbackWear = 0f;
            weapon.FallbackStatTrak = statTrak ?? -1;
            weapon.OriginalOwnerXuidLow = (uint)(player.SteamID & 0xFFFFFFFF);
            weapon.OriginalOwnerXuidHigh = (uint)(player.SteamID >> 32);
            // Quality 9 is what puts "StatTrak" on the item; only touch it to
            // set that or to undo it, the stock quality is otherwise kept.
            if (statTrak.HasValue)
            {
                item.EntityQuality = 9;
            }
            else if (item.EntityQuality == 9)
            {
                item.EntityQuality = 0;
            }

            UpdateEconItemIdentity(item, player);
            var nameTag = customization?.NameTag;
            if (!string.IsNullOrWhiteSpace(nameTag))
            {
                item.CustomName = nameTag;
                item.CustomNameOverride = nameTag;
            }

            _econAttributes.ClearPaintAttributes(item, $"{ResolveWeaponEntityName(weapon)} entity {weapon.Index}", statTrak);
            ApplyStatTrakBodyGroup(weapon, statTrak.HasValue);
            MarkWeaponStateChanged(weapon);
            RefreshActiveWeapon(player, weapon);
            return true;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Failed to customize the stock knife on weapon entity {EntityIndex}.", weapon.Index);
            return false;
        }
    }

    private bool ApplyGloveSelection(CCSPlayerController player, CosmeticEntry glove, bool logFailures)
    {
        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return false;
        }

        return ApplyGloveCosmetic(player, pawn!, glove, logFailures);
    }

    private bool ApplyGloves(CCSPlayerController player, CCSPlayerPawn pawn, PlayerSkinProfile profile, bool logFailures)
    {
        var glove = ResolveUsableGloveSkin(player, profile, logFailures);
        return glove is not null && ApplyGloveCosmetic(player, pawn, glove, logFailures);
    }

    private bool ApplyGloveCosmetic(CCSPlayerController player, CCSPlayerPawn pawn, CosmeticEntry glove, bool logFailures)
    {
        try
        {
            var econGloves = pawn.EconGloves;
            if (econGloves.Handle == IntPtr.Zero)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins econ item invalid while applying gloves {CosmeticId} for player {SteamId}.", glove.Id, player.SteamID);
                }

                return false;
            }

            if (!glove.ItemDefinitionIndex.HasValue)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins glove {CosmeticId} has no ItemDefinitionIndex.", glove.Id);
                }

                return false;
            }

            var customization = GetCustomization(player, GloveTarget);
            var seed = customization?.Seed ?? glove.Seed;
            var wear = customization?.Wear ?? glove.Wear;

            econGloves.ItemDefinitionIndex = glove.ItemDefinitionIndex.Value;
            econGloves.EntityQuality = 3;
            UpdateEconItemIdentity(econGloves, player);
            ApplyCustomName(econGloves, glove, overrideName: null);

            var attributesApplied = _econAttributes.ApplyPaintAttributes(econGloves, glove.Id, glove.PaintKit, seed, wear, $"gloves player {player.SteamID}");
            pawn.EconGlovesChanged++;
            MarkGlovesStateChanged(pawn);
            RefreshGloves(player, pawn);
            return attributesApplied;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Failed to apply gloves for player {SteamId}.", player.SteamID);
            return false;
        }
    }

    private bool ApplyAgentSelection(CCSPlayerController player, AgentDefinition agent, bool logFailures)
    {
        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return false;
        }

        return ApplyAgentModel(player, pawn!, agent, logFailures);
    }

    private bool ApplyAgent(CCSPlayerController player, CCSPlayerPawn pawn, PlayerSkinProfile profile, bool logFailures)
    {
        var agent = ResolveUsableAgent(player, profile, GetPlayerTeamKey(player), logFailures);
        return agent is not null && ApplyAgentModel(player, pawn, agent, logFailures);
    }

    private bool ApplyAgentModel(CCSPlayerController player, CCSPlayerPawn pawn, AgentDefinition agent, bool logFailures)
    {
        if (pawn is null || !pawn.IsValid)
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply agent {AgentId} for player {SteamId}: pawn is invalid.", agent.Id, player.SteamID);
            }

            return false;
        }

        if (string.IsNullOrWhiteSpace(agent.Model))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply agent {AgentId} for player {SteamId}: model path is empty.", agent.Id, player.SteamID);
            }

            return false;
        }

        var playerTeam = GetPlayerTeamKey(player);
        if (playerTeam is null || !agent.Team.Equals(playerTeam, StringComparison.OrdinalIgnoreCase))
        {
            return false;
        }

        if (_isModelPrecached is not null && !_isModelPrecached(agent.Model))
        {
            if (_unprecachedModelsWarned.Add(agent.Model))
            {
                _logger.LogWarning("Astra Skins agent {AgentId} model {Model} is not precached on this map (added after map start?); it applies from the next map.", agent.Id, agent.Model);
            }

            return false;
        }

        try
        {
            var itemDefinitionIndex = agent.ItemDefinitionIndex.GetValueOrDefault();
            pawn.SetModel(agent.Model);
            pawn.CharacterDefIndex = itemDefinitionIndex;
            pawn.StrVOPrefix = agent.VoicePrefix ?? string.Empty;
            pawn.HasFemaleVoice = agent.HasFemaleVoice ?? IsFemaleVoicePrefix(agent.VoicePrefix);
            // m_nCharacterDefIndex and m_strVOPrefix are not networked fields;
            // calling SetStateChanged on them makes the engine log unresolved
            // offsets. Only m_bHasFemaleVoice is part of the send table.
            TrySetStateChanged(pawn, "CCSPlayerPawn", "m_bHasFemaleVoice");
            return true;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to apply agent {AgentId} model {Model} for player {SteamId}.", agent.Id, agent.Model, player.SteamID);
            return false;
        }
    }

    // Everything that lives on the CEconItemView itself, shared by live weapons
    // and the team intro preview slots. Quality 9 is what makes the client
    // render the StatTrak counter.
    private bool PaintEconItem(
        CCSPlayerController player,
        CEconItemView item,
        CosmeticEntry cosmetic,
        bool isKnife,
        int seed,
        float wear,
        int? statTrak,
        string? nameTag,
        string context,
        IReadOnlyList<StickerAttachment>? stickers = null,
        int? keychainId = null)
    {
        if (cosmetic.ItemDefinitionIndex.HasValue)
        {
            item.ItemDefinitionIndex = cosmetic.ItemDefinitionIndex.Value;
        }

        item.EntityQuality = statTrak.HasValue ? 9 : isKnife ? 3 : 0;
        UpdateEconItemIdentity(item, player);
        ApplyCustomName(item, cosmetic, nameTag);
        return _econAttributes.ApplyPaintAttributes(item, cosmetic.Id, cosmetic.PaintKit, seed, wear, context, statTrak, stickers, keychainId);
    }

    private bool ApplyCosmeticToWeapon(CCSPlayerController player, CBasePlayerWeapon weapon, CosmeticEntry cosmetic, bool isKnife, bool logFailures, string? customizationTarget = null)
    {
        try
        {
            if (weapon.AttributeManager.Handle == IntPtr.Zero)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins econ attribute manager invalid while applying {CosmeticId} to weapon entity {EntityIndex}.", cosmetic.Id, weapon.Index);
                }

                return false;
            }

            var item = weapon.AttributeManager.Item;
            if (item.Handle == IntPtr.Zero)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins econ item invalid while applying {CosmeticId} to weapon entity {EntityIndex}.", cosmetic.Id, weapon.Index);
                }

                return false;
            }

            if (isKnife && cosmetic.ItemDefinitionIndex.HasValue)
            {
                TryChangeKnifeSubclass(weapon, cosmetic.ItemDefinitionIndex.Value);
            }

            // Resolving the entity name on a freshly created weapon is not
            // reliable, so prefer the target the caller already knows.
            var resolvedTarget = isKnife ? KnifeTarget : customizationTarget ?? ResolveWeaponEntityName(weapon);
            var customization = GetCustomization(player, resolvedTarget);
            var seed = customization?.Seed ?? cosmetic.Seed;
            var wear = customization?.Wear ?? cosmetic.Wear;

            var profile = GetProfile(player);
            var statTrak = ResolveStatTrakForPaint(profile, resolvedTarget, customization, cosmetic);
            var stickers = isKnife ? null : ResolveUsableStickers(player, profile, resolvedTarget);
            var keychainId = isKnife ? null : ResolveUsableKeychain(player, profile, resolvedTarget);
            if (!isKnife)
            {
                wear = AdjustWearForStickers(player, profile, resolvedTarget, wear, stickers is { Count: > 0 });
            }

            weapon.FallbackPaintKit = cosmetic.PaintKit;
            weapon.FallbackSeed = seed;
            weapon.FallbackWear = wear;
            weapon.FallbackStatTrak = statTrak ?? -1;
            weapon.OriginalOwnerXuidLow = (uint)(player.SteamID & 0xFFFFFFFF);
            weapon.OriginalOwnerXuidHigh = (uint)(player.SteamID >> 32);

            var attributesApplied = PaintEconItem(player, item, cosmetic, isKnife, seed, wear, statTrak, customization?.NameTag,
                $"{ResolveWeaponEntityName(weapon)} entity {weapon.Index}", stickers, keychainId);
            ApplyWeaponBodyGroup(weapon, cosmetic);
            ApplyStatTrakBodyGroup(weapon, statTrak.HasValue);
            MarkWeaponStateChanged(weapon);
            RefreshActiveWeapon(player, weapon);

            if (!attributesApplied && logFailures)
            {
                _logger.LogWarning("Astra Skins applied CS2 paint netprops but dynamic attribute update failed for {CosmeticId} on weapon entity {EntityIndex}.", cosmetic.Id, weapon.Index);
            }

            return attributesApplied;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Failed to apply cosmetic {CosmeticId} to weapon entity {EntityIndex}.", cosmetic.Id, weapon.Index);
            return false;
        }
    }

    private void ClearPlayerCosmetics(CCSPlayerController player, bool logFailures, ISet<string>? stockPaintedWeapons = null)
    {
        ClearWeaponCosmetics(player, includeKnives: true, logFailures: logFailures, alsoReplace: stockPaintedWeapons);
        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return;
        }

        ClearGloveCosmetic(player, pawn!);
    }

    private void ClearWeaponCosmetics(CCSPlayerController player, bool includeKnives, bool onlyKnives = false, bool logFailures = false, ISet<string>? alsoReplace = null)
    {
        if (!TryGetPawn(player, out var pawn, logFailures))
        {
            return;
        }

        var weaponServices = pawn!.WeaponServices;
        if (weaponServices is not null)
        {
            // Snapshot: the loop hands out replacement weapons, which the
            // engine may append to the very list being walked.
            var weapons = weaponServices.MyWeapons
                .Select(handle => handle.Value)
                .Where(weapon => weapon is { IsValid: true })
                .ToList();
            foreach (var weapon in weapons)
            {
                if (weapon is null || !weapon.IsValid)
                {
                    continue;
                }

                var weaponName = ResolveWeaponEntityName(weapon);
                var isKnife = IsKnife(weaponName);
                if ((onlyKnives && !isKnife) || (!includeKnives && isKnife))
                {
                    continue;
                }

                if (isKnife)
                {
                    // Clearing the paint in place leaves the custom knife model
                    // until the next round; hand out the stock knife now.
                    ReplaceKnifeWithDefault(player, weapon);
                    continue;
                }

                // Same for guns: a paint cleared in place stays visible until
                // the entity is re-created. Only catalog weapons that carry a
                // paint (or attachments on the stock finish, kit 0) are
                // replaced, so grenades and the C4 are never touched.
                if (!string.IsNullOrWhiteSpace(weaponName) &&
                    (weapon.FallbackPaintKit > 0 || alsoReplace?.Contains(weaponName) == true))
                {
                    ReplaceWeaponWithStock(player, weapon, weaponName);
                    continue;
                }

                ClearWeaponCosmetic(player, weapon);
            }
        }
        else if (logFailures)
        {
            _logger.LogWarning("Astra Skins cannot clear weapon cosmetics for player {SteamId}: weapon services are unavailable.", player.SteamID);
        }
    }

    // Mirror of RefreshOwnedWeaponWithSelection for the reset case: same kill
    // and give with the ammo carried over, no paint on the new entity because
    // the profile is already empty when the GiveNamedItem hook runs.
    private void ReplaceWeaponWithStock(CCSPlayerController player, CBasePlayerWeapon oldWeapon, string weaponEntity)
    {
        try
        {
            var wasActive = IsActiveWeapon(player, oldWeapon);
            var oldClip = Math.Max(0, oldWeapon.Clip1);
            var oldReserve = oldWeapon.ReserveAmmo.Length > 0 ? Math.Max(0, oldWeapon.ReserveAmmo[0]) : 0;

            ClearWeaponCosmetic(player, oldWeapon);
            var newWeapon = player.GiveNamedItem<CBasePlayerWeapon>(weaponEntity);
            if (newWeapon is null)
            {
                _logger.LogWarning("Astra Skins could not create the stock {WeaponEntity} for player {SteamId} after a reset.", weaponEntity, player.SteamID);
                return;
            }

            oldWeapon.AddEntityIOEvent("Kill", oldWeapon, null, string.Empty, 0.01f);

            Server.NextFrame(() =>
            {
                if (!IsUsablePlayer(player) || !newWeapon.IsValid)
                {
                    return;
                }

                RestoreAmmo(newWeapon, oldClip, oldReserve);
                _scheduleDelayed?.Invoke(0.2f, () =>
                {
                    // Only undo an engine refill; a clip that went down in the
                    // meantime was fired and must not be refunded.
                    if (IsUsablePlayer(player) && newWeapon.IsValid && newWeapon.Clip1 > oldClip)
                    {
                        RestoreAmmo(newWeapon, oldClip, oldReserve);
                    }
                });

                if (wasActive)
                {
                    player.ExecuteClientCommand(IsPistol(weaponEntity) ? "slot2" : "slot1");
                }
            });
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to replace {WeaponEntity} with the stock one for player {SteamId}.", weaponEntity, player.SteamID);
        }
    }

    // The GiveNamedItem hook sees the already cleared profile, so the new knife
    // comes out stock without any further work here.
    private void ReplaceKnifeWithDefault(CCSPlayerController player, CBasePlayerWeapon oldKnife)
    {
        try
        {
            var wasActive = IsActiveWeapon(player, oldKnife);
            ClearWeaponCosmetic(player, oldKnife);
            var newKnife = player.GiveNamedItem<CBasePlayerWeapon>("weapon_knife");
            if (newKnife is null)
            {
                _logger.LogWarning("Astra Skins could not create the stock knife for player {SteamId} after a reset.", player.SteamID);
                return;
            }

            oldKnife.AddEntityIOEvent("Kill", oldKnife, null, string.Empty, 0.01f);

            if (wasActive)
            {
                Server.NextFrame(() =>
                {
                    if (IsUsablePlayer(player) && newKnife.IsValid)
                    {
                        player.ExecuteClientCommand("slot3");
                    }
                });
            }
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to replace the knife with the stock one for player {SteamId}.", player.SteamID);
        }
    }

    private void ClearWeaponCosmetic(CCSPlayerController player, CBasePlayerWeapon weapon)
    {
        try
        {
            weapon.FallbackPaintKit = 0;
            weapon.FallbackSeed = 0;
            weapon.FallbackWear = 0f;
            weapon.FallbackStatTrak = -1;

            var item = weapon.AttributeManager.Item;
            if (item.Handle != IntPtr.Zero)
            {
                _econAttributes.ClearPaintAttributes(item, $"{ResolveWeaponEntityName(weapon)} entity {weapon.Index}");
                UpdateEconItemIdentity(item, player);
            }

            MarkWeaponStateChanged(weapon);
            RefreshActiveWeapon(player, weapon);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to clear weapon cosmetic on entity {EntityIndex}.", weapon.Index);
        }
    }

    private void ClearGloveCosmetic(CCSPlayerController player, CCSPlayerPawn pawn)
    {
        try
        {
            var econGloves = pawn.EconGloves;
            if (econGloves.Handle != IntPtr.Zero)
            {
                _econAttributes.ClearPaintAttributes(econGloves, $"gloves player {player.SteamID}");
                UpdateEconItemIdentity(econGloves, player);
            }

            pawn.EconGlovesChanged++;
            MarkGlovesStateChanged(pawn);
            RefreshGloves(player, pawn);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to clear glove cosmetic for player {SteamId}.", player.SteamID);
        }
    }

    private bool RefreshOwnedWeaponWithSelection(CCSPlayerController player, CBasePlayerWeapon oldWeapon, string weaponEntity, CosmeticEntry skin, bool logFailures)
    {
        try
        {
            if (oldWeapon is null || !oldWeapon.IsValid)
            {
                return false;
            }

            // Only take the player's weapon slot over if the weapon being
            // refreshed is the one actually in their hands.
            var wasActive = IsActiveWeapon(player, oldWeapon);
            var oldClip = 0;
            var oldReserve = 0;
            oldClip = Math.Max(0, oldWeapon.Clip1);
            oldReserve = oldWeapon.ReserveAmmo.Length > 0 ? Math.Max(0, oldWeapon.ReserveAmmo[0]) : 0;

            ApplyCosmeticToWeapon(player, oldWeapon, skin, isKnife: false, logFailures);
            var newWeapon = player.GiveNamedItem<CBasePlayerWeapon>(weaponEntity);
            if (newWeapon is null)
            {
                _logger.LogWarning("Astra Skins could not create replacement {WeaponEntity} for player {SteamId}.", weaponEntity, player.SteamID);
                return false;
            }

            oldWeapon.AddEntityIOEvent("Kill", oldWeapon, null, string.Empty, 0.01f);

            Server.NextFrame(() =>
            {
                if (!IsUsablePlayer(player) || !newWeapon.IsValid)
                {
                    return;
                }

                try
                {
                    RestoreAmmo(newWeapon, oldClip, oldReserve);
                    ApplyCosmeticToWeapon(player, newWeapon, skin, isKnife: false, logFailures, weaponEntity);

                    // The engine finishes initializing the new weapon after this
                    // frame, refilling the clip and clearing the StatTrak netprop,
                    // so write both again once it has settled.
                    _scheduleDelayed?.Invoke(0.2f, () =>
                    {
                        if (IsUsablePlayer(player) && newWeapon.IsValid)
                        {
                            // Only undo an engine refill; a clip that went down
                            // in the meantime was fired and must not be refunded.
                            if (newWeapon.Clip1 > oldClip)
                            {
                                RestoreAmmo(newWeapon, oldClip, oldReserve);
                            }

                            ApplyCosmeticToWeapon(player, newWeapon, skin, isKnife: false, logFailures: false, weaponEntity);
                        }
                    });
                    if (wasActive)
                    {
                        player.ExecuteClientCommand(IsPistol(weaponEntity) ? "slot2" : "slot1");
                    }
                }
                catch (Exception ex)
                {
                    _logger.LogWarning(ex, "Astra Skins failed to finish weapon replacement for {WeaponEntity} on player {SteamId}.", weaponEntity, player.SteamID);
                }
            });

            if (logFailures)
            {
                _logger.LogInformation("Astra Skins refreshed {WeaponEntity} for player {SteamId} to apply {CosmeticId}.", weaponEntity, player.SteamID, skin.Id);
            }

            return true;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to refresh weapon {WeaponEntity} for player {SteamId}.", weaponEntity, player.SteamID);
            return false;
        }
    }

    // knife null and skin null: the stock knife, re-created for its name tag or
    // counter (see ApplyStockKnifeCustomization).
    private bool RefreshOwnedKnifeWithSelection(CCSPlayerController player, CBasePlayerWeapon oldKnife, KnifeDefinition? knife, CosmeticEntry? skin, bool logFailures)
    {
        try
        {
            if (oldKnife is null || !oldKnife.IsValid)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins cannot refresh knife for player {SteamId}: current knife entity is invalid.", player.SteamID);
                }

                return false;
            }

            var knifeEntity = "weapon_knife";
            if (knife is not null)
            {
                if (!WeaponEntityByDefinitionIndex.TryGetValue(knife.ItemDefinitionIndex, out var mappedEntity) ||
                    !IsKnife(mappedEntity))
                {
                    if (logFailures)
                    {
                        _logger.LogWarning(
                            "Astra Skins cannot refresh knife {KnifeId} for player {SteamId}: item definition index is unmapped.",
                            knife.Id,
                            player.SteamID);
                    }

                    return false;
                }

                knifeEntity = mappedEntity;
            }

            void Apply(CBasePlayerWeapon target, bool log)
            {
                if (skin is not null)
                {
                    ApplyCosmeticToWeapon(player, target, skin, isKnife: true, log);
                }
                else if (knife is not null)
                {
                    ApplyKnifeTypeToWeapon(player, target, knife, log);
                }
                else
                {
                    ApplyStockKnifeCustomization(player, target, log);
                }
            }

            var knifeWasActive = IsActiveWeapon(player, oldKnife);
            Apply(oldKnife, logFailures);

            var newKnife = player.GiveNamedItem<CBasePlayerWeapon>("weapon_knife");
            if (newKnife is null)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins could not create replacement knife for player {SteamId}.", player.SteamID);
                }

                return false;
            }

            oldKnife.AddEntityIOEvent("Kill", oldKnife, null, string.Empty, 0.01f);

            Server.NextFrame(() =>
            {
                if (!IsUsablePlayer(player) || !newKnife.IsValid)
                {
                    if (logFailures)
                    {
                        _logger.LogWarning("Astra Skins failed to create refreshed knife {KnifeEntity} for player {SteamId}.", knifeEntity, player.SteamID);
                    }

                    return;
                }

                try
                {
                    Apply(newKnife, logFailures);

                    // Same settle window as weapons: the StatTrak counter is a
                    // netprop the engine clears while it finishes the entity.
                    _scheduleDelayed?.Invoke(0.2f, () =>
                    {
                        if (!IsUsablePlayer(player) || !newKnife.IsValid)
                        {
                            return;
                        }

                        Apply(newKnife, log: false);
                    });

                    if (knifeWasActive)
                    {
                        player.ExecuteClientCommand("slot3");
                    }
                }
                catch (Exception ex)
                {
                    _logger.LogWarning(ex, "Astra Skins failed to finish knife replacement for {KnifeEntity} on player {SteamId}.", knifeEntity, player.SteamID);
                }
            });

            if (logFailures)
            {
                _logger.LogInformation(
                    "Astra Skins refreshed {KnifeEntity} for player {SteamId} to apply {SelectionId}.",
                    knifeEntity,
                    player.SteamID,
                    skin?.Id ?? knife?.Id ?? "stock knife customization");
            }

            return true;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to refresh knife for player {SteamId}.", player.SteamID);
            return false;
        }
    }

    private bool ApplyKnifeTypeToWeapon(CCSPlayerController player, CBasePlayerWeapon weapon, KnifeDefinition knife, bool logFailures)
    {
        try
        {
            if (weapon.AttributeManager.Handle == IntPtr.Zero)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins econ attribute manager invalid while applying knife type {KnifeId} to weapon entity {EntityIndex}.", knife.Id, weapon.Index);
                }

                return false;
            }

            var item = weapon.AttributeManager.Item;
            if (item.Handle == IntPtr.Zero)
            {
                if (logFailures)
                {
                    _logger.LogWarning("Astra Skins econ item invalid while applying knife type {KnifeId} to weapon entity {EntityIndex}.", knife.Id, weapon.Index);
                }

                return false;
            }

            var statTrak = ResolveStatTrak(GetProfile(player), KnifeTarget, GetCustomization(player, KnifeTarget));

            TryChangeKnifeSubclass(weapon, knife.ItemDefinitionIndex);
            weapon.FallbackPaintKit = 0;
            weapon.FallbackSeed = 0;
            weapon.FallbackWear = 0f;
            weapon.FallbackStatTrak = statTrak ?? -1;
            weapon.OriginalOwnerXuidLow = (uint)(player.SteamID & 0xFFFFFFFF);
            weapon.OriginalOwnerXuidHigh = (uint)(player.SteamID >> 32);
            item.ItemDefinitionIndex = knife.ItemDefinitionIndex;
            item.EntityQuality = statTrak.HasValue ? 9 : 3;
            UpdateEconItemIdentity(item, player);
            var nameTag = GetCustomization(player, KnifeTarget)?.NameTag;
            if (!string.IsNullOrWhiteSpace(nameTag))
            {
                item.CustomName = nameTag;
                item.CustomNameOverride = nameTag;
            }

            _econAttributes.ClearPaintAttributes(item, $"{knife.EntityName} entity {weapon.Index}", statTrak);
            ApplyStatTrakBodyGroup(weapon, statTrak.HasValue);
            MarkWeaponStateChanged(weapon);
            RefreshActiveWeapon(player, weapon);
            return true;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to apply knife type {KnifeId} to weapon entity {EntityIndex}.", knife.Id, weapon.Index);
            return false;
        }
    }

    private void RemoveInvalidCachedSelections()
    {
        foreach (var profile in _profiles.Values)
        {
            PruneUnknownSelections(profile);
        }
    }

    // Drops ids the catalog does not know (entries disabled, removed or
    // regenerated) so the menu never shows a selection it cannot name. The
    // rows stay in storage; an entry the player merely lacks the flag for is
    // known and stays too.
    private void PruneUnknownSelections(PlayerSkinProfile profile)
    {
        foreach (var weapon in profile.WeaponSkins.Keys.ToArray())
        {
            if (!Catalog.WeaponSkinsById.ContainsKey(profile.WeaponSkins[weapon]))
            {
                profile.WeaponSkins.Remove(weapon);
            }
        }

        if (profile.KnifeSkinId is not null && !Catalog.KnifeSkinsById.ContainsKey(profile.KnifeSkinId))
        {
            profile.KnifeSkinId = null;
        }

        if (profile.KnifeId is not null && !Catalog.Knives.Any(k => k.Id.Equals(profile.KnifeId, StringComparison.OrdinalIgnoreCase)))
        {
            profile.KnifeId = null;
        }

        if (profile.GloveSkinId is not null && !Catalog.GloveSkinsById.ContainsKey(profile.GloveSkinId))
        {
            profile.GloveSkinId = null;
        }

        foreach (var team in profile.AgentIdsByTeam.Keys.ToArray())
        {
            if (!Catalog.AgentsById.ContainsKey(profile.AgentIdsByTeam[team]))
            {
                profile.AgentIdsByTeam.Remove(team);
            }
        }

        foreach (var (weaponEntity, slots) in profile.Stickers.ToArray())
        {
            var pruned = false;
            foreach (var slot in slots.Keys.ToArray())
            {
                if (!Catalog.StickersById.ContainsKey(slots[slot]))
                {
                    slots.Remove(slot);
                    pruned = true;
                }
            }

            if (slots.Count == 0)
            {
                profile.Stickers.Remove(weaponEntity);
            }

            if (pruned && profile.SteamId64 != 0)
            {
                BumpStickerWear(profile.SteamId64, profile, weaponEntity);
            }
        }

        foreach (var weaponEntity in profile.Keychains.Keys.ToArray())
        {
            if (!Catalog.KeychainsById.ContainsKey(profile.Keychains[weaponEntity]))
            {
                profile.Keychains.Remove(weaponEntity);
            }
        }
    }

    // player_death names the item that killed ("ak47", "hegrenade",
    // "knife_karambit", "planted_c4"). Only the weapon in hand carries the
    // counter, so a kill by anything else is not credited to it.
    private static bool KillWeaponMatches(string weaponEntity, string killWeapon)
    {
        var held = weaponEntity.StartsWith("weapon_", StringComparison.OrdinalIgnoreCase) ? weaponEntity[7..] : weaponEntity;
        var kill = killWeapon.StartsWith("weapon_", StringComparison.OrdinalIgnoreCase) ? killWeapon[7..] : killWeapon;
        if (held.Equals(kill, StringComparison.OrdinalIgnoreCase))
        {
            return true;
        }

        // Knives report their model name while the held entity can be the
        // stock knife or a subclassed one; any knife kill counts for the knife.
        return IsKnife(held) && (kill.StartsWith("knife", StringComparison.OrdinalIgnoreCase) || kill.Equals("bayonet", StringComparison.OrdinalIgnoreCase));
    }

    private static bool IsKnife(string weaponName)
    {
        return weaponName.Contains("knife", StringComparison.OrdinalIgnoreCase) ||
               weaponName.Equals("weapon_bayonet", StringComparison.OrdinalIgnoreCase);
    }

    private bool KnifeSkinMatchesSelectedKnife(PlayerSkinProfile profile, CosmeticEntry knifeSkin)
    {
        if (profile.KnifeId is null)
        {
            return true;
        }

        var knife = Catalog.Knives.FirstOrDefault(k => k.Id.Equals(profile.KnifeId, StringComparison.OrdinalIgnoreCase));
        return knife is not null && knifeSkin.ItemDefinitionIndex == knife.ItemDefinitionIndex;
    }

    private static string ResolveWeaponEntityName(CBasePlayerWeapon weapon)
    {
        if (!weapon.IsValid)
        {
            return string.Empty;
        }

        try
        {
            var itemDefinitionIndex = weapon.AttributeManager.Item.ItemDefinitionIndex;
            if (WeaponEntityByDefinitionIndex.TryGetValue(itemDefinitionIndex, out var byDefinitionIndex))
            {
                return byDefinitionIndex;
            }
        }
        catch
        {
            // Secondary lookup covers weapons whose econ item is not ready yet.
        }

        var byExtension = weapon.GetWeaponName();
        if (!string.IsNullOrWhiteSpace(byExtension))
        {
            return byExtension;
        }

        return weapon.DesignerName ?? string.Empty;
    }

    private static bool IsPistol(string weaponName)
    {
        return weaponName is "weapon_deagle" or "weapon_elite" or "weapon_fiveseven" or "weapon_glock" or
            "weapon_hkp2000" or "weapon_usp_silencer" or "weapon_p250" or "weapon_tec9" or
            "weapon_cz75a" or "weapon_revolver";
    }

    private static string? GetPlayerTeamKey(CCSPlayerController player)
    {
        return player.Team switch
        {
            CsTeam.Terrorist => "t",
            CsTeam.CounterTerrorist => "ct",
            _ => null
        };
    }

    private static string NormalizeAgentTeam(string team)
    {
        return team.Trim().ToLowerInvariant() switch
        {
            "terrorist" or "terrorists" or "t" => "t",
            "counter-terrorist" or "counter-terrorists" or "counterterrorist" or "counterterrorists" or "ct" => "ct",
            var value => value
        };
    }

    private static string? NormalizeResetCategory(string category)
    {
        return category.Trim().ToLowerInvariant() switch
        {
            "weapon" or "weapons" or "guns" => "weapons",
            "knife" or "knives" => "knife",
            "glove" or "gloves" => "gloves",
            "agent" or "agents" => "agents",
            "music" or "musickit" or "musickits" => "music",
            "sticker" or "stickers" => "stickers",
            "keychain" or "keychains" or "charm" or "charms" => "keychains",
            _ => null
        };
    }

    private static bool IsFemaleVoicePrefix(string? voicePrefix)
    {
        return !string.IsNullOrWhiteSpace(voicePrefix) &&
            voicePrefix.Contains("fem", StringComparison.OrdinalIgnoreCase);
    }

    private static IEnumerable<CCSGO_TeamPreviewCharacterPosition> EnumerateTeamPreviewPositions()
    {
        foreach (var designerName in TeamPreviewDesignerNames)
        {
            foreach (var preview in Utilities.FindAllEntitiesByDesignerName<CCSGO_TeamPreviewCharacterPosition>(designerName))
            {
                if (preview is not null && preview.IsValid)
                {
                    yield return preview;
                }
            }
        }
    }

    private void ApplyTeamPreviewToPosition(
        CCSGO_TeamPreviewCharacterPosition preview,
        CCSPlayerController? filterPlayer,
        bool logFailures)
    {
        try
        {
            if (preview is null || !preview.IsValid)
            {
                return;
            }

            var xuid = preview.Xuid;
            if (xuid == 0)
            {
                return;
            }

            CCSPlayerController? owner;
            if (filterPlayer is not null)
            {
                if (!IsUsablePlayer(filterPlayer) || filterPlayer.SteamID != xuid)
                {
                    return;
                }

                owner = filterPlayer;
            }
            else
            {
                owner = Utilities.GetPlayers().FirstOrDefault(p => IsUsablePlayer(p) && p.SteamID == xuid);
                if (owner is null)
                {
                    return;
                }
            }

            if (!TryGetSteamId64(owner, out var steamId))
            {
                return;
            }

            if (!_loadedProfiles.Contains(steamId) || !_profiles.TryGetValue(steamId, out var profile))
            {
                _activeSteamIds.Add(steamId);
                LoadProfileInBackground(steamId, applyAfterLoad: true, logFailures);
                return;
            }

            var team = TeamKeyFromDesignerName(preview.DesignerName) ?? GetPlayerTeamKey(owner);
            ApplyTeamPreviewAgent(preview, owner, profile, team, logFailures);
            ApplyTeamPreviewGloves(preview, owner, profile, logFailures);
            ApplyTeamPreviewWeapon(preview, owner, profile, logFailures);
            _teamPreviewPaintedFor[preview.Index] = xuid;
        }
        catch (Exception ex)
        {
            if (logFailures)
            {
                _logger.LogWarning(ex, "Astra Skins failed to apply team preview cosmetics to a preview entity.");
            }
        }
    }

    private void ApplyTeamPreviewAgent(
        CCSGO_TeamPreviewCharacterPosition preview,
        CCSPlayerController player,
        PlayerSkinProfile profile,
        string? team,
        bool logFailures)
    {
        var agent = ResolveUsableAgent(player, profile, team, logFailures);
        if (agent is null)
        {
            return;
        }

        var defIndex = agent.ItemDefinitionIndex.GetValueOrDefault();
        if (defIndex == 0 || preview.AgentItem.Handle == IntPtr.Zero)
        {
            return;
        }

        preview.AgentItem.ItemDefinitionIndex = defIndex;
        MarkEconItemStateChanged(preview, "CCSGO_TeamPreviewCharacterPosition", "m_agentItem");
    }

    private void ApplyTeamPreviewGloves(
        CCSGO_TeamPreviewCharacterPosition preview,
        CCSPlayerController player,
        PlayerSkinProfile profile,
        bool logFailures)
    {
        var glove = ResolveUsableGloveSkin(player, profile, logFailures);
        if (glove is null)
        {
            return;
        }

        if (!glove.ItemDefinitionIndex.HasValue || preview.GlovesItem.Handle == IntPtr.Zero)
        {
            return;
        }

        var item = preview.GlovesItem;
        var customization = GetCustomization(player, GloveTarget);
        var seed = customization?.Seed ?? glove.Seed;
        var wear = customization?.Wear ?? glove.Wear;

        item.ItemDefinitionIndex = glove.ItemDefinitionIndex.Value;
        item.EntityQuality = 3;
        UpdateEconItemIdentity(item, player);
        ApplyCustomName(item, glove, overrideName: null);
        _econAttributes.ApplyPaintAttributes(
            item,
            glove.Id,
            glove.PaintKit,
            seed,
            wear,
            $"team preview gloves player {player.SteamID}");
        MarkEconItemStateChanged(preview, "CCSGO_TeamPreviewCharacterPosition", "m_glovesItem");
    }

    private void ApplyTeamPreviewWeapon(
        CCSGO_TeamPreviewCharacterPosition preview,
        CCSPlayerController player,
        PlayerSkinProfile profile,
        bool logFailures)
    {
        var item = preview.WeaponItem;
        if (item.Handle == IntPtr.Zero)
        {
            return;
        }

        var weaponName = preview.WeaponName;
        if (string.IsNullOrWhiteSpace(weaponName) &&
            WeaponEntityByDefinitionIndex.TryGetValue(item.ItemDefinitionIndex, out var mappedName))
        {
            weaponName = mappedName;
        }

        if (string.IsNullOrWhiteSpace(weaponName))
        {
            return;
        }

        if (IsKnife(weaponName))
        {
            var knifeSkin = ResolveUsableKnifeSkin(player, profile);
            if (knifeSkin is not null &&
                ApplyPreviewPaint(player, item, knifeSkin, isKnife: true, KnifeTarget, logFailures, "team preview knife"))
            {
                MarkEconItemStateChanged(preview, "CCSGO_TeamPreviewCharacterPosition", "m_weaponItem");
                return;
            }

            var knife = ResolveUsableKnifeType(player, profile);
            if (knife is not null && ApplyPreviewKnifeType(player, item, knife))
            {
                MarkEconItemStateChanged(preview, "CCSGO_TeamPreviewCharacterPosition", "m_weaponItem");
            }
            else if (knife is null && HasVisibleCustomization(profile, KnifeTarget) && ApplyPreviewStockKnife(player, item))
            {
                MarkEconItemStateChanged(preview, "CCSGO_TeamPreviewCharacterPosition", "m_weaponItem");
            }

            return;
        }

        var skin = ResolveWeaponPaint(player, profile, weaponName);
        if (skin is not null &&
            ApplyPreviewPaint(player, item, skin, isKnife: false, weaponName, logFailures, $"team preview {weaponName}"))
        {
            MarkEconItemStateChanged(preview, "CCSGO_TeamPreviewCharacterPosition", "m_weaponItem");
        }
    }

    private bool ApplyPreviewPaint(
        CCSPlayerController player,
        CEconItemView item,
        CosmeticEntry cosmetic,
        bool isKnife,
        string customizationTarget,
        bool logFailures,
        string context)
    {
        try
        {
            var customization = GetCustomization(player, customizationTarget);
            var seed = customization?.Seed ?? cosmetic.Seed;
            var wear = customization?.Wear ?? cosmetic.Wear;
            var profile = GetProfile(player);
            var statTrak = ResolveStatTrakForPaint(profile, customizationTarget, customization, cosmetic);
            var stickers = isKnife ? null : ResolveUsableStickers(player, profile, customizationTarget);
            var keychainId = isKnife ? null : ResolveUsableKeychain(player, profile, customizationTarget);
            if (!isKnife)
            {
                wear = AdjustWearForStickers(player, profile, customizationTarget, wear, stickers is { Count: > 0 });
            }

            var attributesApplied = PaintEconItem(player, item, cosmetic, isKnife, seed, wear, statTrak, customization?.NameTag, context, stickers, keychainId);
            if (!attributesApplied && logFailures)
            {
                _logger.LogWarning(
                    "Astra Skins applied team preview paint but dynamic attribute update failed for {CosmeticId} on {Context}.",
                    cosmetic.Id,
                    context);
            }

            return true;
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Astra Skins failed to apply {CosmeticId} to {Context}.", cosmetic.Id, context);
            return false;
        }
    }

    private bool ApplyPreviewKnifeType(CCSPlayerController player, CEconItemView item, KnifeDefinition knife)
    {
        var customization = GetCustomization(player, KnifeTarget);
        var statTrak = ResolveStatTrak(GetProfile(player), KnifeTarget, customization);
        item.ItemDefinitionIndex = knife.ItemDefinitionIndex;
        item.EntityQuality = statTrak.HasValue ? 9 : 3;
        UpdateEconItemIdentity(item, player);
        var nameTag = customization?.NameTag;
        if (!string.IsNullOrWhiteSpace(nameTag))
        {
            item.CustomName = nameTag;
            item.CustomNameOverride = nameTag;
        }

        _econAttributes.ClearPaintAttributes(item, $"team preview {knife.EntityName}", statTrak);
        return true;
    }

    // The preview twin of ApplyStockKnifeCustomization: the knife the intro
    // shows keeps its definition, only the name and the counter are written.
    private bool ApplyPreviewStockKnife(CCSPlayerController player, CEconItemView item)
    {
        var customization = GetCustomization(player, KnifeTarget);
        var statTrak = StockFinishCounter(GetProfile(player), KnifeTarget, customization);
        if (statTrak.HasValue)
        {
            item.EntityQuality = 9;
        }
        else if (item.EntityQuality == 9)
        {
            item.EntityQuality = 0;
        }

        UpdateEconItemIdentity(item, player);
        var nameTag = customization?.NameTag;
        if (!string.IsNullOrWhiteSpace(nameTag))
        {
            item.CustomName = nameTag;
            item.CustomNameOverride = nameTag;
        }

        _econAttributes.ClearPaintAttributes(item, "team preview stock knife", statTrak);
        return true;
    }

    private static string? TeamKeyFromDesignerName(string? designerName)
    {
        if (string.IsNullOrWhiteSpace(designerName))
        {
            return null;
        }

        if (designerName.Contains("counterterrorist", StringComparison.OrdinalIgnoreCase))
        {
            return "ct";
        }

        if (designerName.Contains("terrorist", StringComparison.OrdinalIgnoreCase))
        {
            return "t";
        }

        return null;
    }

    private bool TryGetPawn(CCSPlayerController player, out CCSPlayerPawn? pawn, bool logFailures)
    {
        pawn = null;
        if (!IsUsablePlayer(player))
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply cosmetics: player is invalid.");
            }

            return false;
        }

        pawn = player.PlayerPawn.Value;
        if (pawn is null || !pawn.IsValid)
        {
            if (logFailures)
            {
                _logger.LogWarning("Astra Skins cannot apply cosmetics for player {SteamId}: player pawn is invalid.", player.SteamID);
            }

            return false;
        }

        return true;
    }

    private void UpdateEconItemIdentity(CEconItemView item, CCSPlayerController player)
    {
        var itemId = _nextItemId++;
        if (_nextItemId == ulong.MaxValue)
        {
            _nextItemId = MinimumCustomItemId;
        }

        item.ItemID = itemId;
        item.ItemIDLow = (uint)(itemId & 0xFFFFFFFF);
        item.ItemIDHigh = (uint)(itemId >> 32);
        item.AccountID = GetAccountId(player);
        item.Initialized = true;
    }

    private static void ApplyCustomName(CEconItemView item, CosmeticEntry cosmetic, string? overrideName)
    {
        var name = string.IsNullOrWhiteSpace(overrideName) ? cosmetic.CustomName : overrideName;
        if (string.IsNullOrWhiteSpace(name))
        {
            return;
        }

        item.CustomName = name;
        item.CustomNameOverride = name;
    }

    private void TryChangeKnifeSubclass(CBasePlayerWeapon weapon, ushort itemDefinitionIndex)
    {
        try
        {
            weapon.AcceptInput("ChangeSubclass", value: itemDefinitionIndex.ToString());
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to change knife subclass for weapon entity {EntityIndex}.", weapon.Index);
        }
    }

    private void ApplyWeaponBodyGroup(CBasePlayerWeapon weapon, CosmeticEntry cosmetic)
    {
        if (!cosmetic.LegacyModel.HasValue)
        {
            _logger.LogWarning(
                "Astra Skins cosmetic {CosmeticId} has no legacyModel metadata. Regenerate and upload data JSON files.",
                cosmetic.Id);
            return;
        }

        try
        {
            weapon.AcceptInput("SetBodygroup", value: $"body,{(cosmetic.LegacyModel.Value ? 1 : 0)}");
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to set weapon bodygroup for {CosmeticId} on entity {EntityIndex}.", cosmetic.Id, weapon.Index);
        }
    }

    // The counter is a separate module on the model; without its bodygroup the
    // item is named StatTrak but shows no number when inspected.
    private void ApplyStatTrakBodyGroup(CBasePlayerWeapon weapon, bool enabled)
    {
        try
        {
            weapon.AcceptInput("SetBodygroup", value: $"stattrak,{(enabled ? 1 : 0)}");
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to set the StatTrak bodygroup on entity {EntityIndex}.", weapon.Index);
        }
    }

    private void MarkWeaponStateChanged(CBasePlayerWeapon weapon)
    {
        TrySetStateChanged(weapon, "CEconEntity", "m_nFallbackPaintKit");
        TrySetStateChanged(weapon, "CEconEntity", "m_nFallbackSeed");
        TrySetStateChanged(weapon, "CEconEntity", "m_flFallbackWear");
        TrySetStateChanged(weapon, "CEconEntity", "m_nFallbackStatTrak");
    }

    private void MarkGlovesStateChanged(CCSPlayerPawn pawn)
    {
        MarkEconItemStateChanged(pawn, "CCSPlayerPawn", "m_EconGloves");
        TrySetStateChanged(pawn, "CCSPlayerPawn", "m_nEconGlovesChanged");
    }

    // Leaf fields of CEconItemView this plugin writes. Flagging the embedded
    // struct itself makes the engine log "Couldn't resolve offset": that
    // offset is not a networked leaf, so the change list has to name each
    // field. Which of them are networked is asked from the schema once.
    private static readonly string[] EconItemFields =
    {
        "m_bInitialized",
        "m_iItemDefinitionIndex",
        "m_iEntityQuality",
        "m_iItemIDHigh",
        "m_iItemIDLow",
        "m_iAccountID",
        "m_szCustomName",
        "m_szCustomNameOverride",
    };

    private static readonly Lazy<(string Name, int Offset)[]> NetworkedEconItemFields = new(() =>
        EconItemFields
            .Where(f => NativeAPI.IsSchemaFieldNetworked("CEconItemView", f))
            .Select(f => (f, (int)NativeAPI.GetSchemaOffset("CEconItemView", f)))
            .ToArray());

    private void MarkEconItemStateChanged(CBaseEntity entity, string className, string fieldName)
    {
        foreach (var (_, offset) in NetworkedEconItemFields.Value)
        {
            TrySetStateChanged(entity, className, fieldName, offset);
        }
    }

    private static bool IsActiveWeapon(CCSPlayerController player, CBasePlayerWeapon weapon)
    {
        try
        {
            var active = player.PlayerPawn.Value?.WeaponServices?.ActiveWeapon.Value;
            return active is not null && active.IsValid && weapon.IsValid && active.Index == weapon.Index;
        }
        catch
        {
            return false;
        }
    }

    private void RestoreAmmo(CBasePlayerWeapon weapon, int clip, int reserve)
    {
        weapon.Clip1 = clip;
        TrySetStateChanged(weapon, "CBasePlayerWeapon", "m_iClip1");
        if (weapon.ReserveAmmo.Length > 0)
        {
            weapon.ReserveAmmo[0] = reserve;
            TrySetStateChanged(weapon, "CBasePlayerWeapon", "m_pReserveAmmo");
        }
    }

    private void TrySetStateChanged(CBaseEntity entity, string className, string fieldName, int extraOffset = 0)
    {
        try
        {
            Utilities.SetStateChanged(entity, className, fieldName, extraOffset);
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to mark state changed for {ClassName}.{FieldName}.", className, fieldName);
        }
    }

    private void RefreshActiveWeapon(CCSPlayerController player, CBasePlayerWeapon weapon)
    {
        try
        {
            var pawn = player.PlayerPawn.Value;
            var activeWeapon = pawn?.WeaponServices?.ActiveWeapon.Value;
            if (pawn is null || !pawn.IsValid || activeWeapon is null || !activeWeapon.IsValid || activeWeapon.Index != weapon.Index)
            {
                return;
            }

            var weaponName = ResolveWeaponEntityName(weapon);
            var slotCommand = IsKnife(weaponName)
                ? "slot3"
                : weaponName.Equals("weapon_taser", StringComparison.OrdinalIgnoreCase)
                    ? "slot5"
                    : IsPistol(weaponName)
                        ? "slot2"
                        : "slot1";

            Server.NextFrame(() =>
            {
                if (!IsUsablePlayer(player))
                {
                    return;
                }

                player.ExecuteClientCommand(slotCommand.Equals("slot3", StringComparison.Ordinal) ? "lastinv" : "slot3");
                Server.NextFrame(() =>
                {
                    if (IsUsablePlayer(player))
                    {
                        player.ExecuteClientCommand(slotCommand);
                    }
                });
            });
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to refresh active weapon for player {SteamId}.", player.SteamID);
        }
    }

    private void RefreshGloves(CCSPlayerController player, CCSPlayerPawn pawn)
    {
        try
        {
            Server.NextFrame(() =>
            {
                if (!IsUsablePlayer(player) || !pawn.IsValid)
                {
                    return;
                }

                player.ExecuteClientCommand("lastinv");
                pawn.AcceptInput("SetBodygroup", value: "first_or_third_person,0");
                Server.NextFrame(() =>
                {
                    if (pawn.IsValid)
                    {
                        pawn.AcceptInput("SetBodygroup", value: "first_or_third_person,1");
                    }
                });
            });
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Astra Skins failed to refresh gloves for player {SteamId}.", player.SteamID);
        }
    }

    private static uint GetAccountId(CCSPlayerController player)
    {
        return (uint)(player.SteamID & 0xFFFFFFFF);
    }

    private static ulong GetSteamId64(CCSPlayerController player)
    {
        if (!TryGetSteamId64(player, out var steamId))
        {
            throw new InvalidOperationException("Player does not have a valid SteamID64.");
        }

        return steamId;
    }

    private static bool TryGetSteamId64(CCSPlayerController player, out ulong steamId)
    {
        steamId = 0;
        if (!player.IsValid || player.IsBot || player.SteamID == 0)
        {
            return false;
        }

        steamId = player.SteamID;
        return true;
    }

    private static bool IsUsablePlayer(CCSPlayerController player)
    {
        return player.IsValid && !player.IsBot && player.SteamID != 0;
    }
}