/// Represents a player connected to the Minecraft server.
interface player {
    use common.{hand, position, game-mode};
    use item-stack.{item-stack};
    use %world.{%world, entity};
    use permission.{permission-level};
    use text.{text-component};
    use gui.{gui};
    use forms.{form};
    use java-dialogs.{dialog};
    use java-packets.{clientbound-packet as java-packet};
    use bedrock-packets.{clientbound-packet as bedrock-packet};
    use uuid.{uuid};
    use status-effect.{status-effect-type, status-effect-instance};
    use scoreboard.{scoreboard, bedrock-scoreboard};

    /// Represents per-player weather condition overrides.
    enum player-weather {
        clear,
        downfall,
    }

    /// Types of projectiles that can be launched by a player.
    enum projectile-type {
        arrow,
        snowball,
        egg,
        ender-pearl,
        splash-potion,
        fireball,
        small-fireball,
        trident,
        wind-charge,
    }

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

    /// Represents which skin parts are visible.
    flags skin-parts {
        cape,
        jacket,
        left-sleeve,
        right-sleeve,
        left-pants-leg,
        right-pants-leg,
        hat,
    }

    /// Represents the various abilities a Bedrock Edition player can have.
    enum bedrock-ability {
        /// Whether the player can build.
        build,
        /// Whether the player can mine blocks.
        mine,
        /// Whether the player can use doors and switches.
        doors-and-switches,
        /// Whether the player can open containers.
        open-containers,
        /// Whether the player can attack other players.
        attack-players,
        /// Whether the player can attack mobs.
        attack-mobs,
        /// Whether the player can use operator commands.
        operator-commands,
        /// Whether the player can teleport.
        teleport,
        /// Whether the player is invulnerable.
        invulnerable,
        /// Whether the player is currently flying.
        flying,
        /// Whether the player is allowed to fly.
        may-fly,
        /// Whether the player has instant build (creative).
        instabuild,
        /// Whether the player can use lightning-related abilities.
        lightning,
        /// The speed at which the player flies.
        fly-speed,
        /// The speed at which the player walks.
        walk-speed,
        /// Whether the player is muted.
        muted,
        /// Whether the player is a world builder.
        world-builder,
        /// Whether the player has no-clip enabled.
        no-clip,
        /// Whether the player is a privileged builder.
        privileged-builder,
        /// The speed at which the player flies vertically.
        vertical-fly-speed,
    }

