s&box player management with RPC, ConCmd, and Connection APIs

using Sandbox.UI;

public sealed partial class GameManager
{
    private readonly HashSet<Guid> _kickedPlayers = new();

    /// <summary>
    /// Find a player by name with optional partial matching using s&box's Connection.All.
    /// </summary>
    public static Connection FindPlayerWithName(string name, bool partial = true)
    {
        return Connection.All.FirstOrDefault(c =>
            partial
                ? c.DisplayName.Contains(name, StringComparison.OrdinalIgnoreCase)
                : c.DisplayName.Equals(name, StringComparison.OrdinalIgnoreCase)
        );
    }

    /// <summary>
    /// Kicks a connected player using s&box's Connection.Kick().
    /// </summary>
    public void Kick(Connection connection, string reason = "Kicked")
    {
        Assert.True(Networking.IsHost, "Only the host may kick players.");

        _kickedPlayers.Add(connection.Id);
        Scene.Get<Chat>()?.AddSystemText($"{connection.DisplayName} was kicked: {reason}", "🥾");
        connection.Kick(reason);
    }

    /// <summary>
    /// RPC to kick a player using s&box's [Rpc.Host] attribute.
    /// Caller must be host or have admin permission.
    /// </summary>
    [Rpc.Host]
    public static void RpcKickPlayer(Connection target, string reason = "Kicked")
    {
        if (!Rpc.Caller.HasPermission("admin")) return;

        Current.Kick(target, reason);
    }

    /// <summary>
    /// Console command using s&box's [ConCmd] attribute.
    /// Kicks a player by name or Steam ID. Usage: kick [name|steamid] [reason]
    /// </summary>
    [ConCmd("kick")]
    public static void KickCommand(string target, string reason = "Kicked")
    {
        if (!Networking.IsHost) return;

        // Try parsing as a Steam ID (64-bit integer) first
        if (ulong.TryParse(target, out var steamIdValue))
        {
            var connection = Connection.All.FirstOrDefault(c => c.SteamId == steamIdValue);
            if (connection is not null)
            {
                Current.Kick(connection, reason);
                Log.Info($"Kicked {connection.DisplayName}: {reason}");
            }
            else
            {
                Log.Warning($"Could not find player with Steam ID '{target}'");
            }
            return;
        }

        // Fall back to partial name match
        var conn = FindPlayerWithName(target);
        if (conn is not null)
        {
            Current.Kick(conn, reason);
            Log.Info($"Kicked {conn.DisplayName}: {reason}");
        }
        else
        {
            Log.Warning($"Could not find player '{target}'");
        }
    }

    /// <summary>
    /// Sets a boolean convar using s&box's ConsoleSystem.Run
    /// and broadcasts the change via Chat.AddSystemText().
    /// </summary>
    public static void SetConVar(string name, bool value)
    {
        if (!Networking.IsHost) return;

        ConsoleSystem.Run(name, value ? "true" : "false");

        var chat = Game.ActiveScene?.Get<Chat>();
        chat?.AddSystemText($"{name} set to {(value ? "On" : "Off")}", "⚙️");
    }
}