/// Represents a player connected to the Minecraft server.
interface player {
    use common.{hand, position, game-mode, block-pos};
    use item-stack.{item-stack};
    use %world.{%world, entity, ray-trace-block-result, ray-trace-entity-result};
    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};
    use advancement.{advancement-progress};
    use damage-types.{damage-type};
    use statistics.{statistic-category, custom-statistic};
    use inventory.{inventory, player-inventory};
    use sounds.{sound, sound-category};
    use particles.{particle};
    use entity-statuses.{entity-status};

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

    /// Types of clientbound game events.
    enum client-game-event {
        no-respawn-block-available,
        begin-raining,
        end-raining,
        change-game-mode,
        win-game,
        demo-event,
        arrow-hit-player,
        rain-level-change,
        thunder-level-change,
        play-pufferfish-string-sound,
        play-elder-guardian-mob-appearance,
        enabled-respawn-screen,
        limited-crafting,
        start-waiting-chunks,
    }

    /// Built-in known server link types displayed in the client Escape pause menu.
    enum known-server-link {
        bug-report,
        community-guidelines,
        support,
        status,
        feedback,
        community,
        website,
        forums,
        news,
        announcements,
    }

    /// Label for a server link: either a built-in standard link type or a custom text component.
    variant server-link-label {
        known(known-server-link),
        custom(text-component),
    }

    /// Represents a server link entry with a label and destination URL.
    record server-link {
        label: server-link-label,
        url: string,
    }

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

    /// Protocol-level disconnect reasons for Minecraft Bedrock Edition.
    enum bedrock-disconnect-reason {
        unknown,
        cant-connect-no-internet,
        no-permissions,
        unrecoverable-error,
        third-party-blocked,
        third-party-no-internet,
        third-party-bad-ip,
        third-party-no-server-or-server-locked,
        version-mismatch,
        skin-issue,
        invite-session-not-found,
        edu-level-settings-missing,
        local-server-not-found,
        legacy-disconnect,
        user-leave-game-attempted,
        platform-locked-skins-error,
        realms-world-unassigned,
        realms-server-cant-connect,
        realms-server-hidden,
        realms-server-disabled-beta,
        realms-server-disabled,
        cross-platform-disabled,
        cant-connect,
        session-not-found,
        client-settings-incompatible-with-server,
        server-full,
        invalid-platform-skin,
        edition-version-mismatch,
        edition-mismatch,
        level-newer-than-exe-version,
        no-fail-occurred,
        banned-skin,
        timeout,
        server-not-found,
        outdated-server,
        outdated-client,
        no-premium-platform,
        multiplayer-disabled,
        no-wifi,
        world-corruption,
        no-reason,
        disconnected,
        invalid-player,
        logged-in-other-location,
        server-id-conflict,
        not-allowed,
        not-authenticated,
        invalid-tenant,
        unknown-packet,
        unexpected-packet,
        invalid-command-request-packet,
        host-suspended,
        login-packet-no-request,
        login-packet-no-cert,
        missing-client,
        kicked,
        kicked-for-exploit,
        kicked-for-idle,
        resource-pack-problem,
        incompatible-pack,
        out-of-storage,
        invalid-level,
        disconnect-packet,
        block-mismatch,
        invalid-heights,
        invalid-widths,
        connection-lost,
        zombie-connection,
        shutdown,
        reason-not-set,
        loading-state-timeout,
        resource-pack-loading-failed,
        searching-for-session-loading-screen-failed,
        nether-net-protocol-version,
        subsystem-status-error,
        empty-auth-from-discovery,
        empty-url-from-discovery,
        expired-auth-from-discovery,
        unknown-signal-service-sign-in-failure,
        xbl-join-lobby-failure,
        unspecified-client-instance-disconnection,
        nether-net-session-not-found,
        nether-net-create-peer-connection,
        nether-net-ice,
        nether-net-connect-request,
        nether-net-connect-response,
        nether-net-negotiation-timeout,
        nether-net-inactivity-timeout,
        stale-connection-being-replaced,
        realms-session-not-found,
        bad-packet,
        nether-net-failed-to-create-offer,
        nether-net-failed-to-create-answer,
        nether-net-failed-to-set-local-description,
        nether-net-failed-to-set-remote-description,
        nether-net-negotiation-timeout-waiting-for-response,
        nether-net-negotiation-timeout-waiting-for-accept,
        nether-net-incoming-connection-ignored,
        nether-net-signaling-parsing-failure,
        nether-net-signaling-unknown-error,
        nether-net-signaling-unicast-delivery-failed,
        nether-net-signaling-broadcast-delivery-failed,
        nether-net-signaling-generic-delivery-failed,
        editor-mismatch-editor-world,
        editor-mismatch-vanilla-world,
        world-transfer-not-primary-client,
        request-server-shutdown,
        client-game-setup-cancelled,
        client-game-setup-failed,
        no-venue,
        nether-net-signaling-signin-failed,
        session-access-denied,
        service-signin-issue,
        nether-net-no-signaling-channel,
        nether-net-not-logged-in,
        nether-net-client-signaling-error,
        sub-client-login-disabled,
        deep-link-trying-to-open-demo-world-while-signed-in,
        async-join-task-denied,
        realms-timeline-required,
        guest-without-host,
        failed-to-join-experience,
        nether-net-data-channel-closed,
        discovery-environment-mismatch,
        host-without-keys,
        host-signed-out,
        script-watchdog-exception,
        script-memory-limit-exceeded,
        storage-low-during-gameplay,
        storage-full-during-gameplay,
        level-storage-corruption,
        edition-mismatch-vanilla-to-edu,
        edition-mismatch-edu-to-vanilla,
        editor-mismatch-editor-to-vanilla,
        editor-mismatch-vanilla-to-editor,
        deny-listed,
        nonce-missing,
        nonce-not-found,
        nonce-expired,
        nonce-not-valid,
        host-disconnected,
        editor-join-intent-policy-failure,
        nether-net-identity-not-allowed,
        invalid-name,
        expired-token,
        host-accepts-no-type-of-auth,
        not-authenticated-fast-fail,
        editor-not-allowed,
    }

    /// Policy for tearing down the player's network connection.
    enum socket-teardown-policy {
        /// Send the disconnect packet and gracefully close the connection.
        graceful,
        /// Send the disconnect packet and close the socket immediately.
        immediate-close,
        /// Terminate the connection immediately without sending any disconnect packet.
        drop-connection,
    }

    /// Options for disconnecting a Java Edition player.
    record java-kick-options {
        /// The formatted text component displayed on the Java disconnect screen.
        reason: text-component,
        /// Whether to log the kick in the server console (default: true).
        log-to-console: bool,
        /// How the connection is closed (default: graceful).
        teardown-policy: socket-teardown-policy,
    }

    /// Options for disconnecting a Bedrock Edition player.
    record bedrock-kick-options {
        /// Protocol level disconnect code (default: kicked).
        reason: bedrock-disconnect-reason,
        /// Message displayed on the Bedrock disconnect screen (default: "").
        message: string,
        /// Whether to suppress the disconnect message on the client screen (default: false).
        skip-message: bool,
        /// Filtered message string for safety/parental filters (default: "").
        filtered-message: string,
        /// Whether to log the kick in the server console (default: true).
        log-to-console: bool,
        /// How the connection is closed (default: graceful).
        teardown-policy: socket-teardown-policy,
    }

    /// Options for banning a player.
    record ban-player-options {
        /// Ban reason displayed to the player and stored in the ban list.
        reason: option<text-component>,
        /// Source or authority responsible for the ban (default: "Plugin").
        source: option<string>,
        /// Ban expiration in RFC-3339 format, if temporary.
        expires-at-utc: option<string>,
        /// Ban duration in seconds from now, if temporary.
        duration-seconds: option<u64>,
        /// Whether to immediately kick the player if currently online (default: true).
        kick-if-online: bool,
        /// Whether to log the ban action to the server console (default: true).
        log-to-console: bool,
    }

    /// Options for banning an IP address.
    record ban-ip-options {
        /// Ban reason stored in the IP ban list.
        reason: option<text-component>,
        /// Source or authority responsible for the ban (default: "Plugin").
        source: option<string>,
        /// Ban expiration in RFC-3339 format, if temporary.
        expires-at-utc: option<string>,
        /// Ban duration in seconds from now, if temporary.
        duration-seconds: option<u64>,
        /// Whether to immediately kick all online players with this IP (default: true).
        kick-matching-players: bool,
        /// Whether to log the IP ban action to the server console (default: true).
        log-to-console: 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);
        /// Deletes a signed chat message from the player's chat window using its 256-byte signature.
        delete-message-by-signature: func (signature: list<u8>);
        /// Deletes a signed chat message from the player's chat window using its signature cache ID.
        delete-message-by-id: func (signature-id: s32);
        /// 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);

        // Camera & Spectating

        /// Sets the player's camera to view from the perspective of another entity.
        /// If `entity` is `none`, the camera is reset back to the player.
        set-camera: func (entity: option<entity>);
        /// Sets the player's camera to view from the perspective of an entity with the given entity ID.
        /// If `entity-id` is the player's own entity ID, the camera is reset back to the player.
        set-camera-entity-id: func (entity-id: u32);
        /// Gets the entity ID of the entity that the player's camera is currently attached to,
        /// or the player's own entity ID if the camera has not been overridden.
        get-camera-entity-id: func () -> u32;
        /// Resets the player's camera back to their own perspective.
        reset-camera: func ();

        // Audio & Particles

        /// Plays a sound effect for this player at their current location.
        play-sound: func(sound: sound, category: sound-category, volume: f32, pitch: f32);
        /// Plays a sound effect for this player at a specific location.
        play-sound-at: func(pos: position, sound: sound, category: sound-category, volume: f32, pitch: f32);
        /// Stops a sound effect from playing for this player.
        stop-sound: func(sound: option<sound>, category: option<sound-category>);

        /// Plays a custom resource pack sound identifier for this player at their current location.
        play-custom-sound: func(sound-name: string, category: sound-category, volume: f32, pitch: f32);
        /// Plays a custom resource pack sound identifier for this player at a specific location.
        play-custom-sound-at: func(pos: position, sound-name: string, category: sound-category, volume: f32, pitch: f32);
        /// Stops a custom sound identifier from playing for this player.
        stop-custom-sound: func(sound-name: option<string>, category: option<sound-category>);

        /// Spawns particles visible only to this player.
        spawn-particles: func(particle: particle, pos: position, count: u32, offset: position, max-speed: f32);

        // Visuals & Client Overrides

        /// Sends a temporary fake block change to the player's client without modifying the server world.
        send-block-change: func(pos: block-pos, block-id: u16);
        /// Resets a temporary fake block change by resending the actual world block at that position.
        reset-block-change: func(pos: block-pos);

        /// Sends a hurt / damage-tilt animation to the player's client (causes screen shake in the given yaw direction).
        send-hurt-animation: func(yaw: f32);

        /// Opens a written book interface for the player from the specified hand.
        open-book: func(hand: hand);
        /// Forces the sign text editor to open for the player at the specified sign block position.
        open-sign-editor: func(pos: block-pos, is-front-text: bool);

        // Velocity & Physics

        /// Sets the player's velocity / motion vector.
        set-velocity: func(velocity: position);
        /// Applies directional knockback impulse to the player.
        apply-knockback: func(strength: f64, x: f64, z: f64);

        // Movement Lock & Freezing

        /// Sets whether the player's movement is locked (frozen in place) for cutscenes and NPC dialogues.
        set-movement-locked: func(locked: bool);
        /// Returns whether the player's movement is currently locked.
        is-movement-locked: func() -> bool;

        /// Sets the number of freeze ticks on the player (controlling the powdered snow / frostbite screen vignette).
        set-freeze-ticks: func(ticks: s32);
        /// Returns the current number of freeze ticks on the player.
        get-freeze-ticks: func() -> s32;

        /// Sends custom server links to the player (displayed in the client Esc pause menu in 1.21+).
        set-server-links: func(links: list<server-link>);

        // 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>);
        /// Forces the player to respawn.
        respawn: func ();

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

        /// Bans the player with the specified options.
        ban: func (options: ban-player-options);
        /// Bans the player's IP address with the specified options.
        ban-ip: func (options: ban-ip-options);

        /// 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 with a damage type.
        damage: func(amount: f32, damage-type: damage-type);
        /// Kills the player instantly.
        kill: func();

        // Statistics

        /// Gets the value of a statistic for this player in the given category and ID.
        get-statistic: func(category: statistic-category, stat-id: s32) -> s32;
        /// Sets the value of a statistic for this player in the given category and ID.
        set-statistic: func(category: statistic-category, stat-id: s32, value: s32);
        /// Increments the value of a statistic for this player in the given category and ID.
        increment-statistic: func(category: statistic-category, stat-id: s32, amount: s32);

        /// Gets the value of a custom statistic for this player.
        get-custom-statistic: func(stat: custom-statistic) -> s32;
        /// Sets the value of a custom statistic for this player.
        set-custom-statistic: func(stat: custom-statistic, value: s32);
        /// Increments the value of a custom statistic for this player.
        increment-custom-statistic: func(stat: custom-statistic, amount: s32);

        /// Sends the player's updated statistics packet to the client.
        send-stats: func();

        /// Gets the team name that this player belongs to on their active scoreboard, if any.
        get-team: func() -> option<string>;

        // 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 player's inventory handle for managing main storage, armor, and equipment.
        get-inventory: func () -> player-inventory;
        /// Returns the player's ender chest inventory handle.
        get-ender-chest: func () -> 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>);

        // Ender Chest Inventory

        /// Returns the item in the specified ender chest slot (0-26).
        get-ender-chest-item: func (slot: u8) -> option<item-stack>;
        /// Sets the item in the specified ender chest slot (0-26).
        set-ender-chest-item: func (slot: u8, stack: option<item-stack>);
        /// Clears all items from the player's ender chest.
        clear-ender-chest: func ();
        /// Opens the player's ender chest inventory screen for them.
        open-ender-chest: func ();

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

        /// Performs a ray-trace from the player's eye position in looking direction to find the targeted block.
        ray-trace-block: func(max-distance: f64, include-fluids: bool) -> option<ray-trace-block-result>;

        /// Performs a ray-trace from the player's eye position in looking direction to find the targeted entity.
        ray-trace-entity: func(max-distance: f64) -> option<ray-trace-entity-result>;

        /// Returns the entity currently targeted in the looking direction within the specified distance.
        get-target-entity: func(max-distance: f64) -> option<entity>;

        /// Raycasts from the player's eyes to find the block being targeted.
        get-target-block: func(max-distance: u32) -> option<position>;

        /// Performs a raycast from the player's eyes to find the exact block and face being targeted.
        get-target-block-exact: func(max-distance: f64, include-fluids: bool) -> option<ray-trace-block-result>;
        /// Launches a projectile from the player's eyes in their line of sight.
        launch-projectile: func(%type: projectile-type) -> option<entity>;

        // Advancements

        /// Returns the progress of the specified advancement for this player, if the advancement exists.
        get-advancement-progress: func(advancement-id: string) -> option<advancement-progress>;

        /// Awards a specific criterion of an advancement to the player.
        /// Returns true if the criterion was successfully awarded (was not already completed).
        award-advancement-criterion: func(advancement-id: string, criterion: string) -> bool;

        /// Revokes a specific criterion of an advancement from the player.
        /// Returns true if the criterion was successfully revoked (was previously completed).
        revoke-advancement-criterion: func(advancement-id: string, criterion: string) -> bool;

        /// Awards all criteria of the specified advancement to the player.
        /// Returns true if any criterion was newly awarded.
        award-advancement: func(advancement-id: string) -> bool;

        /// Revokes all criteria of the specified advancement from the player.
        /// Returns true if any criterion was newly revoked.
        revoke-advancement: func(advancement-id: string) -> bool;

        /// Checks whether the player has completed the specified advancement.
        has-advancement: func(advancement-id: string) -> bool;

        /// Returns a list of all advancement IDs completed by this player.
        get-completed-advancements: func() -> list<string>;

        /// Returns the ID of the currently selected advancement tab for this player, if any.
        get-selected-advancement-tab: func() -> option<string>;

        /// Sets the selected advancement tab for this player (must be a root advancement ID).
        set-selected-advancement-tab: func(tab-id: option<string>);

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

        /// Kicks the Java player with the specified options.
        kick: func(options: java-kick-options);

        /// Sends a clientbound GameEvent packet to the Java player.
        send-game-event: func(event: client-game-event, value: f32);

        /// Sends an entity status / animation event packet to the Java player for a specific entity ID.
        send-entity-status: func(entity-id: s32, status: entity-status);
    }

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

        /// Kicks the Bedrock player with the specified options.
        kick: func(options: bedrock-kick-options);
    }

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