    /// Represents the various status flags a Bedrock Edition entity can have.
    /// These flags control client-side rendering and behavior.
    enum bedrock-status-flag {
        /// Whether the entity is currently on fire.
        on-fire,
        /// Whether the entity is sneaking.
        sneaking,
        /// Whether the entity is riding another entity.
        riding,
        /// Whether the entity is sprinting.
        sprinting,
        /// Whether the entity is using an item (e.g., eating, blocking).
        using-item,
        /// Whether the entity is invisible.
        invisible,
        /// Whether the entity is tempted by an item.
        tempted,
        /// Whether the entity is in love (breeding).
        in-love,
        /// Whether the entity is saddled.
        saddled,
        /// Whether the entity is powered (e.g., charged creeper).
        powered,
        /// Whether the entity is ignited.
        ignited,
        /// Whether the entity is a baby.
        baby,
        /// Whether the entity is currently converting to another type.
        converting,
        /// Whether the entity is in a critical state.
        critical,
        /// Whether to show the entity's name tag.
        show-name,
        /// Whether to always show the entity's name tag.
        always-show-name,
        /// Whether the entity has no AI.
        no-ai,
        /// Whether the entity is silent.
        silent,
        /// Whether the entity is climbing a wall.
        wall-climbing,
        /// Whether the entity is climbing.
        climb,
        /// Whether the entity is swimming.
        swim,
        /// Whether the entity is flying.
        fly,
        /// Whether the entity is walking.
        walk,
        /// Whether the entity is resting.
        resting,
        /// Whether the entity is sitting.
        sitting,
        /// Whether the entity is angry.
        angry,
        /// Whether the entity is interested.
        interested,
        /// Whether the entity is charged.
        charged,
        /// Whether the entity is tamed.
        tamed,
        /// Whether the entity is orphaned.
        orphaned,
        /// Whether the entity is leashed.
        leashed,
        /// Whether the entity is sheared.
        sheared,
        /// Whether the entity is gliding (elytra).
        gliding,
        /// Whether the entity is an elder (e.g., elder guardian).
        elder,
        /// Whether the entity is moving.
        moving,
        /// Whether the entity is breathing.
        breathing,
        /// Whether the entity has a chest (e.g., donkey).
        chested,
        /// Whether the entity is stackable.
        stackable,
        /// Whether to show the bottom of the entity.
        show-bottom,
        /// Whether the entity is standing.
        standing,
        /// Whether the entity is shaking.
        shaking,
        /// Whether the entity is idling.
        idling,
        /// Whether the entity is casting (e.g., evoker).
        casting,
        /// Whether the entity is charging an attack.
        charging,
        /// Whether the entity is controlled by a keyboard.
        keyboard-controlled,
        /// Whether the entity is performing a power jump.
        power-jump,
        /// Whether the entity is dashing.
        dash,
        /// Whether the entity is lingering.
        lingering,
        /// Whether the entity has collision.
        has-collision,
        /// Whether the entity has gravity.
        has-gravity,
        /// Whether the entity is immune to fire.
        fire-immune,
        /// Whether the entity is dancing.
        dancing,
        /// Whether the entity is enchanted.
        enchanted,
        /// Whether a trident will return to the entity.
        return-trident,
        /// Whether the container is private.
        container-private,
        /// Whether the entity is transforming.
        transforming,
        /// Whether the entity damages nearby mobs.
        damage-nearby-mobs,
        /// Whether the entity is swimming.
        swimming,
        /// Whether the entity has been bribed.
        bribed,
        /// Whether the entity is pregnant.
        pregnant,
        /// Whether the entity is laying an egg.
        laying-egg,
        /// Whether a passenger can pick up the entity.
        passenger-can-pick,
        /// Whether the entity is transitioning to sitting.
        transition-sitting,
        /// Whether the entity is eating.
        eating,
        /// Whether the entity is laying down.
        laying-down,
        /// Whether the entity is sneezing.
        sneezing,
        /// Whether the entity is trusting.
        trusting,
        /// Whether the entity is rolling.
        rolling,
        /// Whether the entity is scared.
        scared,
        /// Whether the entity is in scaffolding.
        in-scaffolding,
        /// Whether the entity is over scaffolding.
        over-scaffolding,
        /// Whether the entity is descending through a block.
        descend-through-block,
        /// Whether the entity is blocking.
        blocking,
        /// Whether the entity is transitioning to blocking.
        transition-blocking,
        /// Whether the entity is blocked using a shield.
        blocked-using-shield,
        /// Whether the entity is blocked using a damaged shield.
        blocked-using-damaged-shield,
        /// Whether the entity is sleeping.
        sleeping,
        /// Whether the entity wants to wake up.
        wants-to-wake,
        /// Whether the entity shows interest in trading.
        trade-interest,
        /// Whether the entity can break doors.
        door-breaker,
        /// Whether the entity is breaking an obstruction.
        breaking-obstruction,
        /// Whether the entity can open doors.
        door-opener,
        /// Whether the entity is a captain (raid).
        captain,
        /// Whether the entity is stunned.
        stunned,
        /// Whether the entity is roaring.
        roaring,
        /// Whether the entity has a delayed attack.
        delayed-attack,
        /// Whether the entity is avoiding mobs.
        avoiding-mobs,
        /// Whether the entity is avoiding a block.
        avoiding-block,
        /// Whether the entity is facing a target for a ranged attack.
        facing-target-to-range-attack,
        /// Whether the entity is hidden when invisible.
        hidden-when-invisible,
        /// Whether the entity is in a UI.
        in-ui,
        /// Whether the entity is stalking.
        stalking,
        /// Whether the entity is emoting.
        emoting,
        /// Whether the entity is celebrating.
        celebrating,
        /// Whether the entity is admiring (piglin).
        admiring,
        /// Whether the entity is celebrating a special event.
        celebrating-special,
        /// Whether the entity is out of control.
        out-of-control,
        /// Whether the entity is performing a ram attack.
        ram-attack,
        /// Whether the entity is playing dead.
        playing-dead,
        /// Whether the entity is in an ascending block.
        in-ascending-block,
        /// Whether the entity is over a descending block.
        over-descending-block,
        /// Whether the entity is croaking (frog).
        croaking,
        /// Whether the entity is digesting a mob.
        digest-mob,
        /// Whether the entity has a jump goal.
        jump-goal,
        /// Whether the entity is emerging.
        emerging,
        /// Whether the entity is sniffing.
        sniffing,
        /// Whether the entity is digging.
        digging,
        /// Whether the entity is performing a sonic boom.
        sonic-boom,
        /// Whether the entity has a dash timeout.
        has-dash-timeout,
        /// Whether the entity is pushed towards the closest space.
        push-towards-closest-space,
        /// Whether the entity is scenting.
        scenting,
        /// Whether the entity is rising.
        rising,
        /// Whether the entity is feeling happy.
        feeling-happy,
        /// Whether the entity is searching.
        searching,
        /// Whether the entity is crawling.
        crawling,
        /// Whether the entity's body rotation is blocked.
        body-rotation-blocked,
        /// Whether the entity is rendered when invisible.
        render-when-invisible,
        /// Whether the entity's body rotation is axis-aligned.
        body-rotation-axis-aligned,
        /// Whether the entity is collidable.
        collidable,
        /// Whether the entity is air-controlled via WASD.
        wasd-air-controlled,
        /// Whether only the server can authorize a dismount.
        does-server-auth-only-dismount,
        /// Whether the body rotation always follows the head.
        body-rotation-always-follows-head,
        /// Whether the entity can use vertical movement actions.
        can-use-vertical-movement-action,
        /// Whether rotation is locked to the vehicle.
        rotation-locked-to-vehicle,
    }

