/// Represents a player connected to the Minecraft server.
interface player {
    use common.{hand, item-stack, position, game-mode};
    use %world.{%world};
    use entity.{entity};
    use permission.{permission-level};
    use text.{text-component};
    use gui.{gui};
    use java-packets.{clientbound-packet as java-packet};
    use bedrock-packets.{clientbound-packet as bedrock-packet};

    /// Various abilities a player can have.
    record player-abilities {
        /// Whether the player is invulnerable to damage.
        invulnerable:       bool,
        /// Whether the player is currently flying.
        flying:             bool,
        /// Whether the player is allowed to fly.
        allow-flying:       bool,
        /// Whether the player is in creative mode.
        creative:           bool,
        /// Whether the player can modify the world.
        allow-modify-world: bool,
        /// The speed at which the player flies.
        fly-speed:          f32,
        /// The speed at which the player walks.
        walk-speed:         f32,
    }

    /// Represents a player's skin textures and metadata.
    record player-skin {
        /// The base64-encoded texture data (usually JSON containing skin/cape URLs).
        value: string,
        /// The optional signature for the texture data.
        signature: option<string>,
    }

    /// Flags representing visible skin parts.
    flags skin-parts {
        cape,
        jacket,
        left-sleeve,
        right-sleeve,
        left-pants-leg,
        right-pants-leg,
        hat,
    }

