/// 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};

    /// 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,
    }

    /// 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);
        /// 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);

        // 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 sneaking.
        is-sneaking:  func() -> bool;
        /// Sets whether the player is currently sneaking.
        set-sneaking: func(sneaking: bool);
        /// Returns whether the player is currently sprinting.
        is-sprinting: func() -> bool;
        /// Sets whether the player is currently sprinting.
        set-sprinting: func(sprinting: bool);
        /// Returns whether the player is currently swimming.
        is-swimming: func() -> bool;
        /// Sets whether the player is currently swimming.
        set-swimming: func(swimming: bool);
        /// Returns whether the player is currently invisible.
        is-invisible: func() -> bool;
        /// Sets whether the player is currently invisible.
        set-invisible: func(invisible: bool);
        /// Returns whether the player is currently glowing.
        is-glowing: func() -> bool;
        /// Sets whether the player is currently glowing.
        set-glowing: func(glowing: bool);
        /// Returns whether the player is currently flying due to a fall.
        is-fall-flying: func() -> bool;
        /// Sets whether the player is currently flying due to a fall.
        set-fall-flying: func(fall-flying: bool);
        /// Returns whether the player is currently on fire. Note: this is only visually like fire, there is no actual logic.
        is-on-fire: func() -> bool;
        /// Sets whether the player is visually on fire. Note: this is only visually like fire, there is no actual logic.
        set-on-fire: func(on-fire: bool);
        /// Returns whether the player is currently on the ground.
        is-on-ground: func() -> bool;
        /// 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;
    }
}