    /// Represents a specific version of the Minecraft Java Edition protocol.
    enum java-minecraft-version {
        v-1-7-2,
        v-1-7-6,
        v-1-8,
        v-1-9,
        v-1-9-1,
        v-1-9-2,
        v-1-9-3,
        v-1-10,
        v-1-11,
        v-1-11-1,
        v-1-12,
        v-1-12-1,
        v-1-12-2,
        v-1-13,
        v-1-13-1,
        v-1-13-2,
        v-1-14,
        v-1-14-1,
        v-1-14-2,
        v-1-14-3,
        v-1-14-4,
        v-1-15,
        v-1-15-1,
        v-1-15-2,
        v-1-16,
        v-1-16-1,
        v-1-16-2,
        v-1-16-3,
        v-1-16-4,
        v-1-17,
        v-1-17-1,
        v-1-18,
        v-1-18-2,
        v-1-19,
        v-1-19-1,
        v-1-19-3,
        v-1-19-4,
        v-1-20,
        v-1-20-2,
        v-1-20-3,
        v-1-20-5,
        v-1-21,
        v-1-21-2,
        v-1-21-4,
        v-1-21-5,
        v-1-21-6,
        v-1-21-7,
        v-1-21-9,
        v-1-21-11,
        v-26-1,
        v-26-2,
        unknown,
    }

    /// Represents a specific version of the Minecraft Bedrock Edition protocol.
    enum bedrock-minecraft-version {
        v-1-21,
        v-1-26-30,
        unknown,
    }

    /// Represents settings for a Java Edition player.
    record java-player-settings {
        /// The player's preferred language (e.g., \"en_us\").
        locale: string,
        /// The maximum distance at which chunks are rendered.
        view-distance: u8,
        /// The player's chat visibility settings.
        chat-mode: chat-mode,
        /// Whether chat colors are enabled.
        chat-colors: bool,
        /// The player's skin configuration options.
        skin-parts: skin-parts,
        /// The player's dominant hand (left or right).
        main-hand: hand,
        /// Whether text filtering is enabled.
        text-filtering: bool,
        /// Whether the player wants to appear in the server list.
        server-listing: bool,
    }

    /// The chat visibility settings for a player.
    enum chat-mode {
        /// Chat is fully enabled.
        enabled,
        /// Only system messages and commands are shown.
        commands-only,
        /// Chat is completely hidden.
        hidden,
    }