    /// A handle to a player on the server.
    resource player {
        /// Returns the player as an entity.
        as-entity: func () -> entity;
        /// Returns the player's unique UUID as a string.
        get-id: func () -> string;
        /// Returns the player's username.
        get-name: func () -> string;

        // Basic state

        /// Returns the player's current position in the world.
        get-position: func () -> position;
        /// Returns the player's current yaw (horizontal rotation).
        get-yaw: func () -> f32;
        /// Returns the player's current pitch (vertical rotation).
        get-pitch: func () -> f32;
        /// Returns the world the player is currently in.
        get-world: func () -> %world;
        /// Returns the player's current game mode.
        get-gamemode: func () -> game-mode;
        /// Changes the player's game mode. Returns true if successful.
        set-gamemode: func (mode: game-mode) -> bool;
        /// Returns the player's locale (e.g., "en_us").
        get-locale: func () -> string;
        /// Returns the player's current ping in milliseconds.
        get-ping: func () -> u32;

        // Permissions & metadata

        /// Returns the player's permission level (0-4).
        get-permission-level: func () -> permission-level;
        /// Sets the player's permission level.
        set-permission-level: func (level: permission-level);
        /// Grants or denies a specific permission node for the player.
	    set-permission: func(node: string, value: bool);
	    /// Removes an explicitly set permission node from the player.
	    unset-permission: func(node: string);
        /// Returns `Some(true)` if granted, `Some(false)` if denied, or `None` if not set.
        has-permission-set: func (node: string) -> option<bool>;
        /// Checks if the player has a specific permission node.
        has-permission: func (node: string) -> bool;
        /// Returns the player's display name, which may include formatting.
        get-display-name: func () -> text-component;
        /// Sets the player's display name.
        set-display-name: func (display-name: text-component);
        /// Gets the player's custom tab list name.
        get-tab-list-name: func () -> option<text-component>;
        /// Sets the player's custom tab list name.
        set-tab-list-name: func (name: option<text-component>);

        // Messaging & titles

        /// Sends a system message to the player's chat.
        send-system-message: func (text: text-component, overlay: bool);
        /// Sets the header and footer of the player's Tab list.
        set-tab-list-header-footer: func (header: text-component, footer: text-component);

        /// Sets the sorting order of the player in the Tab list.
        set-tab-list-order: func (order: s32);
        /// Sets the latency (ping) shown for the player in the Tab list.
        set-tab-list-latency: func (latency: s32);
        /// Sets whether the player is visible in the Tab list.
        set-tab-list-listed: func (listed: bool);

        /// Shows a large title on the player's screen.

        show-title: func (text: text-component);
        /// Shows a smaller subtitle on the player's screen.
        show-subtitle: func (text: text-component);
        /// Shows a message in the action bar area.
        show-actionbar: func (text: text-component);
        /// Sets the fade-in, stay, and fade-out times for titles.
        send-title-animation: func (fade-in: s32, stay: s32, fade-out: s32);

        // Teleport & kick

        /// Teleports the player to a position in a world.
        teleport: func (position: position, yaw: option<f32>, pitch: option<f32>, %world: %world);
        /// Teleports the player to another world at a specific position.
        teleport-world: func (world-ref: %world, position: position, yaw: option<f32>, pitch: option<f32>);
        /// Kicks the player from the server with the specified reason.
        kick: func (message: text-component);
        /// Forces the player to respawn.
        respawn: func ();

        /// Opens a GUI for the player.
        open-gui: func (gui-ref: gui);

        /// Bans the player with an optional reason.
        ban: func (reason: option<text-component>);
        /// Bans the player's IP address with an optional reason.
        ban-ip: func (reason: option<text-component>);

        // Inventory

        /// Returns the index of the currently selected hotbar slot (0-8).
        get-selected-slot: func () -> u8;
        /// Returns the item currently in the specified hand.
        get-item-in-hand: func (hand: hand) -> option<item-stack>;
        /// Returns the item in the specified inventory slot.
        get-inventory-item: func (slot: u8) -> option<item-stack>;

        // Status

        /// Returns the player's current health.
        get-health: func () -> f32;
        /// Sets the player's current health.
        set-health: func (health: f32);
        /// Returns the player's maximum health.
        get-max-health: func () -> f32;
        /// Sets the player's maximum health.
        set-max-health: func (max-health: f32);
        /// Returns the player's food level (0-20).
        get-food-level: func () -> u8;
        /// Sets the player's food level.
        set-food-level: func (food-level: u8);
        /// Returns the player's food saturation level.
        get-saturation: func () -> f32;
        /// Sets the player's food saturation level.
        set-saturation: func (saturation: f32);
        /// Returns the player's food exhaustion level.
        get-exhaustion: func () -> f32;
        /// Sets the player's food exhaustion level.
        set-exhaustion: func (exhaustion: f32);
        /// Returns the player's current absorption amount.
        get-absorption: func () -> f32;
        /// Sets the player's current absorption amount.
        set-absorption: func (absorption: f32);

        /// Returns the player's total experience level.
        get-experience-level:    func() -> s32;
        /// Returns the player's progress toward the next level (0.0 to 1.0).
        get-experience-progress: func() -> f32;
        /// Returns the total experience points the player has.
        get-experience-points:   func() -> s32;
        /// Sets the player's total experience level.
        set-experience-level:    func(level: s32);
        /// Sets the player's progress toward the next level.
        set-experience-progress: func(progress: f32);
        /// Sets the player's total experience points.
        set-experience-points:   func(points: s32);
        /// Adds experience levels to the player.
        add-experience-levels:   func(levels: s32);
        /// Adds experience points to the player.
        add-experience-points:   func(points: s32);

        /// Returns whether the player is currently flying.
        is-flying:    func() -> bool;
        /// Sets whether the player should be flying.
        set-flying:   func(flying: bool);

        /// Returns the player's current abilities.
        get-abilities: func() -> player-abilities;
        /// Updates the player's abilities.
        set-abilities: func(abilities: player-abilities);

        /// Returns the player's IP address.
        get-ip: func() -> string;

        /// Returns the player's current skin textures.
        get-skin: func() -> option<player-skin>;

        /// Returns the currently visible skin parts.
        get-skin-parts: func() -> skin-parts;
        /// Sets which skin parts are visible.
        set-skin-parts: func(parts: skin-parts);

        /// Sends a Java-specific clientbound packet to the player.
        send-java-packet: func(packet: java-packet);
        /// Sends a Bedrock-specific clientbound packet to the player.
        send-bedrock-packet: func(packet: bedrock-packet);
        /// Sends a custom payload packet (plugin message) to the player.
        send-custom-payload: func(channel: string, data: list<u8>);
    }
}