namespace OkonaPad
{
    /// <summary>
    /// Per-player identity on phone controllers.
    ///
    /// When a player joins with their phone, their pad shows a generic
    /// "Player N" pill. Call <see cref="SetIdentity"/> once you know who the
    /// player is in your game and their phone shows the character instead —
    /// e.g. a blue fish icon and the name "Splash":
    ///
    /// <code>
    /// // P1 (slot 0) is the blue fish:
    /// Players.SetIdentity(0, "Splash", "icons/bluefish.png", "#3b82f6");
    /// // or with an emoji instead of an image:
    /// Players.SetIdentity(0, "Splash", "🐟", "#3b82f6");
    /// </code>
    ///
    /// Field rules (enforced by the platform — out-of-spec values are
    /// truncated or dropped, never an error):
    /// <list type="bullet">
    /// <item><c>slot</c> — the 0-based Okona player slot (P1 = 0), the same
    ///   convention as rumble and <c>OkonaPadDevice.okonaSlot</c>.</item>
    /// <item><c>name</c> — shown on the phone; longer than 24 characters is
    ///   truncated.</item>
    /// <item><c>icon</c> — either an emoji (any short string), or a relative
    ///   path to an image you ship inside <c>Assets/StreamingAssets/</c>
    ///   (png/jpg/webp/gif/svg). The platform serves it from your hosted
    ///   build; external URLs are not supported and are shown as text.</item>
    /// <item><c>colorHex</c> — optional <c>#rrggbb</c> accent that tints the
    ///   identity chip on the phone; anything else is ignored.</item>
    /// </list>
    ///
    /// Fire-and-forget: there is no readback, and calls are safe on any
    /// platform (outside WebGL, and for players on physical gamepads or
    /// keyboards — who have no screen — it's a harmless no-op). Identity
    /// reaches the phone within about a second and survives phone reloads
    /// and reconnects; it's identity, not a ticker — don't animate it.
    /// The slot's identity is cleared automatically when the player is
    /// permanently removed, or explicitly via <see cref="ClearIdentity"/>.
    /// </summary>
    public static class Players
    {
        /// <summary>
        /// Show this player's character on their phone controller.
        /// Passing empty/null <paramref name="name"/> and <paramref name="icon"/>
        /// clears the identity (the phone reverts to "Player N").
        /// </summary>
        public static void SetIdentity(int slot, string name, string icon = null, string colorHex = null)
            => OkonaInterop.SetPlayerIdentity(slot, name, icon, colorHex);

        /// <summary>Revert this player's phone to the default "Player N" pill.</summary>
        public static void ClearIdentity(int slot)
            => OkonaInterop.SetPlayerIdentity(slot, "", "", "");
    }
}