    /// Represents the operating system of a Bedrock Edition client.
    enum bedrock-device-os {
        android,
        ios,
        osx,
        amazon,
        gear-vr,
        holo-lens,
        windows-10,
        win-32,
        dedicated,
        tv-os,
        playstation,
        nintendo,
        xbox,
        windows-phone,
        linux,
        /// Fallback for unrecognized operating systems.
        unknown,
    }

    /// Represents the input mode used by a Bedrock Edition client.
    enum bedrock-input-mode {
        /// Unknown input mode.
        unknown,
        /// Mouse and keyboard.
        mouse,
        /// Touch screen.
        touch,
        /// Game controller.
        game-pad,
        /// Motion-based controller.
        motion-controller,
    }

    /// Represents the UI profile used by a Bedrock Edition client.
    enum bedrock-ui-profile {
        /// Classic desktop UI.
        classic,
        /// Pocket/Mobile optimized UI.
        pocket,
        /// Unknown UI profile.
        unknown,
    }

    /// Represents the graphics mode used by a Bedrock Edition client.
    enum bedrock-graphics-mode {
        simple,
        fancy,
        ray-traced,
        unknown,
    }

    /// Represents settings and client data for a Bedrock Edition player.
    record bedrock-player-settings {
        /// The client's specific game version string.
        game-version: string,
        /// The operating system of the client device.
        device-os: bedrock-device-os,
        /// A unique identifier for the client device.
        device-id: string,
        /// The model name of the client device.
        device-model: string,
        /// The player's preferred language code (e.g., \"en_US\").
        language-code: string,
        /// The input mode currently used by the player.
        current-input-mode: bedrock-input-mode,
        /// The default input mode for the client device.
        default-input-mode: bedrock-input-mode,
        /// The UI layout profile used by the client.
        ui-profile: bedrock-ui-profile,
        /// The current GUI scale setting.
        gui-scale: s32,
        /// Whether the player is in Editor mode.
        is-editor-mode: bool,
        /// The maximum view distance the client supports.
        max-view-distance: s32,
        /// The memory tier of the client device (indicates performance level).
        memory-tier: s32,
        /// The graphics mode used by the client.
        graphics-mode: bedrock-graphics-mode,
        /// The player's unique PlayFab identifier.
        playfab-id: string,
        /// A random 64-bit ID generated by the client.
        client-random-id: s64,
        /// Platform-specific offline identifier.
        platform-offline-id: string,
        /// Platform-specific online identifier.
        platform-online-id: string,
        /// The unique ID of the player's current skin.
        skin-id: string,
        /// The model arm size (e.g., \"wide\" or \"slim\").
        arm-size: string,
        /// Whether the player is using a Character Creator (Persona) skin.
        is-persona-skin: bool,
        /// Whether the skin is a premium (paid) skin.
        is-premium-skin: bool,
        /// Whether the skin is from a trusted source.
        is-trusted-skin: bool,
    }

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

        /// Transfers the player to another server.
        transfer: func (host: string, port: u16);

        // Status Effects

        /// Gives a status effect to the player.
        add-effect: func(effect: status-effect-instance);
        /// Removes a status effect from the player.
        remove-effect: func(effect: status-effect-type);
        /// Clears all active status effects from the player.
        clear-effects: func();
        /// Checks if a status effect is currently applied to the player.
        has-effect: func(effect: status-effect-type) -> bool;
        /// Returns the status effect instance applied to the player, if any.
        get-effect: func(effect: status-effect-type) -> option<status-effect-instance>;
        /// Returns all status effects currently applied to the player.
        get-active-effects: func() -> list<status-effect-instance>;

        // Health & Damage

        /// Heals the player by a specified amount.
        heal: func(amount: f32);
        /// Deals damage to the player by a specified amount.
        damage: func(amount: f32);
        /// Kills the player instantly.
        kill: func();

        // Cooldowns

        /// Starts an item cooldown for a specific item group name.
        start-cooldown: func(group: string, duration-ticks: s32);
        /// Returns the cooldown progress (0.0 to 1.0) for a specific item group.
        get-cooldown: func(group: string) -> f32;
        /// Checks if a specific item group is currently on cooldown.
        is-on-cooldown: func(group: string) -> bool;

        // Abilities & Flight

        /// Sets whether the player is allowed to fly.
        set-allow-flight: func(allowed: bool);
        /// Sets the player's flying speed.
        set-fly-speed: func(speed: f32);
        /// Sets the player's walking speed.
        set-walk-speed: func(speed: f32);
        /// Sets whether the player is invulnerable to damage.
        set-invulnerable: func(invulnerable: bool);

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

        /// Sets the item in the specified hand.
        set-item-in-hand: func (hand: hand, stack: option<item-stack>);
        /// Sets the item in the specified inventory slot.
        set-inventory-item: func (slot: u8, stack: 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>;

        /// Updates the player's skin textures.
        /// Note: this only updates the fields, it doesn't reload the skin.
        set-skin: func(skin: player-skin);

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

        // Per-Player Environment & Overrides

        /// Overrides the time of day shown to this player.
        set-player-time: func(time: u64, relative: bool);
        /// Resets the player's time to sync with the server world time.
        reset-player-time: func();
        /// Returns the custom time set for this player, if any.
        get-player-time: func() -> option<u64>;
        /// Checks if the custom player time is relative to the world time.
        is-player-time-relative: func() -> bool;

        /// Overrides the weather condition shown to this player.
        set-player-weather: func(weather: player-weather);
        /// Resets the player's weather to match the server world weather.
        reset-player-weather: func();
        /// Returns the custom weather set for this player, if any.
        get-player-weather: func() -> option<player-weather>;

        /// Sets the position where the player's compass points.
        set-compass-target: func(pos: position);
        /// Returns the position where the player's compass currently points.
        get-compass-target: func() -> position;

        /// Sets the player's custom respawn / bed location.
        set-respawn-location: func(pos: position);
        /// Returns the player's custom respawn / bed location, if set.
        get-respawn-location: func() -> option<position>;

        /// Hides another player from this player's view (vanish).
        hide-player: func(other: player);
        /// Shows a previously hidden player to this player.
        show-player: func(other: player);
        /// Checks if this player can see another specified player.
        can-see: func(other: player) -> bool;
        /// Checks if this player can see another specified player.
        can-see-player: func(other: player) -> bool;

        /// Sets the tab list ping / latency indicator in milliseconds.
        set-tab-list-ping: func(latency-ms: s32);

        /// Sets a client-side item cooldown overlay.
        set-item-cooldown: func(item-id: string, ticks: s32);
        /// Returns the remaining cooldown ticks for an item, if active.
        get-item-cooldown: func(item-id: string) -> option<s32>;
        /// Checks if an item is currently on cooldown.
        has-item-cooldown: func(item-id: string) -> bool;

        /// Raycasts from the player's eyes to find the block being targeted.
        get-target-block: func(max-distance: u32) -> option<position>;
        /// Launches a projectile from the player's eyes in their line of sight.
        launch-projectile: func(%type: projectile-type) -> option<entity>;

        /// Returns a Java-specific player handle, if the player is connected via Java Edition.
        ///
        /// This allows access to Java-exclusive features like sending specific packets
        /// or retrieving the client brand.
        as-java: func() -> option<java-player>;

        /// Returns a Bedrock-specific player handle, if the player is connected via Bedrock Edition.
        ///
        /// This allows access to Bedrock-exclusive features like custom forms
        /// or detailed device information.
        as-bedrock: func() -> option<bedrock-player>;
    }

    /// Represents a resource pack sent to a Java Edition player.
    record java-resource-pack {
        /// Unique identifier for the resource pack.
        id: uuid,
        /// The URL to the resource pack file.
        url: string,
        /// The SHA1 hash (40-character hex string) of the pack.
        hash: string,
        /// Whether the player is forced to accept the pack.
        forced: bool,
        /// Optional prompt message displayed in the pack acceptance screen.
        prompt-message: option<text-component>,
    }

    /// Represents an individual Bedrock Edition resource pack entry.
    record bedrock-resource-pack-entry {
        /// Unique identifier for the Bedrock pack.
        id: uuid,
        /// Version string of the Bedrock pack (e.g., "1.0.0").
        version: string,
        /// Size of the pack in bytes.
        size: u64,
        /// Download URL for remote Bedrock packs.
        download-url: string,
        /// Optional encryption content key for encrypted packs.
        content-key: option<string>,
        /// Optional sub-pack name inside the archive.
        sub-pack-name: option<string>,
        /// Optional content identifier.
        content-id: option<string>,
        /// Whether the pack contains client scripts.
        has-scripts: bool,
        /// Whether the pack is marked as an addon pack.
        addon-pack: bool,
        /// Whether Ray Tracing / RTX features are enabled for the pack.
        rtx-enabled: bool,
    }

    /// Represents the resource packs information payload sent to Bedrock clients.
    record bedrock-resource-packs-info {
        /// If true, players cannot join without accepting packs.
        required: bool,
        /// Whether the server offers addon packs.
        has-addon-packs: bool,
        /// Whether any of the packs contain client scripts.
        has-scripts: bool,
        /// Whether vibrant visuals should be forced disabled.
        is-vibrant-visuals-force-disabled: bool,
        /// World template ID, if any.
        world-template-id: option<uuid>,
        /// World template version, if any.
        world-template-version: option<string>,
        /// List of resource packs to send to the player.
        packs: list<bedrock-resource-pack-entry>,
    }

    /// A handle to a player connected via the Java Edition.
    resource java-player {
        /// Returns the Minecraft Java Edition version of the player.
        get-version: func() -> java-minecraft-version;

        /// Returns the brand of the player's client (e.g., \"vanilla\", \"fabric\").
        get-brand: func() -> string;

        /// Returns the server address the player used to connect.
        get-server-address: func() -> string;

        /// Returns the player's configuration settings.
        get-settings: func() -> java-player-settings;

        /// Sends a Java-specific clientbound packet to the player.
        send-packet: func(packet: java-packet);

        /// Sends a custom payload packet (plugin message) to the player.
        send-custom-payload: func(channel: string, data: list<u8>);

        /// Shows a dialog to the player.
        show-dialog: func(dialog: dialog);

        /// Clears any currently shown dialog for the player.
        clear-dialog: func();

        /// Returns the Java scoreboard handle for this player.
        get-scoreboard: func() -> scoreboard;

        /// Resets the player's custom Java scoreboard back to the world scoreboard.
        reset-scoreboard: func();

        /// Sends a resource pack to the Java player.
        send-resource-pack: func(pack: java-resource-pack);

        /// Removes a specific resource pack by UUID for the Java player.
        remove-resource-pack: func(id: uuid);

        /// Clears all custom resource packs for the Java player.
        clear-resource-packs: func();
    }

    /// A handle to a player connected via the Bedrock Edition.
    resource bedrock-player {
        /// Returns the Minecraft Bedrock Edition version of the player.
        get-version: func() -> bedrock-minecraft-version;

        /// Returns the player's configuration settings.
        get-settings: func() -> bedrock-player-settings;

        /// Returns whether a specific Bedrock-only ability is enabled for the player.
        get-ability: func(ability: bedrock-ability) -> bool;

        /// Sets whether a specific Bedrock-only ability is enabled for the player.
        set-ability: func(ability: bedrock-ability, value: bool);

        /// Returns whether a specific Bedrock-only status flag is enabled for the player.
        ///
        /// Status flags control things like whether the player is on fire, sneaking,
        /// sprinting, or has specific visual effects.
        get-status-flag: func(flag: bedrock-status-flag) -> bool;

        /// Sets whether a specific Bedrock-only status flag is enabled for the player.
        ///
        /// This can be used to manually trigger client-side visual states.
        set-status-flag: func(flag: bedrock-status-flag, value: bool);

        /// Sends a Bedrock-specific clientbound packet to the player.
        send-packet: func(packet: bedrock-packet);

        /// Opens a Bedrock custom form for the player.
        open-form: func(form: form) -> u32;

        /// Returns the Bedrock scoreboard handle for this player.
        get-scoreboard: func() -> bedrock-scoreboard;

        /// Resets the player's custom Bedrock scoreboard back to the world scoreboard.
        reset-scoreboard: func();

        /// Sends resource packs information to the Bedrock player.
        send-resource-packs-info: func(info: bedrock-resource-packs-info);
    }

    /// Returns a list of all players in a specific world.
    get-world-players: func(world-ref: %world) -> list<player>;
}